# 7.3.49. `reference_acquire`

## 7.3.49.1. 概要

バージョン 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.49.2. 構文

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

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

    reference_acquire [target_name=null]
                      [recursive=yes]
                      [auto_release_count=0]

## 7.3.49.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.49.4. 引数

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

### 7.3.49.4.1. 必須引数

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

### 7.3.49.4.2. 省略可能引数

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

#### 7.3.49.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.49.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.49.4.2.3. `auto_release_count`

バージョン 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.49.5. 戻り値

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

    [HEADER, true]

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

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