Class: Groonga::Array

Inherits:
Table show all
Defined in:
ext/groonga/rb-grn-array.c,
ext/groonga/rb-grn-array.c

Overview

各レコードがキーに関連付けられていないテーブル。レコードは IDで識別する。

Class Method Summary collapse

  • .create ⇒ Object

    キーのないテーブルを生成する。ブロックを指定すると、そのブ ロックに生成したテーブルが渡され、ブロックを抜けると自動的 にテーブルが破棄される。.

Instance Method Summary collapse

Methods inherited from Table

#[], #clear_lock, #column, #column_value, #columns, #define_column, #define_index_column, #defrag, #delete, #difference!, #disk_usage, #each, #each_sub_record, #empty?, #exist?, #geo_sort, #group, #have_column?, #have_n_sub_records_space?, #initialize, #inspect, #intersection!, #lock, #locked?, #merge!, #open_cursor, #paginate, #records, #rename, #select, #set_column_value, #set_value, #size, #sort, #support_key?, #support_sub_records?, #support_value?, #truncate, #union!, #unlock, #value

Methods included from Flushable

#flush

Methods inherited from Object

#==, #[], #[]=, #accessor?, #append, #builtin?, #close, #closed?, #column?, #dirty?, #domain, #function_procedure?, #id, #index_column?, #inspect, #key_accessor?, #last_modified, #name, #path, #persistent?, #prepend, #procedure?, #range, #reference_column?, #remove, #scorer_procedure?, #selector_only_procedure?, #selector_procedure?, #table?, #temporary?, #touch, #unlink, #window_function_procedure?

Constructor Details

This class inherits a constructor from Groonga::Table

Class Method Details

.create(options = {}) ⇒ Groonga::Array .create(options = {}) {|table| ... } ⇒ Object

キーのないテーブルを生成する。ブロックを指定すると、そのブ ロックに生成したテーブルが渡され、ブロックを抜けると自動的 にテーブルが破棄される。

Examples:

#無名一時テーブルを生成する。
Groonga::Array.create

#無名永続テーブルを生成する。
Groonga::Array.create(:path => "/tmp/array.grn")

#名前付き永続テーブルを生成する。ただし、ファイル名は気にしない。
Groonga::Array.create(:name => "Bookmarks",
                      :persistent => true)

#それぞれのレコードに512バイトの値を格納できる無名一時テーブルを生成する。
Groonga::Array.create(:value => 512)

