7.25.8. grn_ctx

7.25.8.1. Summary

grn_ctx is the most important object. grn_ctx keeps the current information such as:

grn_ctx provides platform features such as:

  • Memory management.

  • Logging.

Most APIs receive grn_ctx as the first argument.

You can’t use the same grn_ctx from two or more threads. You need to create a grn_ctx for a thread. You can use two or more grn_ctx in a thread but it is not needed for usual use-case.

7.25.8.2. Example

TODO…

7.25.8.3. Reference

type grn_ctx

TODO…

grn_rc grn_ctx_init(grn_ctx *ctx, int flags)

ctxを初期化します。

Parameters:
  • ctx – 初期化するctx構造体へのポインタを指定します。

  • flags – 初期化する ctx のオプションを指定します。

Returns:

GRN_SUCCESS on success, not GRN_SUCCESS on error.

grn_rc grn_ctx_fin(grn_ctx *ctx)

ctxの管理するメモリを解放し、使用を終了します。

If ctx is initialized by grn_ctx_open() not grn_ctx_init(), you need to use grn_ctx_close() instead of grn_ctx_fin().

Parameters:
  • ctx – 解放するctx構造体へのポインタを指定します。

Returns:

GRN_SUCCESS on success, not GRN_SUCCESS on error.

grn_ctx *grn_ctx_open(int flags)

初期化された grn_ctx オブジェクトを返します。

grn_ctx_init() で初期化された grn_ctx オブジェクトは構造体の実体をAPIの呼び元で確保するのに対して、 grn_ctx_open() ではGroongaライブラリの内部で、実体を確保します。 どちらで初期化された grn_ctx も、 grn_ctx_fin() で解放できます。 grn_ctx_open() で確保した grn_ctx 構造体に関しては、grn_ctx_fin() で解放した後に、その grn_ctx で作成した grn_objgrn_obj_close() によって解放しても問題ありません。

Parameters:
  • flags – 初期化する ctx のオプションを指定します。

Returns:

初期化された grn_ctx オブジェクトを返します。

grn_rc grn_ctx_close(grn_ctx *ctx)

It calls grn_ctx_fin() and frees allocated memory for ctx by grn_ctx_open().

Parameters:
  • ctx – no longer needed grn_ctx.

Returns:

GRN_SUCCESS on success, not GRN_SUCCESS on error.

grn_rc grn_ctx_set_finalizer(grn_ctx *ctx, grn_proc_func *func)

ctxを破棄するときに呼ばれる関数を設定します。

Parameters:
  • ctx – 対象ctxを指定します。

  • funcctx を破棄するときに呼ばれる関数を指定します。

Returns:

GRN_SUCCESS on success, not GRN_SUCCESS on error.

grn_command_version grn_ctx_get_command_version(grn_ctx *ctx)

command_versionを返します。

grn_rc grn_ctx_set_command_version(grn_ctx *ctx, grn_command_version version)

command_versionを変更します。

Parameters:
  • version – 変更後のcommand_versionを指定します。

grn_rc grn_ctx_use(grn_ctx *ctx, grn_obj *db)

ctxが操作対象とするdbを指定します。NULLを指定した場合は、dbを操作しない状態(init直後の状態)になります。

Don’t use it with grn_ctx that has GRN_CTX_PER_DB flag.

Parameters:
  • db – ctxが使用するdbを指定します。

grn_obj *grn_ctx_db(grn_ctx *ctx)

ctxが現在操作対象としているdbを返します。dbを使用していない場合はNULLを返します。

grn_obj *grn_ctx_get(grn_ctx *ctx, const char *name, int name_size)

ctxが使用するdbからnameに対応するオブジェクトを検索して返す。nameに一致するオブジェクトが存在しなければNULLを返す。

Parameters:
  • name – 検索しようとするオブジェクトの名前。

  • name_size – The number of bytes of name. If negative value is specified, name is assumed that NULL-terminated string.

grn_obj *grn_ctx_at(grn_ctx *ctx, grn_id id)

ctx、またはctxが使用するdbからidに対応するオブジェクトを検索して返す。idに一致するオブジェクトが存在しなければNULLを返す。

Parameters:
  • id – 検索しようとするオブジェクトのidを指定します。

grn_rc grn_ctx_get_all_tables(grn_ctx *ctx, grn_obj *tables_buffer)

It pushes all tables in the database of ctx into tables_buffer. tables_buffer should be initialized as GRN_PVECTOR. You can use GRN_PTR_INIT() with GRN_OBJ_VECTOR flags to initialize tables_buffer.

Here is an example:

grn_rc rc;
grn_obj tables;
int i;
int n_tables;

GRN_PTR_INIT(&tables, GRN_OBJ_VECTOR, GRN_ID_NIL);
rc = grn_ctx_get_all_tables(ctx, &tables);
if (rc != GRN_SUCCESS) {
  GRN_OBJ_FIN(ctx, &tables);
  /* Handle error. */
  return;
}

n_tables = GRN_BULK_VSIZE(&tables) / sizeof(grn_obj *);
for (i = 0; i < n_tables; i++) {
  grn_obj *table = GRN_PTR_VALUE_AT(&tables, i);
  /* Use table. */
}

/* Free resources. */
for (i = 0; i < n_tables; i++) {
  grn_obj *table = GRN_PTR_VALUE_AT(&tables, i);
  grn_obj_unlink(ctx, table);
}
GRN_OBJ_FIN(ctx, &tables);
Parameters:
  • ctx – The context object.

  • table_buffer – The output buffer to store tables.

Returns:

GRN_SUCCESS on success, not GRN_SUCCESS on error.

grn_content_type grn_ctx_get_output_type(grn_ctx *ctx)

Gets the current output type of the context.

Normally, this function isn’t needed.

Parameters:
  • ctx – The context object.

Returns:

The output type of the context.

grn_rc grn_ctx_set_output_type(grn_ctx *ctx, grn_content_type type)

Sets the new output type to the context. It is used by executing a command by grn_expr_exec(). If you use grn_ctx_send(), the new output type isn’t used. grn_ctx_send() sets output type from command line internally.

Normally, this function isn’t needed.

Parameters:
  • ctx – The context object.

  • type – The new output type.

Returns:

GRN_SUCCESS on success, not GRN_SUCCESS on error.

grn_bool_rc grn_ctx_is_opened(grn_ctx *ctx, grn_id id)

Checks whether object with the ID is opened or not.

Parameters:
  • ctx – The context object.

  • id – The object ID to be checked.

Returns:

GRN_TRUE if object with the ID is opened, GRN_FALSE otherwise.