7.3.49. reference_acquire

7.3.49.1. Summary

New in version 10.0.4.

reference_acquire acquires a reference of target objects.

This command is meaningless unless you use the reference count mode. You can enable the reference count mode by the GRN_ENABLE_REFERENCE_COUNT=yes environment variable.

If you acquires a reference of an object, the object isn’t closed automatically because you have at least one reference of the object. If you need to call multiple load in a short time, auto close by the reference count mode will degrade performance. You can avoid the performance degrading by calling reference_acquire before multiple load and calling reference_release after multiple load. Between reference_acquire and reference_release, auto close is disabled.

You must call reference_release after you finish performance impact operations. If you don’t call reference_release, the reference count mode doesn’t work.

You can use auto_release_count instead of calling reference_release. You can release acquired references automatically by auto_release_count. But you need to tune suitable auto_release_count value. If you specify too large number, auto close isn’t triggered. If you specify too small number, auto close is triggered before performance impact operations are finished.

7.3.49.2. Syntax

This command takes two parameters.

All parameters are optional:

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

7.3.49.3. Usage

You can acquire a reference of the all objects with no arguments:

Execution example:

reference_acquire
# [[0, 1337566253.89858, 0.000355720520019531], true]

If you know what should be referred, you can narrow targets.

Here is a schema definition to show usage:

Execution example:

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]

If you want to call multiple select without any condition against Users table, the following command acquires a reference of Users, Users.age and Users.introduction:

Execution example:

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

If you want to call multiple select with condition that uses indexes against Users table, the following command acquires a reference of Users, Users.age, Users.introduction, Ages (lexicon) and Ages.user_age (index column). This command is suitable for load too:

Execution example:

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

If you want to just refer Users, you can specify a table with recursive=no:

Execution example:

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

If you want to just refer Users.introduction, you can specify a column:

Execution example:

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

You can release acquired references by calling reference_release with the same arguments:

Execution example:

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. Parameters

This section describes all parameters.

7.3.49.4.1. Required parameters

There is no required parameter.

7.3.49.4.2. Optional parameters

There are optional parameters.

7.3.49.4.2.1. target_name

Specifies a target object name. Target object is one of database, table or column.

If you omit this parameter, database is the target object:

Execution example:

reference_acquire
# [[0, 1337566253.89858, 0.000355720520019531], true]

If you specify a table name, the table is the target object:

Execution example:

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

If you specify a column name, the column is the target object:

Execution example:

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

7.3.49.4.2.2. recursive

Specifies whether child objects of the target object are also target objects.

Child objects of database are all tables and all columns.

Child objects of table are all its columns.

Child objects of column are nothing.

recursive value must be yes, no or dependent. yes means that all of the specified target object and child objects are the target objects. no means that only the specified target object is the target object. dependent means that all of the specified target object, child objects, corresponding table of index column and corresponding index column are the target objects.

The following reference_acquire acquires a reference of all tables and all columns:

Execution example:

reference_acquire --recursive yes
# [[0, 1337566253.89858, 0.000355720520019531], true]

The following reference_acquire acquires a reference of only Users table:

Execution example:

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

If you specify other value (not yes neither no) or omit recursive parameter, yes is used.

yes is used in the following case because invalid recursive argument is specified:

Execution example:

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

yes is used in the following case because recursive parameter isn’t specified:

Execution example:

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

dependent acquires a reference of not only the target object and the child objects but also related objects. The related objects are:

  • A referenced table

  • Data columns of referenced tables

  • A related index column (There is source column in target TABLE_NAME)

  • A table of related index column (There is source column in target TABLE_NAME)

  • Data columns of tables of related index columns

It is useful to keep reference for load and select.

If you want to call multiple load for Users table, you can use the following command:

Execution example:

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

7.3.49.4.2.3. auto_release_count

New in version 10.0.9.

You can release acquired references automatically by auto_release_count.

If auto_release_count is 1 or greater, acquired references are automatically after the following auto_release_count commands are processed. You must not call corresponding reference_release when you use auto_release_count.

In the following example, the acquired reference of Users is released automatically after the second status is processed:

reference_acquire --target_name Users --auto_release_count 2
status # Users is still referred.
status # Users' reference is released after this command is processed.

The same recursive is used when acquired references are released automatically. You don’t need to care about recursive.

auto_release_count is safe with table_remove, column_remove and database_unmap. If one of them are called, registered auto release hook is removed internally.

7.3.49.5. Return value

The command returns true as body on success such as:

[HEADER, true]

If the command fails, error details are in HEADER.

See Output format for HEADER.