class PStore (Ruby 3.1 リファレンスマニュアル)

要約

Rubyのオブジェクトを外部ファイルに格納するためのクラスです。内部で Marshal を使っています。

使い方

データベースにアクセスするためには、 transaction のブロック内である必要があります。インターフェースは Hash に似ています。

require 'pstore'
db = PStore.new("/tmp/foo")
db.transaction do
  p db.roots       # => []
  ary = db["root"] = [1,2,3,4]
  ary[0] = [1,1.5]
end

db.transaction do
  p db["root"]     # => [[1, 1.5], 2, 3, 4]
end

特異メソッド

new(file, thread_safe = false) -> PStore[permalink][rdoc][edit]

ファイル名 file に対してデータベースを読み書きします。

データベースを更新するときにバックアップファイルが作成されるため、 file のあるディレクトリは書き込み可能である必要があります。データベースの更新が成功すると、バックアップファイルは削除されます。バックアップファイル名はファイル名に ".tmp" および ".new" を付けたものです。

[PARAM] file:: データベースファイル名。
[PARAM] thread_safe:: 真を指定すると Thread::Mutex を用いてスレッドセーフになります。デフォルトは偽です。

インスタンスメソッド

self[name] -> object[permalink][rdoc][edit]

ルートnameに対応する値を得ます。

[PARAM] name:: 探索するルート。
[EXCEPTION] PStore::Error:: トランザクション外でこのメソッドが呼び出された場合に発生します。

[SEE_ALSO] Hash#[]

self[name] = value[permalink][rdoc][edit]

ルート name に対応する値 value をセットします。

[PARAM] name:: ルート。
[PARAM] value:: 格納する値。
[EXCEPTION] PStore::Error:: トランザクション外でこのメソッドが呼び出された場合に発生します。

[SEE_ALSO] Hash#[]=

abort -> ()[permalink][rdoc][edit]

データベースの読み書きを終了します。

transaction ブロックから抜けますが、データベースの変更は反映されません。

[EXCEPTION] PStore::Error:: トランザクション外でこのメソッドが呼び出された場合に発生します。

例:

require 'pstore'
db = PStore.new("/tmp/foo")
db.transaction do
  p db.roots       # => []
  ary = db["root"] = [1,2,3,4]
  db.abort
  ary[0] = [1,1.5] # => ここは実行されない。
end

db.transaction do |pstore|
  pstore["root"]       # => nil
end

commit -> ()[permalink][rdoc][edit]

データベースの読み書きを終了します。

transaction ブロックから抜け、データベースの変更が反映されます。

[EXCEPTION] PStore::Error:: トランザクション外でこのメソッドが呼び出された場合に発生します。

例:

require 'pstore'
db = PStore.new("/tmp/foo")
db.transaction do
  p db.roots       # => []
  ary = db["root"] = [1,2,3,4]
  db.commit
  ary[0] = [1,1.5] # => ここは実行されない。
end

db.transaction do |pstore|
  pstore["root"]       # => [[1, 2, 3, 4]
end

delete(name) -> object[permalink][rdoc][edit]

ルートnameに対応する値を削除します。

[PARAM] name:: 探索するルート。
[RETURN]: 削除した値を返します。
[EXCEPTION] PStore::Error:: トランザクション外でこのメソッドが呼び出された場合に発生します。

例:

require 'pstore'
db = PStore.new("/tmp/foo")
db.transaction do
  p db.roots       # => []
  ary = db["root"] = [1,2,3,4]
  ary[0] = [1,1.5]
end

db.transaction do |pstore|
  pstore.delete("root")       # => [[1, 1.5], 2, 3, 4]
  pstore.delete("root")       # => nil
end

[SEE_ALSO] Hash#delete

fetch(name, default = PStore::Error) -> object[permalink][rdoc][edit]

ルートnameに対応する値を得ます。

該当するルートが登録されていない時には、引数 default が与えられていればその値を返し、与えられていなければ例外 PStore::Error が発生します。

