| Class | PStore |
| In: |
lib/pstore.rb
|
| Parent: | Object |
PStore implements a file based persistance 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.
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 upated 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.
require "pstore"
# a mock wiki object...
class WikiPage
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 }
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..." )
# 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...
wiki[home_page.page_name] = home_page
# ensure that an index has been created...
wiki[:wiki_index] ||= Array.new
# update wiki index...
wiki[:wiki_index].push(*home_page.wiki_page_references)
end # commit changes to wiki data store file
### Some time later... ###
# 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]
end
end
To construct a PStore object, pass in the file path where you would like the data to be stored.
# File lib/pstore.rb, line 89
89: def initialize(file)
90: dir = File::dirname(file)
91: unless File::directory? dir
92: raise PStore::Error, format("directory %s does not exist", dir)
93: end
94: if File::exist? file and not File::readable? file
95: raise PStore::Error, format("file %s not readable", file)
96: end
97: @transaction = false
98: @filename = file
99: @abort = false
100: end
Retrieves a value from the PStore file data, by name. The hierarchy of Ruby objects stored under that root name will be returned.
WARNING: This method is only valid in a PStore#transaction. It will raise PStore::Error if called at any other time.
# File lib/pstore.rb, line 123
123: def [](name)
124: in_transaction
125: @table[name]
126: end
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.
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_heirarchy] = { "Kev Jackson" => ["rational.rb", "pstore.rb"],
"James Gray" => ["erb.rb", "pstore.rb"] }
end # commit changes to data store file
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.
# File lib/pstore.rb, line 167
167: def []=(name, value)
168: in_transaction_wr()
169: @table[name] = value
170: end
Ends the current PStore#transaction, discarding any changes to the data store.
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.
# File lib/pstore.rb, line 255
255: def abort
256: in_transaction
257: @abort = true
258: throw :pstore_abort_transaction
259: end
Ends the current PStore#transaction, committing any changes to the data store immediately.
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.
# File lib/pstore.rb, line 229
229: def commit
230: in_transaction
231: @abort = false
232: throw :pstore_abort_transaction
233: end
Removes an object hierarchy from the data store, by name.
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.
# File lib/pstore.rb, line 177
177: def delete(name)
178: in_transaction_wr()
179: @table.delete name
180: end
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.
WARNING: This method is only valid in a PStore#transaction. It will raise PStore::Error if called at any other time.
# File lib/pstore.rb, line 137
137: def fetch(name, default=PStore::Error)
138: unless @table.key? name
139: if default==PStore::Error
140: raise PStore::Error, format("undefined root name `%s'", name)
141: else
142: default
143: end
144: end
145: self[name]
146: end
Returns the path to the data store file.
# File lib/pstore.rb, line 203
203: def path
204: @filename
205: end
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.
# File lib/pstore.rb, line 198
198: def root?(name)
199: in_transaction
200: @table.key? name
201: end
Returns the names of all object hierarchies currently in the store.
WARNING: This method is only valid in a PStore#transaction. It will raise PStore::Error if called at any other time.
# File lib/pstore.rb, line 188
188: def roots
189: in_transaction
190: @table.keys
191: end
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.
Note that PStore does not support nested transactions.
# File lib/pstore.rb, line 278
278: def transaction(read_only=false) # :yields: pstore
279: raise PStore::Error, "nested transaction" if @transaction
280: begin
281: @rdonly = read_only
282: @abort = false
283: @transaction = true
284: value = nil
285: new_file = @filename + ".new"
286:
287: content = nil
288: unless read_only
289: file = File.open(@filename, File::RDWR | File::CREAT)
290: file.binmode
291: file.flock(File::LOCK_EX)
292: commit_new(file) if FileTest.exist?(new_file)
293: content = file.read()
294: else
295: begin
296: file = File.open(@filename, File::RDONLY)
297: file.binmode
298: file.flock(File::LOCK_SH)
299: content = (File.read(new_file) rescue file.read())
300: rescue Errno::ENOENT
301: content = ""
302: end
303: end
304:
305: if content != ""
306: @table = load(content)
307: if !read_only
308: size = content.size
309: md5 = Digest::MD5.digest(content)
310: end
311: else
312: @table = {}
313: end
314: content = nil # unreference huge data
315:
316: begin
317: catch(:pstore_abort_transaction) do
318: value = yield(self)
319: end
320: rescue Exception
321: @abort = true
322: raise
323: ensure
324: if !read_only and !@abort
325: tmp_file = @filename + ".tmp"
326: content = dump(@table)
327: if !md5 || size != content.size || md5 != Digest::MD5.digest(content)
328: File.open(tmp_file, "w") {|t|
329: t.binmode
330: t.write(content)
331: }
332: File.rename(tmp_file, new_file)
333: commit_new(file)
334: end
335: content = nil # unreference huge data
336: end
337: end
338: ensure
339: @table = nil
340: @transaction = false
341: file.close if file
342: end
343: value
344: end
Commits changes to the data store file.
# File lib/pstore.rb, line 363
363: def commit_new(f)
364: f.truncate(0)
365: f.rewind
366: new_file = @filename + ".new"
367: File.open(new_file) do |nf|
368: nf.binmode
369: FileUtils.copy_stream(nf, f)
370: end
371: File.unlink(new_file)
372: end
Raises PStore::Error if the calling code is not in a PStore#transaction.
# File lib/pstore.rb, line 103
103: def in_transaction
104: raise PStore::Error, "not in transaction" unless @transaction
105: end
Raises PStore::Error if the calling code is not in a PStore#transaction or if the code is in a read-only PStore#transaction.
# File lib/pstore.rb, line 110
110: def in_transaction_wr()
111: in_transaction()
112: raise PStore::Error, "in read-only transaction" if @rdonly
113: end