diff options
Diffstat (limited to 'lib/pstore.rb')
| -rw-r--r-- | lib/pstore.rb | 578 |
1 files changed, 408 insertions, 170 deletions
diff --git a/lib/pstore.rb b/lib/pstore.rb index a46bcb84bc..57ecb0ef5c 100644 --- a/lib/pstore.rb +++ b/lib/pstore.rb @@ -10,89 +10,323 @@ require "digest" -# -# PStore implements a file based persistence mechanism based on a Hash. User -# code can store hierarchies of Ruby objects (values) into the data store file -# by name (keys). An object hierarchy may be just a single object. User code -# may later read values back from the data store or even update data, as needed. +# \PStore implements a file based persistence mechanism based on a Hash. +# User code can store hierarchies of Ruby objects (values) +# into the data store by name (keys). +# An object hierarchy may be just a single object. +# User code may later read values back from the data store +# or even update data, as needed. # # The transactional behavior ensures that any changes succeed or fail together. -# This can be used to ensure that the data store is not left in a transitory -# state, where some values were updated but others were not. +# This can be used to ensure that the data store is not left in a transitory state, +# where some values were updated but others were not. +# +# Behind the scenes, Ruby objects are stored to the data store file with Marshal. +# That carries the usual limitations. Proc objects cannot be marshalled, +# for example. +# +# There are three important concepts here (details at the links): +# +# - {Store}[rdoc-ref:PStore@The+Store]: a store is an instance of \PStore. +# - {Entries}[rdoc-ref:PStore@Entries]: the store is hash-like; +# each entry is the key for a stored object. +# - {Transactions}[rdoc-ref:PStore@Transactions]: each transaction is a collection +# of prospective changes to the store; +# a transaction is defined in the block given with a call +# to PStore#transaction. +# +# == About the Examples +# +# Examples on this page need a store that has known properties. +# They can get a new (and populated) store by calling thus: +# +# example_store do |store| +# # Example code using store goes here. +# end +# +# All we really need to know about +example_store+ +# is that it yields a fresh store with a known population of entries; +# its implementation: +# +# 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 +# +# == The Store +# +# The contents of the store are maintained in a file whose path is specified +# when the store is created (see PStore.new). +# The objects are stored and retrieved using +# module Marshal, which means that certain objects cannot be added to the store; +# see {Marshal::dump}[rdoc-ref:Marshal.dump]. +# +# == Entries +# +# A store may have any number of entries. +# Each entry has a key and a value, just as in a hash: +# +# - Key: as in a hash, the key can be (almost) any object; +# see {Hash Keys}[rdoc-ref:Hash@Hash+Keys]. +# You may find it convenient to keep it simple by using only +# symbols or strings as keys. +# - Value: the value may be any object that can be marshalled by \Marshal +# (see {Marshal::dump}[rdoc-ref:Marshal.dump]) +# and in fact may be a collection +# (e.g., an array, a hash, a set, a range, etc). +# That collection may in turn contain nested objects, +# including collections, to any depth; +# those objects must also be \Marshal-able. +# See {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values]. +# +# == Transactions +# +# === The Transaction Block +# +# The block given with a call to method #transaction# +# contains a _transaction_, +# which consists of calls to \PStore methods that +# read from or write to the store +# (that is, all \PStore methods except #transaction itself, +# #path, and 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 +# +# Execution of the transaction is deferred until the block exits, +# and is executed _atomically_ (all-or-nothing): +# either all transaction calls are executed, or none are. +# This maintains the integrity of the store. +# +# Other code in the block (including even calls to #path and PStore.new) +# is executed immediately, not deferred. +# +# The transaction block: +# +# - May not contain a nested call to #transaction. +# - Is the only context where methods that read from or write to +# the store are allowed. +# +# As seen above, changes in a transaction are made automatically +# when the block exits. +# The block may be exited early by calling method #commit or #abort. +# +# - Method #commit triggers the update to the store and exits the block: +# +# 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 discards the update to the store and exits the block: +# +# 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 +# +# === Read-Only Transactions +# +# By default, a transaction allows both reading from and writing to +# the store: +# +# store.transaction do +# # Read-write transaction. +# # Any code except a call to #transaction is allowed here. +# end +# +# If argument +read_only+ is passed as +true+, +# only reading is allowed: +# +# store.transaction(true) do +# # Read-only transaction: +# # Calls to #transaction, #[]=, and #delete are not allowed here. +# end +# +# == Hierarchical Values +# +# The value for an entry may be a simple object (as seen above). +# It may also be a hierarchy of objects nested to any depth: +# +# 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 +# +# And recall that you can use +# {dig methods}[rdoc-ref:dig_methods.rdoc] +# in a returned hierarchy of objects. +# +# == Working with the Store +# +# === Creating a Store +# +# Use method PStore.new to create a store. +# The new store creates or opens its containing file: +# +# store = PStore.new('t.store') +# +# === Modifying the Store +# +# Use method #[]= to update or create an entry: +# +# example_store do |store| +# store.transaction do +# store[:foo] = 1 # Update. +# store[:bam] = 1 # Create. +# end +# end +# +# Use method #delete to remove an entry: +# +# example_store do |store| +# store.transaction do +# store.delete(:foo) +# store[:foo] # => nil +# end +# end +# +# === Retrieving Values +# +# Use method #fetch (allows default) or #[] (defaults to +nil+) +# to retrieve an entry: +# +# 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 +# +# === Querying the Store +# +# Use method #key? to determine whether a given key exists: +# +# example_store do |store| +# store.transaction do +# store.key?(:foo) # => true +# end +# end # -# Behind the scenes, Ruby objects are stored to the data store file with -# Marshal. That carries the usual limitations. Proc objects cannot be -# marshalled, for example. +# Use method #keys to retrieve keys: # -# == Usage example: +# example_store do |store| +# store.transaction do +# store.keys # => [:foo, :bar, :baz] +# end +# end +# +# Use method #path to retrieve the path to the store's underlying file; +# this method may be called from outside a transaction block: +# +# store = PStore.new('t.store') +# store.path # => "t.store" +# +# == Transaction Safety +# +# For transaction safety, see: +# +# - Optional argument +thread_safe+ at method PStore.new. +# - Attribute #ultra_safe. +# +# Needless to say, if you're storing valuable data with \PStore, then you should +# backup the \PStore file from time to time. +# +# == An Example Store # # require "pstore" # -# # a mock wiki object... +# # A mock wiki object. # class WikiPage -# def initialize( page_name, author, contents ) +# +# attr_reader :page_name +# +# def initialize(page_name, author, contents) # @page_name = page_name # @revisions = Array.new -# # add_revision(author, contents) # end # -# attr_reader :page_name -# -# def add_revision( author, contents ) -# @revisions << { :created => Time.now, -# :author => author, -# :contents => contents } +# 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 page... -# home_page = WikiPage.new( "HomePage", "James Edward Gray II", -# "A page about the JoysOfDocumentation..." ) +# # Create a new wiki page. +# home_page = WikiPage.new("HomePage", "James Edward Gray II", +# "A page about the JoysOfDocumentation..." ) # -# # then we want to update page data and the index together, or not at all... # wiki = PStore.new("wiki_pages.pstore") -# wiki.transaction do # begin transaction; do all of this or none of it -# # store page... +# # Update page data and the index together, or not at all. +# wiki.transaction do +# # Store page. # wiki[home_page.page_name] = home_page -# # ensure that an index has been created... +# # Create page index. # wiki[:wiki_index] ||= Array.new -# # update wiki index... +# # Update wiki index. # wiki[:wiki_index].push(*home_page.wiki_page_references) -# end # commit changes to wiki data store file -# -# ### Some time later... ### +# end # -# # read wiki data... -# wiki.transaction(true) do # begin read-only transaction, no changes allowed -# wiki.roots.each do |data_root_name| -# p data_root_name -# p wiki[data_root_name] +# # 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 # -# == Transaction modes -# -# By default, file integrity is only ensured as long as the operating system -# (and the underlying hardware) doesn't raise any unexpected I/O errors. If an -# I/O error occurs while PStore is writing to its file, then the file will -# become corrupted. -# -# You can prevent this by setting <em>pstore.ultra_safe = true</em>. -# However, this results in a minor performance loss, and only works on platforms -# that support atomic file renames. Please consult the documentation for -# +ultra_safe+ for details. -# -# Needless to say, if you're storing valuable data with PStore, then you should -# backup the PStore files from time to time. class PStore - VERSION = "0.1.1" + VERSION = "0.1.3" RDWR_ACCESS = {mode: IO::RDWR | IO::CREAT | IO::BINARY, encoding: Encoding::ASCII_8BIT}.freeze RD_ACCESS = {mode: IO::RDONLY | IO::BINARY, encoding: Encoding::ASCII_8BIT}.freeze @@ -102,21 +336,38 @@ class PStore class Error < StandardError end - # Whether PStore should do its best to prevent file corruptions, even when under - # unlikely-to-occur error conditions such as out-of-space conditions and other - # unusual OS filesystem errors. Setting this flag comes at the price in the form - # of a performance loss. + # Whether \PStore should do its best to prevent file corruptions, + # even when an unlikely error (such as memory-error or filesystem error) occurs: + # + # - +true+: changes are posted by creating a temporary file, + # writing the updated data to it, then renaming the file to the given #path. + # File integrity is maintained. + # Note: has effect only if the filesystem has atomic file rename + # (as do POSIX platforms Linux, MacOS, FreeBSD and others). + # + # - +false+ (the default): changes are posted by rewinding the open file + # and writing the updated data. + # File integrity is maintained if the filesystem raises + # no unexpected I/O error; + # if such an error occurs during a write to the store, + # the file may become corrupted. # - # This flag only has effect on platforms on which file renames are atomic (e.g. - # all POSIX platforms: Linux, MacOS X, FreeBSD, etc). The default value is false. attr_accessor :ultra_safe + # Returns a new \PStore object. + # + # Argument +file+ is the path to the file in which objects are to be stored; + # if the file exists, it should be one that was written by \PStore. # - # To construct a PStore object, pass in the _file_ path where you would like - # the data to be stored. + # path = 't.store' + # store = PStore.new(path) # - # PStore objects are always reentrant. But if _thread_safe_ is set to true, - # then it will become thread-safe at the cost of a minor performance hit. + # A \PStore object is + # {reentrant}[https://en.wikipedia.org/wiki/Reentrancy_(computing)]. + # If argument +thread_safe+ is given as +true+, + # the object is also thread-safe (at the cost of a small performance penalty): + # + # store = PStore.new(path, true) # def initialize(file, thread_safe = false) dir = File::dirname(file) @@ -147,169 +398,156 @@ class PStore end private :in_transaction, :in_transaction_wr + # Returns the value for the given +key+ if the key exists. + # +nil+ otherwise; + # if not +nil+, the returned value is an object or a hierarchy of objects: + # + # example_store do |store| + # store.transaction do + # store[:foo] # => 0 + # store[:nope] # => nil + # end + # end # - # Retrieves a value from the PStore file data, by _name_. The hierarchy of - # Ruby objects stored under that root _name_ will be returned. + # Returns +nil+ if there is no such key. # - # *WARNING*: This method is only valid in a PStore#transaction. It will - # raise PStore::Error if called at any other time. + # See also {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values]. # - def [](name) + # Raises an exception if called outside a transaction block. + def [](key) in_transaction - @table[name] + @table[key] end + + # Like #[], except that it accepts a default value for the store. + # If the +key+ does not exist: # - # This method is just like PStore#[], save that you may also provide a - # _default_ value for the object. In the event the specified _name_ is not - # found in the data store, your _default_ will be returned instead. If you do - # not specify a default, PStore::Error will be raised if the object is not - # found. + # - Raises an exception if +default+ is +PStore::Error+. + # - Returns the value of +default+ otherwise: # - # *WARNING*: This method is only valid in a PStore#transaction. It will - # raise PStore::Error if called at any other time. + # example_store do |store| + # store.transaction do + # store.fetch(:nope, nil) # => nil + # store.fetch(:nope) # Raises an exception. + # end + # end # - def fetch(name, default=PStore::Error) + # Raises an exception if called outside a transaction block. + def fetch(key, default=PStore::Error) in_transaction - unless @table.key? name + unless @table.key? key if default == PStore::Error - raise PStore::Error, format("undefined root name `%s'", name) + raise PStore::Error, format("undefined key '%s'", key) else return default end end - @table[name] + @table[key] end + + # Creates or replaces the value for the given +key+: # - # Stores an individual Ruby object or a hierarchy of Ruby objects in the data - # store file under the root _name_. Assigning to a _name_ already in the data - # store clobbers the old data. - # - # == Example: - # - # require "pstore" - # - # store = PStore.new("data_file.pstore") - # store.transaction do # begin transaction - # # load some data into the store... - # store[:single_object] = "My data..." - # store[:obj_hierarchy] = { "Kev Jackson" => ["rational.rb", "pstore.rb"], - # "James Gray" => ["erb.rb", "pstore.rb"] } - # end # commit changes to data store file + # example_store do |store| + # temp.transaction do + # temp[:bat] = 3 + # end + # end # - # *WARNING*: This method is only valid in a PStore#transaction and it cannot - # be read-only. It will raise PStore::Error if called at any other time. + # See also {Hierarchical Values}[rdoc-ref:PStore@Hierarchical+Values]. # - def []=(name, value) + # Raises an exception if called outside a transaction block. + def []=(key, value) in_transaction_wr - @table[name] = value + @table[key] = value end + + # Removes and returns the value at +key+ if it exists: # - # Removes an object hierarchy from the data store, by _name_. + # example_store do |store| + # store.transaction do + # store[:bat] = 3 + # store.delete(:bat) + # end + # end # - # *WARNING*: This method is only valid in a PStore#transaction and it cannot - # be read-only. It will raise PStore::Error if called at any other time. + # Returns +nil+ if there is no such key. # - def delete(name) + # Raises an exception if called outside a transaction block. + def delete(key) in_transaction_wr - @table.delete name + @table.delete key end + # Returns an array of the existing keys: # - # Returns the names of all object hierarchies currently in the store. + # example_store do |store| + # store.transaction do + # store.keys # => [:foo, :bar, :baz] + # end + # end # - # *WARNING*: This method is only valid in a PStore#transaction. It will - # raise PStore::Error if called at any other time. - # - def roots + # Raises an exception if called outside a transaction block. + def keys in_transaction @table.keys end + alias roots keys + + # Returns +true+ if +key+ exists, +false+ otherwise: # - # Returns true if the supplied _name_ is currently in the data store. - # - # *WARNING*: This method is only valid in a PStore#transaction. It will - # raise PStore::Error if called at any other time. + # example_store do |store| + # store.transaction do + # store.key?(:foo) # => true + # end + # end # - def root?(name) + # Raises an exception if called outside a transaction block. + def key?(key) in_transaction - @table.key? name + @table.key? key end - # Returns the path to the data store file. + alias root? key? + + # Returns the string file path used to create the store: + # + # store.path # => "flat.store" + # def path @filename end + # Exits the current transaction block, committing any changes + # specified in the + # {transaction block}[rdoc-ref:PStore@The+Transaction+Block]. # - # Ends the current PStore#transaction, committing any changes to the data - # store immediately. - # - # == Example: - # - # require "pstore" - # - # store = PStore.new("data_file.pstore") - # store.transaction do # begin transaction - # # load some data into the store... - # store[:one] = 1 - # store[:two] = 2 - # - # store.commit # end transaction here, committing changes - # - # store[:three] = 3 # this change is never reached - # end - # - # *WARNING*: This method is only valid in a PStore#transaction. It will - # raise PStore::Error if called at any other time. - # + # Raises an exception if called outside a transaction block. def commit in_transaction @abort = false throw :pstore_abort_transaction end + + # Exits the current transaction block, discarding any changes + # specified in the + # {transaction block}[rdoc-ref:PStore@The+Transaction+Block]. # - # Ends the current PStore#transaction, discarding any changes to the data - # store. - # - # == Example: - # - # require "pstore" - # - # store = PStore.new("data_file.pstore") - # store.transaction do # begin transaction - # store[:one] = 1 # this change is not applied, see below... - # store[:two] = 2 # this change is not applied, see below... - # - # store.abort # end transaction here, discard all changes - # - # store[:three] = 3 # this change is never reached - # end - # - # *WARNING*: This method is only valid in a PStore#transaction. It will - # raise PStore::Error if called at any other time. - # + # Raises an exception if called outside a transaction block. def abort in_transaction @abort = true throw :pstore_abort_transaction end + # Opens a transaction block for the store. + # See {Transactions}[rdoc-ref:PStore@Transactions]. # - # Opens a new transaction for the data store. Code executed inside a block - # passed to this method may read and write data to and from the data store - # file. - # - # At the end of the block, changes are committed to the data store - # automatically. You may exit the transaction early with a call to either - # PStore#commit or PStore#abort. See those methods for details about how - # changes are handled. Raising an uncaught Exception in the block is - # equivalent to calling PStore#abort. - # - # If _read_only_ is set to +true+, you will only be allowed to read from the - # data store during the transaction and any attempts to change the data will - # raise a PStore::Error. + # With argument +read_only+ as +false+, the block may both read from + # and write to the store. # - # Note that PStore does not support nested transactions. + # With argument +read_only+ as +true+, the block may not include calls + # to #transaction, #[]=, or #delete. # + # Raises an exception if called within a transaction block. def transaction(read_only = false) # :yields: pstore value = nil if !@thread_safe |