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.