7.25.8. grn_ctx

7.25.8.1. 概要

grn_ctx は最も重要なオブジェクトです。grn_ctx はその時点の情報を保持します:

grn_ctx は基盤となる機能を提供します:

  • メモリ管理機能

  • ロギング機能

ほとんどのAPIは grn_ctx を最初の引数にとります。

同じ grn_ctx を二つ以上のスレッドからは扱えません。grn_ctx はスレッドごとに作成する必要があります。一つのスレッドでは grn_ctx を二つ以上扱えますが、通常はその必要はありません。

7.25.8.2.

TODO...

7.25.8.3. リファレンス

type grn_ctx

TODO...

grn_rc grn_ctx_init(grn_ctx *ctx, int flags)

ctxを初期化します。

パラメータ
  • ctx -- 初期化するctx構造体へのポインタを指定します。

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

戻り値

成功時は GRN_SUCCESS 、エラー時は GRN_SUCCESS 以外。

grn_rc grn_ctx_fin(grn_ctx *ctx)

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

grn_ctx_init() ではなく grn_ctx_open()ctx を初期化した場合、 grn_ctx_fin() ではなく grn_ctx_close() を使わなければいけません。

パラメータ
  • ctx -- 解放するctx構造体へのポインタを指定します。

戻り値

成功時は GRN_SUCCESS 、エラー時は GRN_SUCCESS 以外。

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() によって解放しても問題ありません。

パラメータ
  • flags -- 初期化する ctx のオプションを指定します。

戻り値

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

grn_rc grn_ctx_close(grn_ctx *ctx)

grn_ctx_fin() を呼び出し、その後、 grn_ctx_open() によって割り当てた ctx のメモリを解放する。

パラメータ
  • ctx -- もう使わない grn_ctx

戻り値

成功時は GRN_SUCCESS 、エラー時は GRN_SUCCESS 以外。

grn_rc grn_ctx_set_finalizer(grn_ctx *ctx, grn_proc_func *func)

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

パラメータ
  • ctx -- 対象ctxを指定します。

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

戻り値

成功時は GRN_SUCCESS 、エラー時は GRN_SUCCESS 以外。

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を変更します。

パラメータ
  • version -- 変更後のcommand_versionを指定します。

grn_rc grn_ctx_use(grn_ctx *ctx, grn_obj *db)

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

GRN_CTX_PER_DB フラグを指定した grn_ctx と一緒に使ってはいけません。

パラメータ
  • 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を返す。

パラメータ
  • name -- 検索しようとするオブジェクトの名前。

  • name_size -- 名前のバイト数。負の値が指定された場合は、終端をNULL文字とした文字列として扱われる。

grn_obj *grn_ctx_at(grn_ctx *ctx, grn_id id)

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

パラメータ
  • 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.

以下は例です。

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);
パラメータ
  • ctx -- その時点のコンテキスト。

  • table_buffer -- The output buffer to store tables.

戻り値

成功時は GRN_SUCCESS 、エラー時は GRN_SUCCESS 以外。

grn_content_type grn_ctx_get_output_type(grn_ctx *ctx)

コンテキストの出力形式を取得します。

Normally, this function isn't needed.

パラメータ
  • ctx -- その時点のコンテキスト。

戻り値

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.

パラメータ
  • ctx -- その時点のコンテキスト。

  • type -- 新しい出力形式。

戻り値

成功時は GRN_SUCCESS 、エラー時は GRN_SUCCESS 以外。

grn_bool_rc grn_ctx_is_opened(grn_ctx *ctx, grn_id id)

指定したIDのオブジェクトが開かれているかどうかをチェックします。

パラメータ
  • ctx -- その時点のコンテキスト。

  • id -- チェック対象のオブジェクトのID。

戻り値

指定したIDのオブジェクトが開かれていたら GRN_TRUE 、そうでなければ GRN_FALSE