[PARAM] name:: 探索するルート。
[PARAM] default:: name に対応するルートが登録されていない場合に返す値を指定する。
[EXCEPTION] PStore::Error:: name に対応するルートが登録されていないかつ、 default が与えられていない場合に発生します。また、トランザクション外でこのメソッドが呼び出された場合に発生します。

例:

require 'pstore'
db = PStore.new("/tmp/foo")
db.transaction do
  p db.roots       # => []
  ary = db["root"] = [1,2,3,4]
  ary[0] = [1,1.5]
end

db.transaction(true) do |pstore|
  pstore.fetch("root")        # => [[1, 1.5], 2, 3, 4]
  pstore.fetch("root", 'aaa') # => [[1, 1.5], 2, 3, 4]
  pstore.fetch("not_root")    # => 例外発生
end

[SEE_ALSO] Hash#fetch, PStore#[]

path -> String[permalink][rdoc][edit]

データベースのファイル名を得ます。

root?(name) -> bool[permalink][rdoc][edit]

ルート name がデータベースに格納されている場合に真を返します。

[PARAM] name:: 探索するルート。
[EXCEPTION] PStore::Error:: トランザクション外でこのメソッドが呼び出された場合に発生します。

[SEE_ALSO] Hash#key?

roots -> Array[permalink][rdoc][edit]

ルートの集合を配列で返します。

[EXCEPTION] PStore::Error:: トランザクション外でこのメソッドが呼び出された場合に発生します。

[SEE_ALSO] Hash#keys

transaction(read_only = false) {|pstore| ... } -> object[permalink][rdoc][edit]

トランザクションに入ります。このブロックの中でのみデータベースの読み書きができます。

読み込み専用のトランザクションが使用可能です。

[PARAM] read_only:: 真を指定すると、読み込み専用のトランザクションになります。
[RETURN]: ブロックで最後に評価した値を返します。
[EXCEPTION] PStore::Error:: read_only を真にしたときに、データベースを変更しようした場合に発生します。

例:

require 'pstore'
db = PStore.new("/tmp/foo")
db.transaction do
  p db.roots       # => []
  ary = db["root"] = [1,2,3,4]
  ary[0] = [1,1.5]
end

db.transaction(true) do |pstore|
  pstore["root"] = 'aaa' # => ここで例外発生
end

ultra_safe -> bool[permalink][rdoc][edit]

真であれば、パフォーマンスと引き換えにファイル更新の衝突を避けることができます。デフォルトは偽です。

このフラグの効果があるのは一部のプラットフォームだけです。 (e.g. all POSIX platforms: Linux, Mac OS X, FreeBSD, etc)

ultra_safe=(flag)[permalink][rdoc][edit]

真をセットすると、パフォーマンスと引き換えにファイル更新の衝突を避けることができます。

このフラグの効果があるのは一部のプラットフォームだけです。 (e.g. all POSIX platforms: Linux, Mac OS X, FreeBSD, etc)

[PARAM] flag:: 真偽値を指定します。

privateメソッド

in_transaction -> ()[permalink][rdoc][edit]: トランザクションの中でなければ例外を発生させます。

定数

EMPTY_MARSHAL_CHECKSUM -> String[permalink][rdoc][edit]: 内部で利用する定数です。
EMPTY_MARSHAL_DATA -> String[permalink][rdoc][edit]: 内部で利用する定数です。
EMPTY_STRING -> String[permalink][rdoc][edit]: 内部で利用する定数です。
RDWR_ACCESS -> Integer[permalink][rdoc][edit]: 内部で利用する定数です。
RD_ACCESS -> Integer[permalink][rdoc][edit]: 内部で利用する定数です。
WR_ACCESS -> Integer[permalink][rdoc][edit]: 内部で利用する定数です。

要約

使い方

目次

特異メソッド

インスタンスメソッド

privateメソッド

定数