Overloads:

  • .create(options = {}) ⇒ Groonga::Array

    Parameters:

    • options (::Hash) (defaults to: {})

      The name and value pairs. Omitted names are initialized as the default value.

    Options Hash (options):

    • :context (Groonga::Context) — default: Groonga::Context.default

      テーブルが利用する Context

    • :name (Object)

      The name テーブルの名前。名前をつけると、 Context#[] に名 前を指定してテーブルを取得することができる。省略すると 無名テーブルになり、テーブルIDでのみ取得できる。

    • :path (Object)

      テーブルを保存するパス。パスを指定すると永続テーブルとな り、プロセス終了後もレコードは保持される。次回起動時に Context#[] で保存されたレコードを利用することが できる。省略すると一時テーブルになり、プロセスが終了する とレコードは破棄される。

    • :persistent (Object)

      +true+ を指定すると永続テーブルとなる。 +path+ を省略した 場合は自動的にパスが付加される。 +:context+ で指定した Context に結びついているデータベースが一時デー タベースの場合は例外が発生する。

    • :value_type (Object) — default: nil

      値の型を指定する。省略すると値のための領域を確保しない。 値を保存したい場合は必ず指定すること。 参考: Type.new

    • :sub_records (Groonga::Record#n_sub_records)

      +true+ を指定すると Table#group でグループ化したときに、 Record#n_sub_records でグループに含まれるレコー ドの件数を取得できる。

    Returns:

  • .create(options = {}) {|table| ... } ⇒ Object

    Parameters:

    • options (::Hash) (defaults to: {})

      The name and value pairs. Omitted names are initialized as the default value.

    Options Hash (options):

    • :context (Groonga::Context) — default: Groonga::Context.default

      テーブルが利用する Context

    • :name (Object)

      The name テーブルの名前。名前をつけると、 Context#[] に名 前を指定してテーブルを取得することができる。省略すると 無名テーブルになり、テーブルIDでのみ取得できる。

    • :path (Object)

      テーブルを保存するパス。パスを指定すると永続テーブルとな り、プロセス終了後もレコードは保持される。次回起動時に Context#[] で保存されたレコードを利用することが できる。省略すると一時テーブルになり、プロセスが終了する とレコードは破棄される。

    • :persistent (Object)

      +true+ を指定すると永続テーブルとなる。 +path+ を省略した 場合は自動的にパスが付加される。 +:context+ で指定した Context に結びついているデータベースが一時デー タベースの場合は例外が発生する。

    • :value_type (Object) — default: nil

      値の型を指定する。省略すると値のための領域を確保しない。 値を保存したい場合は必ず指定すること。 参考: Type.new

    • :sub_records (Groonga::Record#n_sub_records)

      +true+ を指定すると Table#group でグループ化したときに、 Record#n_sub_records でグループに含まれるレコー ドの件数を取得できる。

    Yields:

    • (table)

      生成されたテーブル。ブロックを抜けると破棄される。



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# File 'ext/groonga/rb-grn-array.c', line 86

static VALUE
rb_grn_array_s_create (int argc, VALUE *argv, VALUE klass)
{
    grn_ctx *context = NULL;
    grn_obj *value_type = NULL, *table;
    const char *name = NULL, *path = NULL;
    unsigned name_size = 0;
    grn_table_flags flags = GRN_OBJ_TABLE_NO_KEY;
    VALUE rb_table;
    VALUE options, rb_context, rb_name, rb_path, rb_persistent;
    VALUE rb_value_type, rb_sub_records;

    rb_scan_args(argc, argv, "01", &options);

    rb_grn_scan_options(options,
                        "context", &rb_context,
                        "name", &rb_name,
                        "path", &rb_path,
                        "persistent", &rb_persistent,
                        "value_type", &rb_value_type,
                        "sub_records", &rb_sub_records,
                        NULL);

    context = rb_grn_context_ensure(&rb_context);

    if (!NIL_P(rb_name)) {
        name = StringValuePtr(rb_name);
        name_size = RSTRING_LEN(rb_name);
        flags |= GRN_OBJ_PERSISTENT;
    }

    if (!NIL_P(rb_path)) {
        path = StringValueCStr(rb_path);
        flags |= GRN_OBJ_PERSISTENT;
    }

    if (RVAL2CBOOL(rb_persistent))
        flags |= GRN_OBJ_PERSISTENT;

    if (!NIL_P(rb_value_type))
        value_type = RVAL2GRNOBJECT(rb_value_type, &context);

    if (RVAL2CBOOL(rb_sub_records))
        flags |= GRN_OBJ_WITH_SUBREC;

    table = grn_table_create(context, name, name_size, path,
                             flags, NULL, value_type);
    if (!table)
        rb_grn_context_check(context, rb_ary_new_from_values(argc, argv));
    rb_table = GRNOBJECT2RVAL(klass, context, table, GRN_TRUE);
    rb_grn_context_check(context, rb_table);
    rb_iv_set(rb_table, "@context", rb_context);

    if (rb_block_given_p())
        return rb_ensure(rb_yield, rb_table, rb_grn_object_close, rb_table);
    else
        return rb_table;
}

Instance Method Details

#add(values = nil) ⇒ Groonga::Recordまたはnil

レコード追加し、追加したレコードを返す。レコードの追加に失 敗した場合は +nil+ を返す。

values にはレコードのカラムに設定する値を指定する。省略 した場合または +nil+ を指定した場合はカラムは設定しない。カ ラムの値は @=> 値1, :カラム名2 => 値2, …@ と指定する。

Examples:

#以下のようなユーザを格納するGroonga::Arrayが
#定義されているものとする。
users = Groonga::Array.create(:name => "Users")
users.define_column("name", "ShortText")
users.define_column("uri", "ShortText")
#ユーザを追加する。
user = users.add

#daijiroユーザを追加する。
daijiro = users.add(:name => "daijiro")

#gunyara-kunユーザを追加する。
gunyara_kun = users.add(:name => "gunyara-kun",
                        :uri => "http://d.hatena.ne.jp/tasukuchan/")

Returns:



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
# File 'ext/groonga/rb-grn-array.c', line 173

static VALUE
rb_grn_array_add (int argc, VALUE *argv, VALUE self)
{
    grn_ctx *context = NULL;
    grn_obj *table;
    grn_id id;
    VALUE values;

    rb_scan_args(argc, argv, "01", &values);

    table = SELF(self, &context);

    id = grn_table_add(context, table, NULL, 0, NULL);
    rb_grn_context_check(context, self);

    if (GRN_ID_NIL == id) {
        return Qnil;
    } else {
        return rb_grn_record_new_added(self, id, values);
    }
}

#pull(options = {}) {|record| ... } ⇒ Groonga::Record or nil

Pulls a record from the array. The required values should be retrieved in the given block.

If #push failes to fill values of the pushed record, the pulled record may be uncompleted. It should be handled by your application.

If you passes @:block? => true@ option, the pull operation blocks until a pushed record is pushed. It is the default behavior.

If you passes @:block? => false@ option, the pull operation returns immediately, the given block isn’t called and returns nil when no record exist in the array.

Note that your signal handlers can’t be ran while a pull operation. You need to use #unblock from another process to unblock the pull operation. If you call #unblock, signal handler can be ran.

Examples:

A program that pulls with non-block mode

queue = Groonga::Array.open(:name => "CrawlURLQueue")
loop do
  url = nil
  # The case for no pushed records in the array.
  pulled_record = queue.pull(:block? => false) do |record|
    # This block isn't called
    url = record.url
    record.delete
  end
  p pulled_record.nil? # => true
end

Signal handler isn’t called

queue = Groonga::Array.open(:name => "CrawlURLQueue")
trap(:INT) do
  p :not_called!
end
queue.pull do |record|
  # Send SIGINT while blocking the pull operation.
  # The signal handler isn't called.
end

Returns A pulled record that is yielded.

Parameters:

  • options (::Hash) (defaults to: {})

    The option parameters.

Options Hash (options):

  • :block? (Boolean) — default: true

    Whether the pull operation is blocked or not when no record exist in the array.

Yields:

  • (record)

    Gets required values for a pull record in the given block.

Yield Parameters:

  • record (Groonga::Record or nil)

    A pulled record. It is nil when no records exist in the array and @block?@ parameter is not @true@.

Returns:

See Also:



385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
# File 'ext/groonga/rb-grn-array.c', line 385

static VALUE
rb_grn_array_pull (int argc, VALUE *argv, VALUE self)
{
    grn_ctx *context = NULL;
    grn_obj *table;
    VALUE options;
    VALUE rb_block_p;
    YieldRecordCallbackData data;

    rb_scan_args(argc, argv, "01", &options);

    rb_grn_scan_options(options,
                        "block?", &rb_block_p,
                        NULL);

    if (!rb_block_given_p()) {
        rb_raise(rb_eArgError,
                 "tried to call Groonga::Array#pull without a block");
    }

    table = SELF(self, &context);

    if (NIL_P(rb_block_p)) {
        rb_block_p = Qtrue;
    }

    data.self = self;
    data.record = Qnil;
    data.status = 0;
    grn_array_pull(context, (grn_array *)table, RVAL2CBOOL(rb_block_p),
                   yield_record_callback, &data);
    if (data.status != 0) {
        rb_jump_tag(data.status);
    }
    rb_grn_context_check(context, self);

    return data.record;
}

#push {|record| ... } ⇒ Groonga::Record or nil

Pushes a record to the array. The record should be filled in the given block. The pushed record can be pulled by #pull.

The record that is passed to the given block may be nil. You need to handle the case. For example, just ignoring it or reports an error.

If an error is occurred in the given block, the pushed record may not be filled completely. You should handle the case in pull side.

Examples:

A program that pushes a job without error handling

queue = Groonga::Array.create(:name => "CrawlURLQueue")
queue.define_column("url", "ShortText")
urls = ["http://groonga.org/", "http://ranguba.org/"]
urls.each do |url|
  queue.push do |record|
    record.url = url
  end
end

A program that pulls a job without error handling

queue = Groonga::Array.open(:name => "CrawlURLQueue")
loop do
  url = nil
  queue.pull do |record|
    url = record.url
    record.delete
  end
  # Crawl URL
end

A program that pushes a job with error handling

queue = Groonga::Array.create(:name => "CrawlURLQueue")
queue.define_column("url", "ShortText")
urls = ["http://groonga.org/", "http://ranguba.org/"]
urls.each do |url|
  queue.push do |record|
    record.url = url if record # check record is not nil
  end
end

A program that has an error in push block

queue = Groonga::Array.create(:name => "CrawlURLQueue")
queue.define_column("url", "ShortText")
urls = ["http://groonga.org/", "http://ranguba.org/"]
urls.each do |url|
  queue.push do |record|
    record.url = uri # Typo! It should be ur*l* not ur*i*
    # record.url isn't set
  end
end

A program that pulls a job with error handling

queue = Groonga::Array.open(:name => "CrawlURLQueue")
loop do
  url = nil
  queue.pull do |record|
    url = record.url # record.url is nil!
    record.delete
  end
  next if url.nil? # Ignore an uncompleted added job
  # Crawl URL
end

Returns A pushed record that is yielded.

Yields:

  • (record)

    Filles columns of a pushed record in the given block.

Yield Parameters:

  • record (Groonga::Record or nil)

    A pushed record. It is nil when pushing is failed.

Returns:



302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
# File 'ext/groonga/rb-grn-array.c', line 302

static VALUE
rb_grn_array_push (VALUE self)
{
    grn_ctx *context = NULL;
    grn_obj *table;
    YieldRecordCallbackData data;

    if (!rb_block_given_p()) {
        rb_raise(rb_eArgError,
                 "tried to call Groonga::Array#push without a block");
    }

    table = SELF(self, &context);

    data.self = self;
    data.record = Qnil;
    data.status = 0;
    grn_array_push(context, (grn_array *)table, yield_record_callback, &data);
    if (data.status != 0) {
        rb_jump_tag(data.status);
    }
    rb_grn_context_check(context, self);

    return data.record;
}

#unblockvoid

Unblocks all #pull operations for the array.

Examples:

Pull, unblock and signal

# pull.rb
queue = Groonga::Array.open(:name => "CrawlURLQueue")
trap(:INT) do
  p :called!
end
queue.pull do |record|
  # 1. Send SIGINT while blocking the pull operation.
  #    The signal handler isn't called.
  # 2. Run unblock.rb.
  #    The signal handler is called!
end

# unblock.rb
queue = Groonga::Array.open(:name => "CrawlURLQueue")
queue.unblock

This method returns an undefined value.

See Also:



450
451
452
453
454
455
456
457
458
459
460
461
# File 'ext/groonga/rb-grn-array.c', line 450

static VALUE
rb_grn_array_unblock (VALUE self)
{
    grn_ctx *context = NULL;
    grn_obj *table;

    table = SELF(self, &context);

    grn_array_unblock(context, (grn_array *)table);

    return Qnil;
}