класс PStore

PStore реализует механизм сохранения данных в файле на основе Hash. Пользовательский код может сохранять иерархии объектов Ruby (значения) в хранилище по имени (ключи). Иерархия объектов может состоять всего из одного объекта. Пользовательский код может позже считывать значения из хранилища или даже обновлять данные по мере необходимости.

Транзакционное поведение гарантирует, что все изменения происходят успешно или терпят неудачу вместе. Это можно использовать для обеспечения того, что хранилище данных не останется в переходном состоянии, где некоторые значения были обновлены, а другие — нет.

За кулисами объекты Ruby сохраняются в файл хранилища с помощью Marshal. Это влечёт за собой обычные ограничения. Например, объекты Proc не могут быть сохраняемы.

Здесь три важных понятия (подробности по ссылкам):

• Хранилище: хранилище — это экземпляр PStore.

• Элементы: хранилище подобно хэшу; каждый элемент — это ключ для сохранённого объекта.

• Транзакции: каждая транзакция — это набор предполагаемых изменений в хранилище; транзакция определяется в блоке, заданном при вызове PStore#transaction.

О примерах

Примеры на этой странице нуждаются в хранилище с известными свойствами. Они могут получить новое (и заполненное) хранилище, вызвав его таким образом:

example_store do |store|
  # Example code using store goes here.
end

Всё, что нам нужно знать о example_store, это то, что оно возвращает свежее хранилище с известной популяцией элементов; его реализация:

require 'pstore'
require 'tempfile'
# Yield a pristine store for use in examples.
def example_store
  # Create the store in a temporary file.
  Tempfile.create do |file|
    store = PStore.new(file)
    # Populate the store.
    store.transaction do
      store[:foo] = 0
      store[:bar] = 1
      store[:baz] = 2
    end
    yield store
  end
end

Хранилище

Содержимое хранилища хранится в файле, путь к которому указывается при создании хранилища (см. PStore.new). Объекты сохраняются и извлекаются с помощью модуля Marshal, что означает, что некоторые объекты не могут быть добавлены в хранилище; см. Marshal::dump.

Элементы

Хранилище может содержать любое количество элементов. Каждый элемент имеет ключ и значение, как и в хэше:

• Ключ: как и в хэше, ключ может быть (почти) любым объектом; см. Ключи хэша. Для простоты можно использовать только символы или строки в качестве ключей.

• Значение: значение может быть любым объектом, который может быть сохраняем Marshal (см. Marshal::dump), и фактически может быть коллекцией (например, массивом, хэшем, множеством, диапазоном и т. д.). Эта коллекция может, в свою очередь, содержать вложенные объекты, включая коллекции, на любой глубине; эти объекты также должны быть сохраняемы Marshal. См. Иерархические значения.

Транзакции

Блок транзакции

Блок, переданный при вызове метода transaction, содержит транзакцию, которая состоит из вызовов методов PStore, которые считывают или записывают данные в хранилище (то есть, все методы PStore, кроме transaction сам по себе, path и Pstore.new):

example_store do |store|
  store.transaction do
    store.keys # => [:foo, :bar, :baz]
    store[:bat] = 3
    store.keys # => [:foo, :bar, :baz, :bat]
  end
end

Выполнение транзакции откладывается до выхода из блока, и выполняется атомарно (все или ничего): либо все вызовы транзакции выполняются, либо ни один. Это поддерживает целостность хранилища.

Другой код в блоке (включая даже вызовы path и PStore.new) выполняется немедленно, а не откладывается.

Блок транзакции:

• Не может содержать вложенный вызов transaction.

• Является единственным контекстом, где разрешены методы, считывающие или записывающие данные в хранилище.

Как видно выше, изменения в транзакции производятся автоматически при выходе из блока. Блок может быть досрочно завершен вызовом метода commit или abort.

• Method commit вызывает обновление хранилища и завершает блок:

  example_store do |store|
    store.transaction do
      store.keys # => [:foo, :bar, :baz]
      store[:bat] = 3
      store.commit
      fail 'Cannot get here'
    end
    store.transaction do
      # Update was completed.
      store.keys # => [:foo, :bar, :baz, :bat]
    end
  end
  

• Method abort отбрасывает обновление хранилища и завершает блок:

  example_store do |store|
    store.transaction do
      store.keys # => [:foo, :bar, :baz]
      store[:bat] = 3
      store.abort
      fail 'Cannot get here'
    end
    store.transaction do
      # Update was not completed.
      store.keys # => [:foo, :bar, :baz]
    end
  end
  

