7.3.50. reference_acquire#
7.3.50.1. 概要#
Added in version 10.0.4.
reference_acquire は対象オブジェクトの参照を1つ増やします。
このコマンドはリファレンスカウントモードのとき以外は意味がありません。リファレンスカウントモードを有効にするには GRN_ENABLE_REFERENCE_COUNT=yes 環境変数を使います。
オブジェクトの参照を1つ増やすとそのオブジェクトは自動的にクローズされません。なぜなら少なくとも1つそのオブジェクトの参照があるからです。短期間に複数の load を実行する場合、リファレンスカウントモードによる自動クローズは性能劣化を引き起こすでしょう。 reference_acquire を実行してから複数の load 実行し、 load の後に reference_release を実行するとこの性能劣化を避けることができます。 reference_acquire と reference_release の間は自動クローズが無効になります。
性能に影響がある操作を実行したら reference_release を実行しなければいけません。 reference_release を実行しないとリファレンスカウントモードが動きません。
reference_release を呼ぶ代わりに auto_release_count を使うこともできます。 auto_release_count を使うと増やした参照を自動で減らせます。しかし、適切な auto_release_count を見つける必要があります。もし、大きすぎる数値を指定すると、自動クローズがなかなか動きません。もし、小さすぎる数値を指定すると、性能に影響がある操作が終わる前に自動クローズが動いてしまいます。
7.3.50.2. 構文#
このコマンドには2つの引数があります。
すべての引数は省略可能です:
reference_acquire [target_name=null]
[recursive=yes]
[auto_release_count=0]
7.3.50.3. 使い方#
引数無しで実行するとすべてのテーブル・カラムの参照を1つ増やすことができます。
実行例:
reference_acquire
# [[0,1337566253.89858,0.000355720520019531],true]
なにを参照するべきかわかっているなら対象を狭めることができます。
使い方を示すために使うスキーマ定義は以下の通りです。
実行例:
table_create Users TABLE_HASH_KEY ShortText
# [[0,1337566253.89858,0.000355720520019531],true]
column_create Users age COLUMN_SCALAR UInt8
# [[0,1337566253.89858,0.000355720520019531],true]
column_create Users introduction COLUMN_SCALAR ShortText
# [[0,1337566253.89858,0.000355720520019531],true]
table_create Ages TABLE_PAT_KEY UInt8
# [[0,1337566253.89858,0.000355720520019531],true]
column_create Ages user_age COLUMN_INDEX Users age
# [[0,1337566253.89858,0.000355720520019531],true]
Users テーブルに対して条件なしの複数の select を実行するときは、次のコマンドで Users と Users.age と Users.introduction の参照を1つ増やします。
実行例:
reference_acquire --target_name Users
# [[0,1337566253.89858,0.000355720520019531],true]
Users テーブルに対してインデックスを使う条件で複数の select を実行するときは、次のコマンドで Users と Users.age と Users.introduction と Ages （語彙表）と Ages.user_age （インデックスカラム）の参照を1つ増やせます。このコマンドは load を実行するときでも適切です。
実行例:
reference_acquire --target_name Users --recursive dependent
# [[0,1337566253.89858,0.000355720520019531],true]
単に Users の参照を1つ増やしたいだけなら、テーブルと recursive=no を指定します。
実行例:
reference_acquire --target_name Users --recursive no
# [[0,1337566253.89858,0.000355720520019531],true]
単に Users.introduction の参照を1つ増やしたいだけなら、カラムを指定します。
実行例:
reference_acquire --target_name Users.introduction
# [[0,1337566253.89858,0.000355720520019531],true]
同じ引数で reference_release を実行すると増やした参照を1つ減らせます。
実行例:
reference_acquire --target_name Users --recursive dependent
# [[0,1337566253.89858,0.000355720520019531],true]
# select Users ...
# load --table Users ...
reference_release --target_name Users --recursive dependent
# [[0,1337566253.89858,0.000355720520019531],true]
7.3.50.4. 引数#
このセクションではすべての引数について説明します。
7.3.50.4.1. 必須引数#
必須の引数はありません。
7.3.50.4.2. 省略可能引数#
いくつか省略可能な引数があります。
7.3.50.4.2.1. target_name#
対象オブジェクトの名前を指定します。対象オブジェクトはデータベース、テーブル、カラムのどれかです。
このパラメーターを省略すると、データベースが対象オブジェクトになります。
実行例:
reference_acquire
# [[0,1337566253.89858,0.000355720520019531],true]
テーブル名を指定すると、そのテーブルが対象オブジェクトになります。
実行例:
reference_acquire --target_name Users
# [[0,1337566253.89858,0.000355720520019531],true]
カラム名を指定すると、そのカラムが対象オブジェクトになります。
実行例:
reference_acquire --target_name Users.age
# [[0,1337566253.89858,0.000355720520019531],true]
7.3.50.4.2.2. recursive#
書き出し対象オブジェクトの子オブジェクトも対象にするかどうかを指定します。
データベースの子オブジェクトはすべてのテーブルとすべてのカラムです。
テーブルの子オブジェクトはそのテーブルのすべてのカラムです。
カラムの子オブジェクトはありません。
recursive の値は yes または no もしくは dependent でなければいけません。 yes は指定した対象オブジェクトとその子オブジェクトすべてを対象オブジェクトにするという意味です。 no は指定した対象オブジェクトのみを対象オブジェクトにするという意味です。dependent は指定した対象オブジェクトとその子オブジェクトすべて、参照先のテーブル、インデックスが張られているカラムがある場合、対応するインデックスカラムとそのインデックスカラムのテーブルを対象オブジェクトにするという意味です。
次の reference_acquire はデータベースとすべてのテーブルとすべてのカラムの参照を1つ増やします。
実行例:
reference_acquire --recursive yes
# [[0,1337566253.89858,0.000355720520019531],true]
次の reference_acquire は Users テーブルだけの参照を1つ増やします。
実行例:
reference_acquire --target_name Users --recursive no
# [[0,1337566253.89858,0.000355720520019531],true]
他の値（つまり、 yes でも no でもない値）を指定した場合、または recursive パラメーターを指定しない場合は yes が使われます。
recursive 引数の値が不正なので、次のケースでは yes が使われます。
実行例:
reference_acquire --target_name Users --recursive invalid
# [[0,1337566253.89858,0.000355720520019531],true]
recursive パラメーターが指定されていないので、次のケースでは yes が使われます。
実行例:
reference_acquire --target_name Users
# [[0,1337566253.89858,0.000355720520019531],true]
dependent は対象オブジェクトとその子オブジェクトの参照を1つ増やすだけではなく、関連するオブジェクトの参照も1つ増やします。関連するオブジェクトは次のとおりです。
参照されているテーブル
参照されているテーブルのデータカラム
関連するインデックスカラム(対象の
TABLE_NAMEにソースカラムがある)関連するインデックスカラムのテーブル(対象の
TABLE_NAMEにソースカラムがある)関連するインデックスカラムのテーブルのデータカラム
これは load と select 用に参照を維持するために便利です。
Users テーブルに対して複数の load を実行するときは、次のコマンドを使います。
実行例:
reference_acquire --target_name Users --recursive dependent
# [[0,1337566253.89858,0.000355720520019531],true]
7.3.50.4.2.3. auto_release_count#
Added in version 10.0.9.
auto_release_count を使うと増やした参照を自動で減らせます。
auto_release_count が1以上の場合、後続する auto_release_count 個のコマンドを実行した後に増やした参照を自動的に減らします。 auto_release_count を使った場合は対応する reference_release を呼んではいけません。
以下の例では、増やした Users の参照を2つ目の status を実行した後に自動的に減らします。
reference_acquire --target_name Users --auto_release_count 2
status # Users is still referred.
status # Users' reference is released after this command is processed.
増やした参照を自動的に減らすときは、同じ recursive を使います。 recursive のことを気にする必要はありません。
auto_release_count は table_remove ・ column_remove ・ database_unmap と一緒に使っても安全です。これらのうちどれかのコマンドが呼ばれた場合は、登録されている自動で参照を減らす処理は内部的に削除されます。
7.3.50.5. 戻り値#
このコマンドが成功したときは以下のようにボディは true になります:
[HEADER, true]
このコマンドが失敗すると、 HEADER にエラーの詳細が含まれます。
HEADER については 出力形式 を参照してください。