Class: Groonga::Context

Inherits:
Object
  • Object
show all
Defined in:
ext/groonga/rb-grn-context.c,
lib/groonga/context.rb,
lib/groonga/context/command-executor.rb

Overview

groonga全体に渡る情報を管理するオブジェクト。通常のアプリ ケーションでは1つのコンテキストを作成し、それを利用する。 複数のコンテキストを利用する必要はない。

デフォルトで使用されるコンテキストは default でアクセスできる。コンテキ ストを指定できる箇所でコンテキストの指定を省略したり +nil+ を指定した場合は default が利用さ れる。

また、デフォルトのコンテキストは必要になると暗黙のうちに 作成される。そのため、コンテキストを意識することは少ない。

暗黙のうちに作成されるコンテキストにオプションを指定する 場合は default_options= を使用 する。

Defined Under Namespace

Classes: CommandExecutor

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.open(*args) {|context| ... } ⇒ Object .open(*args) {|context| ... } ⇒ Groonga::Context

Opens a new context. If block is given, the opened context is closed automatically after the given block is evaluated.

Overloads:

  • .open(*args) {|context| ... } ⇒ Object

    The return value of the given block is the return value of the call.

    Parameters:

    • args (::Array<Object>)

      Passed through to #initialize.

    Yield Parameters:

    Returns:

    • (Object)

      The return value of the given block is the return value of the call.

  • .open(*args) {|context| ... } ⇒ Groonga::Context

    Returns The newly created context.

    Parameters:

    • args (::Array<Object>)

      Passed through to #initialize.

    Yield Parameters:

    Returns:

See Also:

  • #initialize


41
42
43
44
45
46
47
48
49
50
51
52
# File 'lib/groonga/context.rb', line 41

def open(*args, **kwargs)
  context = new(*args, **kwargs)
  if block_given?
    begin
      yield(context)
    ensure
      context.close
    end
  else
    context
  end
end

Instance Method Details

#confGroonga::Config

Deprecated.

since 5.1.1. Use #config instead.

Returns The database level configuration sets of this context.

Returns:

  • (Groonga::Config)

    The database level configuration sets of this context.

Since:

  • 5.0.9



387
388
389
# File 'lib/groonga/context.rb', line 387

def conf
  config
end

#configGroonga::Config

Returns The database level configuration sets of this context.

Returns:

  • (Groonga::Config)

    The database level configuration sets of this context.

Since:

  • 5.1.1



395
396
397
# File 'lib/groonga/context.rb', line 395

def config
  @config ||= Config.new(self)
end

#create_databaseGroonga::Database #create_database {|database| ... } ⇒ Object #create_database(path) ⇒ Groonga::Database #create_database(path) {|database| ... } ⇒ Object

This is convenience method. It wraps Database.create for the context.

Overloads:

  • #create_databaseGroonga::Database

    Creates a new temproary database for the context.

    Examples:

    Creating a new temporary database

    temporary_database = context.create_database

    Returns:

  • #create_database {|database| ... } ⇒ Object

    Creates a new temproary database for the context. The database is closed after the passed block is finished.

    Examples:

    Creating a new temporary database with block

    context.create_database do |temporary_database|
      # ...
    end

    Yields:

    • (database)

      Yields a newly created temporary database for the context. The database is available only in the block.

    Yield Parameters:

    • database (Groonga::Database)

      A newly created temporary database for the context.

    Yield Returns:

    • (Object)

      The returned value from the block is the returned value from this method.

    Returns:

    • Returned value from the block.

  • #create_database(path) ⇒ Groonga::Database

    Creates a new persistent database for the context to the path.

    Examples:

    Creating a new persistent database to “/tmp/db.groonga”

    database = context.create_database("/tmp/db.groonga")

    Parameters:

    • path (String)

      Database path for a new persistent database.

    Returns:

  • #create_database(path) {|database| ... } ⇒ Object

    Creates a new persistent database for the context to the path. The database is closed after the passed block is finished.

    Examples:

    Creating a new persistent database to “/tmp/db.groonga” database with block

    context.create_database("/tmp/db.groonga") do |persistent_database|
      # ...
    end

    Parameters:

    • path (String)

      Database path for a new persistent database.

    Yields:

    • (database)

      Yields a newly created persistent database for the context. The database is available only in the block.

    Yield Parameters:

    • database (Groonga::Database)

      A newly created persistent database for the context.

    Yield Returns:

    • (Object)

      The returned value from the block is the returned value from this method.

    Returns:

    • Returned value from the block.



