Class: Groonga::Context

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

Overview

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

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

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

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

Instance Method Summary collapse

Instance Method Details

#create_database ⇒ Groonga::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_database ⇒ Groonga::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.



101
102
103
104
105
106
107
108
 
# File 'lib/groonga/context.rb', line 101

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

  Database.create(options, &block)
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. 



310
311
312
313
314
 
# File 'lib/groonga/context.rb', line 310

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 にある既存のデータベースを開く。ブロックを指定した場合はブロックに開いたデータベースを渡し、ブロックを抜けるときに閉じる。



27
28
29
30
31
 
# File 'lib/groonga/context.rb', line 27

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

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

#pop_memory_pool ⇒ void

This method returns an undefined value.

Pops the pushed memory pool.

See Also:

Since:

  • 3.0.5



304
305
306
307
 
# File 'lib/groonga/context.rb', line 304

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

#push_memory_pool ⇒ void #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_pool ⇒ void

    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



285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/groonga/context.rb', line 285

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 を指定するとプラグインディレクトリ以外にあるプラグインを登録することができる。



113
114
115
116
117
118
119
120
121
 
# File 'lib/groonga/context.rb', line 113

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.



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/groonga/context.rb', line 168

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



135
136
137
138
 
# File 'lib/groonga/context.rb', line 135

def select(table, options={})
  select = Command::Select.new(self, table, options)
  select.exec
end