Только чтение транзакций

По умолчанию транзакция позволяет как чтение, так и запись в хранилище:

store.transaction do
  # Read-write transaction.
  # Any code except a call to #transaction is allowed here.
end

Если аргумент read_only передан как true, разрешено только чтение:

store.transaction(true) do
  # Read-only transaction:
  # Calls to #transaction, #[]=, and #delete are not allowed here.
end

Иерархические значения

Значение элемента может быть простым объектом (как показано выше). Оно также может быть иерархией объектов, вложенных на любой глубине:

deep_store = PStore.new('deep.store')
deep_store.transaction do
  array_of_hashes = [{}, {}, {}]
  deep_store[:array_of_hashes] = array_of_hashes
  deep_store[:array_of_hashes] # => [{}, {}, {}]
  hash_of_arrays = {foo: [], bar: [], baz: []}
  deep_store[:hash_of_arrays] = hash_of_arrays
  deep_store[:hash_of_arrays]  # => {:foo=>[], :bar=>[], :baz=>[]}
  deep_store[:hash_of_arrays][:foo].push(:bat)
  deep_store[:hash_of_arrays]  # => {:foo=>[:bat], :bar=>[], :baz=>[]}
end

И помните, что вы можете использовать методы dig методов в возвращаемой иерархии объектов.

Работа с хранилищем

Создание хранилища

Используйте метод PStore.new для создания хранилища. Новое хранилище создаёт или открывает содержащий его файл:

store = PStore.new('t.store')

Изменение хранилища

Используйте метод []= для обновления или создания элемента:

example_store do |store|
  store.transaction do
    store[:foo] = 1 # Update.
    store[:bam] = 1 # Create.
  end
end

Используйте метод delete для удаления элемента:

example_store do |store|
  store.transaction do
    store.delete(:foo)
    store[:foo] # => nil
  end
end

Извлечение значений

Используйте метод fetch (разрешает значение по умолчанию) или [] (по умолчанию nil) для извлечения элемента:

example_store do |store|
  store.transaction do
    store[:foo]             # => 0
    store[:nope]            # => nil
    store.fetch(:baz)       # => 2
    store.fetch(:nope, nil) # => nil
    store.fetch(:nope)      # Raises exception.
  end
end

Запрос к хранилищу

Используйте метод key? для определения, существует ли данный ключ:

example_store do |store|
  store.transaction do
    store.key?(:foo) # => true
  end
end

Используйте метод keys для извлечения ключей:

example_store do |store|
  store.transaction do
    store.keys # => [:foo, :bar, :baz]
  end
end

Используйте метод path для получения пути к файлу, лежащему в основе хранилища; этот метод может быть вызван вне блока транзакции:

store = PStore.new('t.store')
store.path # => "t.store"

Безопасность транзакций

Для безопасности транзакций см.:

• Необязательный аргумент thread_safe в методе PStore.new.

• Атрибут ultra_safe.

Само собой разумеется, если вы храните ценные данные с помощью PStore, то время от времени следует делать резервную копию файла PStore.

Пример хранилища

require "pstore"

# A mock wiki object.
class WikiPage

  attr_reader :page_name

  def initialize(page_name, author, contents)
    @page_name = page_name
    @revisions = Array.new
    add_revision(author, contents)
  end

  def add_revision(author, contents)
    @revisions << {created: Time.now,
                   author: author,
                   contents: contents}
  end

  def wiki_page_references
    [@page_name] + @revisions.last[:contents].scan(/\b(?:[A-Z]+[a-z]+){2,}/)
  end

end

# Create a new wiki page.
home_page = WikiPage.new("HomePage", "James Edward Gray II",
                         "A page about the JoysOfDocumentation..." )

wiki = PStore.new("wiki_pages.pstore")
# Update page data and the index together, or not at all.
wiki.transaction do
  # Store page.
  wiki[home_page.page_name] = home_page
  # Create page index.
  wiki[:wiki_index] ||= Array.new
  # Update wiki index.
  wiki[:wiki_index].push(*home_page.wiki_page_references)
end

# Read wiki data, setting argument read_only to true.
wiki.transaction(true) do
  wiki.keys.each do |key|
    puts key
    puts wiki[key]
  end
end