132
133
134
135
136
137
138
139
# File 'lib/groonga/context.rb', line 132

def create_database(path=nil, &block)
  options = {:context => self}
  if path
    options[:path] = path
  end

  Database.create(options, &block)
end

#execute_command(name, parameters = {}) ⇒ Object



201
202
203
204
# File 'lib/groonga/context.rb', line 201

def execute_command(name, parameters={})
  executor = CommandExecutor.new(self)
  executor.execute(name, parameters)
end

#object_created(object) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



376
377
378
379
380
# File 'lib/groonga/context.rb', line 376

def object_created(object)
  return if @memory_pools.empty?
  memory_pool = @memory_pools.last
  memory_pool.register(object)
end

#open_database(path, &block) ⇒ Object

path にある既存のデータベースを開く。ブロックを指定した場 合はブロックに開いたデータベースを渡し、ブロックを抜けると きに閉じる。



58
59
60
61
62
# File 'lib/groonga/context.rb', line 58

def open_database(path, &block)
  options = {:context => self}

  Database.open(path, options, &block)
end

#pop_memory_poolvoid

This method returns an undefined value.

Pops the pushed memory pool.

See Also:

Since:

  • 3.0.5



370
371
372
373
# File 'lib/groonga/context.rb', line 370

def pop_memory_pool
  memory_pool = @memory_pools.pop
  memory_pool.close
end

#push_memory_poolvoid #push_memory_pool({}) { ... } ⇒ Object

Pushes a new memory pool to the context. Temporary objects that are created between pushing a new memory pool and popping the new memory pool are closed automatically when popping the new memory pool.

It is useful for request and response style applications. These style applications can close temporary objects between a request and resopnse pair. There are some merits for closing temporary objects explicilty rather than closing implicitly by GC:

  • Less memory consumption
  • Faster

The “less memory consumption” merit is caused by temporary objects are closed each request and response pair. The max memory consumption in these applications is the same as the max memory consumption in a request and response pair. If temporary objects are closed by GC, the max memory consumption in these applications is the same as the max memory consumption between the current GC and the next GC. These applications process many request and response pairs during two GCs.

The “faster” merit is caused by reducing GC. You can reduce GC, your application run faster because GC is a heavy process. You can reduce GC because memory consumption is reduced.

You can nest #push_memory_pool and #pop_memory_pool pair.

Examples:

Pushes a new memory pool with block

adults = nil
context.push_memory_pool do
  users = context["Users"]
  adults = users.select do |user|
    user.age >= 20
  end
  p adults.temporary? # => true
  p adults.closed?    # => false
end
p adults.closed?      # => true

Pushes a new memory pool without block

adults = nil
context.push_memory_pool
users = context["Users"]
adults = users.select do |user|
  user.age >= 20
end
p adults.temporary? # => true
p adults.closed?    # => false
context.pop_memory_pool
p adults.closed?    # => true

Nesting push and pop pair

adults = nil
context.push_memory_pool do
  users = context["Users"]
  adults = users.select do |user|
    user.age >= 20
  end
  grouped_adults = nil
  context.push_memory_pool do
    grouped_adults = adults.group(["hobby"])
    p grouped_adults.temporary? # => true
    p grouped_adults.closed?    # => false
  end
  p grouped_adults.closed?      # => true
  p adults.temporary?           # => true
  p adults.closed?              # => false
end
p adults.closed?                # => true

Overloads:

  • #push_memory_poolvoid

    This method returns an undefined value.

    Pushes a new memory pool to the context. You need to pop the memory pool explicitly by yourself.

  • #push_memory_pool({}) { ... } ⇒ Object

    Closes temporary objects created in the given block automatically.

    Yields:

    • [] Yields the block. Temporary objects created in the block are closed automatically when the block is exited.

    Yield Returns:

    • (Object)

      It is the return value of this method call.

    Returns:

    • (Object)

      The value returned by the block.

