7.3.48. reference_acquire

7.3.48.1. 概要

バージョン 10.0.4 で追加.

reference_acquire は対象オブジェクトの参照を1つ増やします。

このコマンドはリファレンスカウントモードのとき以外は意味がありません。リファレンスカウントモードを有効にするには GRN_ENABLE_REFERENCE_COUNT=yes 環境変数を使います。

オブジェクトの参照を1つ増やすとそのオブジェクトは自動的にクローズされません。なぜなら少なくとも1つそのオブジェクトの参照があるからです。短期間に複数の load を実行する場合、リファレンスカウントモードによる自動クローズは性能劣化を引き起こすでしょう。 reference_acquire を実行してから複数の load 実行し、 load の後に reference_release を実行するとこの性能劣化を避けることができます。 reference_acquirereference_release の間は自動クローズが無効になります。

性能に影響がある操作を実行したら reference_release を実行しなければいけません。 reference_release を実行しないとリファレンスカウントモードが動きません。

7.3.48.2. 構文

このコマンドには2つの引数があります。

すべての引数は省略可能です:

reference_acquire [target_name=null]
                  [recursive=yes]

7.3.48.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 を実行するときは、次のコマンドで UsersUsers.ageUsers.introduction の参照を1つ増やします。

実行例:

reference_acquire --target_name Users
# [[0, 1337566253.89858, 0.000355720520019531], true]

Users テーブルに対してインデックスを使う条件で複数の select を実行するときは、次のコマンドで UsersUsers.ageUsers.introductionAges (語彙表)と 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.48.4. 引数

このセクションではすべての引数について説明します。

7.3.48.4.1. 必須引数

必須の引数はありません。

7.3.48.4.2. 省略可能引数

いくつか省略可能な引数があります。

7.3.48.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.48.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_acquireUsers テーブルだけの参照を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 にソースカラムがある)

  • 関連するインデックスカラムのテーブルのカラム

これは loadselect 用に参照を維持するために便利です。

Users テーブルに対して複数の load を実行するときは、次のコマンドを使います。

実行例:

reference_acquire --target_name Users --recursive dependent
# [[0, 1337566253.89858, 0.000355720520019531], true]

7.3.48.5. 戻り値

このコマンドが成功したときは以下のようにボディは true になります:

[HEADER, true]

このコマンドが失敗すると、 HEADER にエラーの詳細が含まれます。

HEADER については 出力形式 を参照してください。