класс 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.

• Метод 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
  

• Метод 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