класс 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), и фактически может быть коллекцией (например, массивом, хэшем, множеством, диапазоном и т. д.). Эта коллекция может, в свою очередь, содержать вложенные объекты, включая коллекции, на любой глубине; эти объекты также должны быть сериализуемы. См. Иерархические значения.

Транзакции

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

Блок, переданный с вызовом метода 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 methods в возвращаемой иерархии объектов.

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

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

Используйте метод 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