pstore 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.gitignore +9 -0
- data/.travis.yml +7 -0
- data/Gemfile +9 -0
- data/LICENSE.txt +22 -0
- data/README.md +95 -0
- data/Rakefile +10 -0
- data/bin/console +14 -0
- data/bin/setup +8 -0
- data/lib/pstore.rb +491 -0
- data/lib/pstore/version.rb +3 -0
- data/pstore.gemspec +27 -0
- metadata +56 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 3de8bbd117d11303d2372e9fd0b9db5a15fb4d6b566905101e70689cd82fbe4d
|
4
|
+
data.tar.gz: bbab746d38d3e6fc07bfaf54235bcb6e34727a2a20ae586620064a16de834dc2
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 4a4f1df2cafeee50e8c82a1755e8f0836f7c2b685f5372df1461cdac183d43cf3ad19b1dfa9a516ab3698e0ad1837f050be0e86b1b4944dbd5d3c625665f2b5d
|
7
|
+
data.tar.gz: f2b9d2cb5172cc4e09eba1ae2ec499bce9972b54028e0b89e6d26e6f66f16918254d3d643dc49d4caed17fe45ffc3278737431864de1d9a87bc429bf4c345c5b
|
data/.gitignore
ADDED
data/.travis.yml
ADDED
data/Gemfile
ADDED
data/LICENSE.txt
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
Copyright (C) 1993-2013 Yukihiro Matsumoto. All rights reserved.
|
2
|
+
|
3
|
+
Redistribution and use in source and binary forms, with or without
|
4
|
+
modification, are permitted provided that the following conditions
|
5
|
+
are met:
|
6
|
+
1. Redistributions of source code must retain the above copyright
|
7
|
+
notice, this list of conditions and the following disclaimer.
|
8
|
+
2. Redistributions in binary form must reproduce the above copyright
|
9
|
+
notice, this list of conditions and the following disclaimer in the
|
10
|
+
documentation and/or other materials provided with the distribution.
|
11
|
+
|
12
|
+
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
13
|
+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
14
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
15
|
+
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
16
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
17
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
18
|
+
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
19
|
+
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
20
|
+
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
21
|
+
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
22
|
+
SUCH DAMAGE.
|
data/README.md
ADDED
@@ -0,0 +1,95 @@
|
|
1
|
+
# Pstore
|
2
|
+
|
3
|
+
PStore implements a file based persistence mechanism based on a Hash. User
|
4
|
+
code can store hierarchies of Ruby objects (values) into the data store file
|
5
|
+
by name (keys). An object hierarchy may be just a single object. User code
|
6
|
+
may later read values back from the data store or even update data, as needed.
|
7
|
+
|
8
|
+
The transactional behavior ensures that any changes succeed or fail together.
|
9
|
+
This can be used to ensure that the data store is not left in a transitory
|
10
|
+
state, where some values were updated but others were not.
|
11
|
+
|
12
|
+
Behind the scenes, Ruby objects are stored to the data store file with
|
13
|
+
Marshal. That carries the usual limitations. Proc objects cannot be
|
14
|
+
marshalled, for example.
|
15
|
+
|
16
|
+
## Installation
|
17
|
+
|
18
|
+
Add this line to your application's Gemfile:
|
19
|
+
|
20
|
+
```ruby
|
21
|
+
gem 'pstore'
|
22
|
+
```
|
23
|
+
|
24
|
+
And then execute:
|
25
|
+
|
26
|
+
$ bundle
|
27
|
+
|
28
|
+
Or install it yourself as:
|
29
|
+
|
30
|
+
$ gem install pstore
|
31
|
+
|
32
|
+
## Usage
|
33
|
+
|
34
|
+
```ruby
|
35
|
+
require "pstore"
|
36
|
+
|
37
|
+
# a mock wiki object...
|
38
|
+
class WikiPage
|
39
|
+
def initialize( page_name, author, contents )
|
40
|
+
@page_name = page_name
|
41
|
+
@revisions = Array.new
|
42
|
+
|
43
|
+
add_revision(author, contents)
|
44
|
+
end
|
45
|
+
|
46
|
+
attr_reader :page_name
|
47
|
+
|
48
|
+
def add_revision( author, contents )
|
49
|
+
@revisions << { :created => Time.now,
|
50
|
+
:author => author,
|
51
|
+
:contents => contents }
|
52
|
+
end
|
53
|
+
|
54
|
+
def wiki_page_references
|
55
|
+
[@page_name] + @revisions.last[:contents].scan(/\b(?:[A-Z]+[a-z]+){2,}/)
|
56
|
+
end
|
57
|
+
|
58
|
+
# ...
|
59
|
+
end
|
60
|
+
|
61
|
+
# create a new page...
|
62
|
+
home_page = WikiPage.new( "HomePage", "James Edward Gray II",
|
63
|
+
"A page about the JoysOfDocumentation..." )
|
64
|
+
|
65
|
+
# then we want to update page data and the index together, or not at all...
|
66
|
+
wiki = PStore.new("wiki_pages.pstore")
|
67
|
+
wiki.transaction do # begin transaction; do all of this or none of it
|
68
|
+
# store page...
|
69
|
+
wiki[home_page.page_name] = home_page
|
70
|
+
# ensure that an index has been created...
|
71
|
+
wiki[:wiki_index] ||= Array.new
|
72
|
+
# update wiki index...
|
73
|
+
wiki[:wiki_index].push(*home_page.wiki_page_references)
|
74
|
+
end # commit changes to wiki data store file
|
75
|
+
|
76
|
+
### Some time later... ###
|
77
|
+
|
78
|
+
# read wiki data...
|
79
|
+
wiki.transaction(true) do # begin read-only transaction, no changes allowed
|
80
|
+
wiki.roots.each do |data_root_name|
|
81
|
+
p data_root_name
|
82
|
+
p wiki[data_root_name]
|
83
|
+
end
|
84
|
+
end
|
85
|
+
```
|
86
|
+
|
87
|
+
## Development
|
88
|
+
|
89
|
+
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
90
|
+
|
91
|
+
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
|
92
|
+
|
93
|
+
## Contributing
|
94
|
+
|
95
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/pstore.
|
data/Rakefile
ADDED
data/bin/console
ADDED
@@ -0,0 +1,14 @@
|
|
1
|
+
#!/usr/bin/env ruby
|
2
|
+
|
3
|
+
require "bundler/setup"
|
4
|
+
require "pstore"
|
5
|
+
|
6
|
+
# You can add fixtures and/or initialization code here to make experimenting
|
7
|
+
# with your gem easier. You can also use a different console, if you like.
|
8
|
+
|
9
|
+
# (If you use this, don't forget to add pry to your Gemfile!)
|
10
|
+
# require "pry"
|
11
|
+
# Pry.start
|
12
|
+
|
13
|
+
require "irb"
|
14
|
+
IRB.start(__FILE__)
|
data/bin/setup
ADDED
data/lib/pstore.rb
ADDED
@@ -0,0 +1,491 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
# = PStore -- Transactional File Storage for Ruby Objects
|
3
|
+
#
|
4
|
+
# pstore.rb -
|
5
|
+
# originally by matz
|
6
|
+
# documentation by Kev Jackson and James Edward Gray II
|
7
|
+
# improved by Hongli Lai
|
8
|
+
#
|
9
|
+
# See PStore for documentation.
|
10
|
+
|
11
|
+
require "digest"
|
12
|
+
|
13
|
+
#
|
14
|
+
# PStore implements a file based persistence mechanism based on a Hash. User
|
15
|
+
# code can store hierarchies of Ruby objects (values) into the data store file
|
16
|
+
# by name (keys). An object hierarchy may be just a single object. User code
|
17
|
+
# may later read values back from the data store or even update data, as needed.
|
18
|
+
#
|
19
|
+
# The transactional behavior ensures that any changes succeed or fail together.
|
20
|
+
# This can be used to ensure that the data store is not left in a transitory
|
21
|
+
# state, where some values were updated but others were not.
|
22
|
+
#
|
23
|
+
# Behind the scenes, Ruby objects are stored to the data store file with
|
24
|
+
# Marshal. That carries the usual limitations. Proc objects cannot be
|
25
|
+
# marshalled, for example.
|
26
|
+
#
|
27
|
+
# == Usage example:
|
28
|
+
#
|
29
|
+
# require "pstore"
|
30
|
+
#
|
31
|
+
# # a mock wiki object...
|
32
|
+
# class WikiPage
|
33
|
+
# def initialize( page_name, author, contents )
|
34
|
+
# @page_name = page_name
|
35
|
+
# @revisions = Array.new
|
36
|
+
#
|
37
|
+
# add_revision(author, contents)
|
38
|
+
# end
|
39
|
+
#
|
40
|
+
# attr_reader :page_name
|
41
|
+
#
|
42
|
+
# def add_revision( author, contents )
|
43
|
+
# @revisions << { :created => Time.now,
|
44
|
+
# :author => author,
|
45
|
+
# :contents => contents }
|
46
|
+
# end
|
47
|
+
#
|
48
|
+
# def wiki_page_references
|
49
|
+
# [@page_name] + @revisions.last[:contents].scan(/\b(?:[A-Z]+[a-z]+){2,}/)
|
50
|
+
# end
|
51
|
+
#
|
52
|
+
# # ...
|
53
|
+
# end
|
54
|
+
#
|
55
|
+
# # create a new page...
|
56
|
+
# home_page = WikiPage.new( "HomePage", "James Edward Gray II",
|
57
|
+
# "A page about the JoysOfDocumentation..." )
|
58
|
+
#
|
59
|
+
# # then we want to update page data and the index together, or not at all...
|
60
|
+
# wiki = PStore.new("wiki_pages.pstore")
|
61
|
+
# wiki.transaction do # begin transaction; do all of this or none of it
|
62
|
+
# # store page...
|
63
|
+
# wiki[home_page.page_name] = home_page
|
64
|
+
# # ensure that an index has been created...
|
65
|
+
# wiki[:wiki_index] ||= Array.new
|
66
|
+
# # update wiki index...
|
67
|
+
# wiki[:wiki_index].push(*home_page.wiki_page_references)
|
68
|
+
# end # commit changes to wiki data store file
|
69
|
+
#
|
70
|
+
# ### Some time later... ###
|
71
|
+
#
|
72
|
+
# # read wiki data...
|
73
|
+
# wiki.transaction(true) do # begin read-only transaction, no changes allowed
|
74
|
+
# wiki.roots.each do |data_root_name|
|
75
|
+
# p data_root_name
|
76
|
+
# p wiki[data_root_name]
|
77
|
+
# end
|
78
|
+
# end
|
79
|
+
#
|
80
|
+
# == Transaction modes
|
81
|
+
#
|
82
|
+
# By default, file integrity is only ensured as long as the operating system
|
83
|
+
# (and the underlying hardware) doesn't raise any unexpected I/O errors. If an
|
84
|
+
# I/O error occurs while PStore is writing to its file, then the file will
|
85
|
+
# become corrupted.
|
86
|
+
#
|
87
|
+
# You can prevent this by setting <em>pstore.ultra_safe = true</em>.
|
88
|
+
# However, this results in a minor performance loss, and only works on platforms
|
89
|
+
# that support atomic file renames. Please consult the documentation for
|
90
|
+
# +ultra_safe+ for details.
|
91
|
+
#
|
92
|
+
# Needless to say, if you're storing valuable data with PStore, then you should
|
93
|
+
# backup the PStore files from time to time.
|
94
|
+
class PStore
|
95
|
+
RDWR_ACCESS = {mode: IO::RDWR | IO::CREAT | IO::BINARY, encoding: Encoding::ASCII_8BIT}.freeze
|
96
|
+
RD_ACCESS = {mode: IO::RDONLY | IO::BINARY, encoding: Encoding::ASCII_8BIT}.freeze
|
97
|
+
WR_ACCESS = {mode: IO::WRONLY | IO::CREAT | IO::TRUNC | IO::BINARY, encoding: Encoding::ASCII_8BIT}.freeze
|
98
|
+
|
99
|
+
# The error type thrown by all PStore methods.
|
100
|
+
class Error < StandardError
|
101
|
+
end
|
102
|
+
|
103
|
+
# Whether PStore should do its best to prevent file corruptions, even when under
|
104
|
+
# unlikely-to-occur error conditions such as out-of-space conditions and other
|
105
|
+
# unusual OS filesystem errors. Setting this flag comes at the price in the form
|
106
|
+
# of a performance loss.
|
107
|
+
#
|
108
|
+
# This flag only has effect on platforms on which file renames are atomic (e.g.
|
109
|
+
# all POSIX platforms: Linux, MacOS X, FreeBSD, etc). The default value is false.
|
110
|
+
attr_accessor :ultra_safe
|
111
|
+
|
112
|
+
#
|
113
|
+
# To construct a PStore object, pass in the _file_ path where you would like
|
114
|
+
# the data to be stored.
|
115
|
+
#
|
116
|
+
# PStore objects are always reentrant. But if _thread_safe_ is set to true,
|
117
|
+
# then it will become thread-safe at the cost of a minor performance hit.
|
118
|
+
#
|
119
|
+
def initialize(file, thread_safe = false)
|
120
|
+
dir = File::dirname(file)
|
121
|
+
unless File::directory? dir
|
122
|
+
raise PStore::Error, format("directory %s does not exist", dir)
|
123
|
+
end
|
124
|
+
if File::exist? file and not File::readable? file
|
125
|
+
raise PStore::Error, format("file %s not readable", file)
|
126
|
+
end
|
127
|
+
@filename = file
|
128
|
+
@abort = false
|
129
|
+
@ultra_safe = false
|
130
|
+
@thread_safe = thread_safe
|
131
|
+
@lock = Thread::Mutex.new
|
132
|
+
end
|
133
|
+
|
134
|
+
# Raises PStore::Error if the calling code is not in a PStore#transaction.
|
135
|
+
def in_transaction
|
136
|
+
raise PStore::Error, "not in transaction" unless @lock.locked?
|
137
|
+
end
|
138
|
+
#
|
139
|
+
# Raises PStore::Error if the calling code is not in a PStore#transaction or
|
140
|
+
# if the code is in a read-only PStore#transaction.
|
141
|
+
#
|
142
|
+
def in_transaction_wr
|
143
|
+
in_transaction
|
144
|
+
raise PStore::Error, "in read-only transaction" if @rdonly
|
145
|
+
end
|
146
|
+
private :in_transaction, :in_transaction_wr
|
147
|
+
|
148
|
+
#
|
149
|
+
# Retrieves a value from the PStore file data, by _name_. The hierarchy of
|
150
|
+
# Ruby objects stored under that root _name_ will be returned.
|
151
|
+
#
|
152
|
+
# *WARNING*: This method is only valid in a PStore#transaction. It will
|
153
|
+
# raise PStore::Error if called at any other time.
|
154
|
+
#
|
155
|
+
def [](name)
|
156
|
+
in_transaction
|
157
|
+
@table[name]
|
158
|
+
end
|
159
|
+
#
|
160
|
+
# This method is just like PStore#[], save that you may also provide a
|
161
|
+
# _default_ value for the object. In the event the specified _name_ is not
|
162
|
+
# found in the data store, your _default_ will be returned instead. If you do
|
163
|
+
# not specify a default, PStore::Error will be raised if the object is not
|
164
|
+
# found.
|
165
|
+
#
|
166
|
+
# *WARNING*: This method is only valid in a PStore#transaction. It will
|
167
|
+
# raise PStore::Error if called at any other time.
|
168
|
+
#
|
169
|
+
def fetch(name, default=PStore::Error)
|
170
|
+
in_transaction
|
171
|
+
unless @table.key? name
|
172
|
+
if default == PStore::Error
|
173
|
+
raise PStore::Error, format("undefined root name `%s'", name)
|
174
|
+
else
|
175
|
+
return default
|
176
|
+
end
|
177
|
+
end
|
178
|
+
@table[name]
|
179
|
+
end
|
180
|
+
#
|
181
|
+
# Stores an individual Ruby object or a hierarchy of Ruby objects in the data
|
182
|
+
# store file under the root _name_. Assigning to a _name_ already in the data
|
183
|
+
# store clobbers the old data.
|
184
|
+
#
|
185
|
+
# == Example:
|
186
|
+
#
|
187
|
+
# require "pstore"
|
188
|
+
#
|
189
|
+
# store = PStore.new("data_file.pstore")
|
190
|
+
# store.transaction do # begin transaction
|
191
|
+
# # load some data into the store...
|
192
|
+
# store[:single_object] = "My data..."
|
193
|
+
# store[:obj_hierarchy] = { "Kev Jackson" => ["rational.rb", "pstore.rb"],
|
194
|
+
# "James Gray" => ["erb.rb", "pstore.rb"] }
|
195
|
+
# end # commit changes to data store file
|
196
|
+
#
|
197
|
+
# *WARNING*: This method is only valid in a PStore#transaction and it cannot
|
198
|
+
# be read-only. It will raise PStore::Error if called at any other time.
|
199
|
+
#
|
200
|
+
def []=(name, value)
|
201
|
+
in_transaction_wr
|
202
|
+
@table[name] = value
|
203
|
+
end
|
204
|
+
#
|
205
|
+
# Removes an object hierarchy from the data store, by _name_.
|
206
|
+
#
|
207
|
+
# *WARNING*: This method is only valid in a PStore#transaction and it cannot
|
208
|
+
# be read-only. It will raise PStore::Error if called at any other time.
|
209
|
+
#
|
210
|
+
def delete(name)
|
211
|
+
in_transaction_wr
|
212
|
+
@table.delete name
|
213
|
+
end
|
214
|
+
|
215
|
+
#
|
216
|
+
# Returns the names of all object hierarchies currently in the store.
|
217
|
+
#
|
218
|
+
# *WARNING*: This method is only valid in a PStore#transaction. It will
|
219
|
+
# raise PStore::Error if called at any other time.
|
220
|
+
#
|
221
|
+
def roots
|
222
|
+
in_transaction
|
223
|
+
@table.keys
|
224
|
+
end
|
225
|
+
#
|
226
|
+
# Returns true if the supplied _name_ is currently in the data store.
|
227
|
+
#
|
228
|
+
# *WARNING*: This method is only valid in a PStore#transaction. It will
|
229
|
+
# raise PStore::Error if called at any other time.
|
230
|
+
#
|
231
|
+
def root?(name)
|
232
|
+
in_transaction
|
233
|
+
@table.key? name
|
234
|
+
end
|
235
|
+
# Returns the path to the data store file.
|
236
|
+
def path
|
237
|
+
@filename
|
238
|
+
end
|
239
|
+
|
240
|
+
#
|
241
|
+
# Ends the current PStore#transaction, committing any changes to the data
|
242
|
+
# store immediately.
|
243
|
+
#
|
244
|
+
# == Example:
|
245
|
+
#
|
246
|
+
# require "pstore"
|
247
|
+
#
|
248
|
+
# store = PStore.new("data_file.pstore")
|
249
|
+
# store.transaction do # begin transaction
|
250
|
+
# # load some data into the store...
|
251
|
+
# store[:one] = 1
|
252
|
+
# store[:two] = 2
|
253
|
+
#
|
254
|
+
# store.commit # end transaction here, committing changes
|
255
|
+
#
|
256
|
+
# store[:three] = 3 # this change is never reached
|
257
|
+
# end
|
258
|
+
#
|
259
|
+
# *WARNING*: This method is only valid in a PStore#transaction. It will
|
260
|
+
# raise PStore::Error if called at any other time.
|
261
|
+
#
|
262
|
+
def commit
|
263
|
+
in_transaction
|
264
|
+
@abort = false
|
265
|
+
throw :pstore_abort_transaction
|
266
|
+
end
|
267
|
+
#
|
268
|
+
# Ends the current PStore#transaction, discarding any changes to the data
|
269
|
+
# store.
|
270
|
+
#
|
271
|
+
# == Example:
|
272
|
+
#
|
273
|
+
# require "pstore"
|
274
|
+
#
|
275
|
+
# store = PStore.new("data_file.pstore")
|
276
|
+
# store.transaction do # begin transaction
|
277
|
+
# store[:one] = 1 # this change is not applied, see below...
|
278
|
+
# store[:two] = 2 # this change is not applied, see below...
|
279
|
+
#
|
280
|
+
# store.abort # end transaction here, discard all changes
|
281
|
+
#
|
282
|
+
# store[:three] = 3 # this change is never reached
|
283
|
+
# end
|
284
|
+
#
|
285
|
+
# *WARNING*: This method is only valid in a PStore#transaction. It will
|
286
|
+
# raise PStore::Error if called at any other time.
|
287
|
+
#
|
288
|
+
def abort
|
289
|
+
in_transaction
|
290
|
+
@abort = true
|
291
|
+
throw :pstore_abort_transaction
|
292
|
+
end
|
293
|
+
|
294
|
+
#
|
295
|
+
# Opens a new transaction for the data store. Code executed inside a block
|
296
|
+
# passed to this method may read and write data to and from the data store
|
297
|
+
# file.
|
298
|
+
#
|
299
|
+
# At the end of the block, changes are committed to the data store
|
300
|
+
# automatically. You may exit the transaction early with a call to either
|
301
|
+
# PStore#commit or PStore#abort. See those methods for details about how
|
302
|
+
# changes are handled. Raising an uncaught Exception in the block is
|
303
|
+
# equivalent to calling PStore#abort.
|
304
|
+
#
|
305
|
+
# If _read_only_ is set to +true+, you will only be allowed to read from the
|
306
|
+
# data store during the transaction and any attempts to change the data will
|
307
|
+
# raise a PStore::Error.
|
308
|
+
#
|
309
|
+
# Note that PStore does not support nested transactions.
|
310
|
+
#
|
311
|
+
def transaction(read_only = false) # :yields: pstore
|
312
|
+
value = nil
|
313
|
+
if !@thread_safe
|
314
|
+
raise PStore::Error, "nested transaction" unless @lock.try_lock
|
315
|
+
else
|
316
|
+
begin
|
317
|
+
@lock.lock
|
318
|
+
rescue ThreadError
|
319
|
+
raise PStore::Error, "nested transaction"
|
320
|
+
end
|
321
|
+
end
|
322
|
+
begin
|
323
|
+
@rdonly = read_only
|
324
|
+
@abort = false
|
325
|
+
file = open_and_lock_file(@filename, read_only)
|
326
|
+
if file
|
327
|
+
begin
|
328
|
+
@table, checksum, original_data_size = load_data(file, read_only)
|
329
|
+
|
330
|
+
catch(:pstore_abort_transaction) do
|
331
|
+
value = yield(self)
|
332
|
+
end
|
333
|
+
|
334
|
+
if !@abort && !read_only
|
335
|
+
save_data(checksum, original_data_size, file)
|
336
|
+
end
|
337
|
+
ensure
|
338
|
+
file.close
|
339
|
+
end
|
340
|
+
else
|
341
|
+
# This can only occur if read_only == true.
|
342
|
+
@table = {}
|
343
|
+
catch(:pstore_abort_transaction) do
|
344
|
+
value = yield(self)
|
345
|
+
end
|
346
|
+
end
|
347
|
+
ensure
|
348
|
+
@lock.unlock
|
349
|
+
end
|
350
|
+
value
|
351
|
+
end
|
352
|
+
|
353
|
+
private
|
354
|
+
# Constant for relieving Ruby's garbage collector.
|
355
|
+
CHECKSUM_ALGO = %w[SHA512 SHA384 SHA256 SHA1 RMD160 MD5].each do |algo|
|
356
|
+
begin
|
357
|
+
break Digest(algo)
|
358
|
+
rescue LoadError
|
359
|
+
end
|
360
|
+
end
|
361
|
+
EMPTY_STRING = ""
|
362
|
+
EMPTY_MARSHAL_DATA = Marshal.dump({})
|
363
|
+
EMPTY_MARSHAL_CHECKSUM = CHECKSUM_ALGO.digest(EMPTY_MARSHAL_DATA)
|
364
|
+
|
365
|
+
#
|
366
|
+
# Open the specified filename (either in read-only mode or in
|
367
|
+
# read-write mode) and lock it for reading or writing.
|
368
|
+
#
|
369
|
+
# The opened File object will be returned. If _read_only_ is true,
|
370
|
+
# and the file does not exist, then nil will be returned.
|
371
|
+
#
|
372
|
+
# All exceptions are propagated.
|
373
|
+
#
|
374
|
+
def open_and_lock_file(filename, read_only)
|
375
|
+
if read_only
|
376
|
+
begin
|
377
|
+
file = File.new(filename, **RD_ACCESS)
|
378
|
+
begin
|
379
|
+
file.flock(File::LOCK_SH)
|
380
|
+
return file
|
381
|
+
rescue
|
382
|
+
file.close
|
383
|
+
raise
|
384
|
+
end
|
385
|
+
rescue Errno::ENOENT
|
386
|
+
return nil
|
387
|
+
end
|
388
|
+
else
|
389
|
+
file = File.new(filename, **RDWR_ACCESS)
|
390
|
+
file.flock(File::LOCK_EX)
|
391
|
+
return file
|
392
|
+
end
|
393
|
+
end
|
394
|
+
|
395
|
+
# Load the given PStore file.
|
396
|
+
# If +read_only+ is true, the unmarshalled Hash will be returned.
|
397
|
+
# If +read_only+ is false, a 3-tuple will be returned: the unmarshalled
|
398
|
+
# Hash, a checksum of the data, and the size of the data.
|
399
|
+
def load_data(file, read_only)
|
400
|
+
if read_only
|
401
|
+
begin
|
402
|
+
table = load(file)
|
403
|
+
raise Error, "PStore file seems to be corrupted." unless table.is_a?(Hash)
|
404
|
+
rescue EOFError
|
405
|
+
# This seems to be a newly-created file.
|
406
|
+
table = {}
|
407
|
+
end
|
408
|
+
table
|
409
|
+
else
|
410
|
+
data = file.read
|
411
|
+
if data.empty?
|
412
|
+
# This seems to be a newly-created file.
|
413
|
+
table = {}
|
414
|
+
checksum = empty_marshal_checksum
|
415
|
+
size = empty_marshal_data.bytesize
|
416
|
+
else
|
417
|
+
table = load(data)
|
418
|
+
checksum = CHECKSUM_ALGO.digest(data)
|
419
|
+
size = data.bytesize
|
420
|
+
raise Error, "PStore file seems to be corrupted." unless table.is_a?(Hash)
|
421
|
+
end
|
422
|
+
data.replace(EMPTY_STRING)
|
423
|
+
[table, checksum, size]
|
424
|
+
end
|
425
|
+
end
|
426
|
+
|
427
|
+
def on_windows?
|
428
|
+
is_windows = RUBY_PLATFORM =~ /mswin|mingw|bccwin|wince/
|
429
|
+
self.class.__send__(:define_method, :on_windows?) do
|
430
|
+
is_windows
|
431
|
+
end
|
432
|
+
is_windows
|
433
|
+
end
|
434
|
+
|
435
|
+
def save_data(original_checksum, original_file_size, file)
|
436
|
+
new_data = dump(@table)
|
437
|
+
|
438
|
+
if new_data.bytesize != original_file_size || CHECKSUM_ALGO.digest(new_data) != original_checksum
|
439
|
+
if @ultra_safe && !on_windows?
|
440
|
+
# Windows doesn't support atomic file renames.
|
441
|
+
save_data_with_atomic_file_rename_strategy(new_data, file)
|
442
|
+
else
|
443
|
+
save_data_with_fast_strategy(new_data, file)
|
444
|
+
end
|
445
|
+
end
|
446
|
+
|
447
|
+
new_data.replace(EMPTY_STRING)
|
448
|
+
end
|
449
|
+
|
450
|
+
def save_data_with_atomic_file_rename_strategy(data, file)
|
451
|
+
temp_filename = "#{@filename}.tmp.#{Process.pid}.#{rand 1000000}"
|
452
|
+
temp_file = File.new(temp_filename, **WR_ACCESS)
|
453
|
+
begin
|
454
|
+
temp_file.flock(File::LOCK_EX)
|
455
|
+
temp_file.write(data)
|
456
|
+
temp_file.flush
|
457
|
+
File.rename(temp_filename, @filename)
|
458
|
+
rescue
|
459
|
+
File.unlink(temp_file) rescue nil
|
460
|
+
raise
|
461
|
+
ensure
|
462
|
+
temp_file.close
|
463
|
+
end
|
464
|
+
end
|
465
|
+
|
466
|
+
def save_data_with_fast_strategy(data, file)
|
467
|
+
file.rewind
|
468
|
+
file.write(data)
|
469
|
+
file.truncate(data.bytesize)
|
470
|
+
end
|
471
|
+
|
472
|
+
|
473
|
+
# This method is just a wrapped around Marshal.dump
|
474
|
+
# to allow subclass overriding used in YAML::Store.
|
475
|
+
def dump(table) # :nodoc:
|
476
|
+
Marshal::dump(table)
|
477
|
+
end
|
478
|
+
|
479
|
+
# This method is just a wrapped around Marshal.load.
|
480
|
+
# to allow subclass overriding used in YAML::Store.
|
481
|
+
def load(content) # :nodoc:
|
482
|
+
Marshal::load(content)
|
483
|
+
end
|
484
|
+
|
485
|
+
def empty_marshal_data
|
486
|
+
EMPTY_MARSHAL_DATA
|
487
|
+
end
|
488
|
+
def empty_marshal_checksum
|
489
|
+
EMPTY_MARSHAL_CHECKSUM
|
490
|
+
end
|
491
|
+
end
|
data/pstore.gemspec
ADDED
@@ -0,0 +1,27 @@
|
|
1
|
+
lib = File.expand_path("lib", __dir__)
|
2
|
+
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
|
3
|
+
require "pstore/version"
|
4
|
+
|
5
|
+
Gem::Specification.new do |spec|
|
6
|
+
spec.name = "pstore"
|
7
|
+
spec.version = PStore::VERSION
|
8
|
+
spec.authors = ["Hiroshi SHIBATA"]
|
9
|
+
spec.email = ["hsbt@ruby-lang.org"]
|
10
|
+
|
11
|
+
spec.summary = %q{Transactional File Storage for Ruby Objects}
|
12
|
+
spec.description = spec.summary
|
13
|
+
spec.homepage = "https://github.com/ruby/pstore"
|
14
|
+
spec.license = "BSD-2-Clause"
|
15
|
+
|
16
|
+
spec.metadata["homepage_uri"] = spec.homepage
|
17
|
+
spec.metadata["source_code_uri"] = "https://github.com/ruby/pstore"
|
18
|
+
|
19
|
+
# Specify which files should be added to the gem when it is released.
|
20
|
+
# The `git ls-files -z` loads the files in the RubyGem that have been added into git.
|
21
|
+
spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
|
22
|
+
`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
|
23
|
+
end
|
24
|
+
spec.bindir = "exe"
|
25
|
+
spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
|
26
|
+
spec.require_paths = ["lib"]
|
27
|
+
end
|
metadata
ADDED
@@ -0,0 +1,56 @@
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
2
|
+
name: pstore
|
3
|
+
version: !ruby/object:Gem::Version
|
4
|
+
version: 0.1.0
|
5
|
+
platform: ruby
|
6
|
+
authors:
|
7
|
+
- Hiroshi SHIBATA
|
8
|
+
autorequire:
|
9
|
+
bindir: exe
|
10
|
+
cert_chain: []
|
11
|
+
date: 2019-11-06 00:00:00.000000000 Z
|
12
|
+
dependencies: []
|
13
|
+
description: Transactional File Storage for Ruby Objects
|
14
|
+
email:
|
15
|
+
- hsbt@ruby-lang.org
|
16
|
+
executables: []
|
17
|
+
extensions: []
|
18
|
+
extra_rdoc_files: []
|
19
|
+
files:
|
20
|
+
- ".gitignore"
|
21
|
+
- ".travis.yml"
|
22
|
+
- Gemfile
|
23
|
+
- LICENSE.txt
|
24
|
+
- README.md
|
25
|
+
- Rakefile
|
26
|
+
- bin/console
|
27
|
+
- bin/setup
|
28
|
+
- lib/pstore.rb
|
29
|
+
- lib/pstore/version.rb
|
30
|
+
- pstore.gemspec
|
31
|
+
homepage: https://github.com/ruby/pstore
|
32
|
+
licenses:
|
33
|
+
- BSD-2-Clause
|
34
|
+
metadata:
|
35
|
+
homepage_uri: https://github.com/ruby/pstore
|
36
|
+
source_code_uri: https://github.com/ruby/pstore
|
37
|
+
post_install_message:
|
38
|
+
rdoc_options: []
|
39
|
+
require_paths:
|
40
|
+
- lib
|
41
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
42
|
+
requirements:
|
43
|
+
- - ">="
|
44
|
+
- !ruby/object:Gem::Version
|
45
|
+
version: '0'
|
46
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
47
|
+
requirements:
|
48
|
+
- - ">="
|
49
|
+
- !ruby/object:Gem::Version
|
50
|
+
version: '0'
|
51
|
+
requirements: []
|
52
|
+
rubygems_version: 3.0.3
|
53
|
+
signing_key:
|
54
|
+
specification_version: 4
|
55
|
+
summary: Transactional File Storage for Ruby Objects
|
56
|
+
test_files: []
|