Since:

  • 3.0.5



351
352
353
354
355
356
357
358
359
360
361
# File 'lib/groonga/context.rb', line 351

def push_memory_pool
  memory_pool = MemoryPool.new
  @memory_pools.push(memory_pool)
  return unless block_given?

  begin
    yield
  ensure
    pop_memory_pool
  end
end

#register_plugin(name_or_options) ⇒ Object

groongaのプラグインディレクトリにあるプラグイン name を登録する。 path を指定するとプラグインディレクトリ以 外にあるプラグインを登録することができる。



144
145
146
147
148
149
150
151
152
# File 'lib/groonga/context.rb', line 144

def register_plugin(name_or_options)
  options = {:context => self}
  if name_or_options.is_a?(String)
    name = name_or_options
    Plugin.register(name, options)
  else
    Plugin.register(name_or_options.merge(options))
  end
end

#restore(dumped_commands) {|command, response| ... } ⇒ void

This method returns an undefined value.

Restore commands dumped by “grndump” command.

If block is given, a response is yielded.

Examples:

Restore dumped commands as a String object.

dumped_commands = File.read("dump.grn")
context.restore(dumped_commands)

Restore dumped commands from a File object.

File.open("dump.grn") do |file|
  context.restore(file)
end

Restore dumped commands and reports result.

dumped_commands = File.read("dump.grn")
context.restore(dumped_commands) do |command, response|
  puts("#{command} -> #{response}")
end

Parameters:

  • dumped_commands (#each_line)

    commands dumped by grndump. It can be a String object or any objects like an IO object such as a File object. It should have #each_line that iterates a line.

Yields:

  • (command, response)

    Yields a sent command and its response if block is given.

Yield Parameters:

  • command (String)

    A sent command.

  • response (String)

    A response for a command.



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
# File 'lib/groonga/context.rb', line 234

def restore(dumped_commands)
  buffer = ""
  continued = false
  dumped_commands.each_line do |line|
    line = line.chomp
    case line
    when /\\\z/
      continued = true
      buffer << $PREMATCH
    else
      continued = false
      buffer << line
      send(buffer)
      _, response = receive
      if block_given?
        not_shared_command = continued ? buffer.dup : line
        yield(not_shared_command, response)
      end
      buffer.clear
    end
  end
  unless buffer.empty?
    send(buffer)
    _, response = receive
    yield(buffer.dup, response) if block_given?
  end
end

#select(table, options = {}) ⇒ Object

table から指定した条件にマッチするレコードの値を取得 する。 table はテーブル名かテーブルオブジェクトを指定 する。

options に指定できるキーは以下の通り。

Parameters:

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

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

Options Hash (options):

  • output_columns (Array)

    The output_columns

    値を取得するカラムを指定する。

  • XXX (Array)

    TODO TODO



197
198
199
# File 'lib/groonga/context.rb', line 197

def select(table, options={})
  execute_command("select", {:table => table}.merge(options))
end

#unregister_plugin(name) ⇒ Object #unregister_plugin(path) ⇒ Object

Unregister a registered name plugin.

You can unregister name plugin by name if name plugin is installed to plugin directory.

You can also specify the path of name plugin explicitly.

Examples:

Unregister a registerd plugin by name.

context.register_plugin("token_filters/stop_word")
context.unregister_plugin("token_filters/stop_word")

Unregister a registerd plugin by path.

context.register_plugin("token_filters/stop_word")
context.unregister_plugin("/usr/local/lib/groonga/plugins/token_filters/stop_word.so")

Overloads:

  • #unregister_plugin(name) ⇒ Object

    Unregister a registerd plugin by name.

    Parameters:

    • name (String)

      The plugin name.

  • #unregister_plugin(path) ⇒ Object

    Unregister a registerd plugin by path.

    Parameters:

    • path (String)

      The path to plugin.

Since:

  • 5.0.1



180
181
182
183
# File 'lib/groonga/context.rb', line 180

def unregister_plugin(name_or_path)
  options = {:context => self}
  Plugin.unregister(name_or_path, options)
end