groonga 0.0.1 → 0.0.2

data/NEWS.ja.rdoc

@@ -1,5 +1,16 @@
 = お知らせ
 
+== 0.0.2: 2009-06-04
+
+* groonga 0.0.9対応 [mori]
+* 性能向上: キー、値、ドメイン、レンジをキャッシュ
+* API改良
+* ドキュメントの追加
+* Ruby 1.9対応
+* バグ修正:
+** インストール処理の修正 [Tasuku SUENAGA]
+** メモリリーク修正
+
 == 0.0.1: 2009-04-30
 
 * 最初のリリース！

data/NEWS.rdoc

@@ -1,5 +1,16 @@
 = NEWS
 
+== 0.0.2: 2009-06-04
+
+* Supported groonga 0.0.9 [mori]
+* Improved preformance: cache key, value, domain and range
+* Improved API
+* Added documents
+* Supported Ruby 1.9
+* Bug fixes:
+** Fixed install process [Tasuku SUENAGA]
+** Fixed memory leaks
+
 == 0.0.1: 2009-04-30
 
 * Initial release!

data/README.ja.rdoc

@@ -20,7 +20,7 @@ groongaに関する情報は以下を参照して下さい。
 
 == 作者
 
-Kouhei Sutou <kou@clear-code.com>
+Kouhei Sutou: <tt><kou@clear-code.com></tt>
 
 == ライセンス
 
@@ -32,7 +32,7 @@ pkg-config.rbはrcairoに付属しているもので、これはRubyライセ
 == 依存ソフトウェア
 
 * Ruby >= 1.8 （1.9.1対応）
-* groonga >= 0.0.4
+* groonga >= 0.0.8
 
 == インストール
 
@@ -50,4 +50,5 @@ http://lists.sourceforge.jp/mailman/listinfo/groonga-dev
 
 == 感謝
 
-* ...
+* 森さん: 最新groonga対応パッチをくれました。
+* グニャラくん: バグレポートしてくれました。

data/README.rdoc

@@ -20,7 +20,7 @@ See the following URL about groonga.
 
 == Author
 
-Kouhei Sutou <kou@clear-code.com>
+Kouhei Sutou: <tt><kou@clear-code.com></tt>
 
 == License
 
@@ -33,7 +33,7 @@ license/GPL for details.
 == Dependencies
 
 * Ruby >= 1.8 (including 1.9.1)
-* groonga >= 0.0.4
+* groonga >= 0.0.8
 
 == Install
 
@@ -51,4 +51,5 @@ http://rubyforge.org/mailman/listinfo/groonga-users-en
 
 == Thanks
 
-* ...
+* mori: sent patches to support the latest groonga.
+* Tasuku SUENAGA: sent bug reports.

data/Rakefile

@@ -27,7 +27,7 @@ require 'hoe'
 
 ENV["NODOT"] = "yes"
 
-Hoe::SUPPORTED_TEST_FRAMEWORKS[:testunit2] = "test/run-test.rb"
+Hoe::Test::SUPPORTED_TEST_FRAMEWORKS[:testunit2] = "test/run-test.rb"
 
 base_dir = File.join(File.dirname(__FILE__))
 truncate_base_dir = Proc.new do |x|

data/TUTORIAL.ja.rdoc

@@ -1,7 +1,7 @@
 = チュートリアル
 
 このページでは簡単なアプリケーションの作成を通して
-Ruby/groongaの新しいSennaの操作方法を紹介します。
+Ruby/groongaの操作方法を紹介します。
 
 == インストール
 
@@ -50,14 +50,14 @@ groongaには以下の3種類のテーブルがあります。
   配列。主キーの存在しないテーブルです。レコードはIDによって
   識別します。
 
-ここではハッシュテーブルを利用して、+<items>+という名前のテー
+ここではハッシュテーブルを利用して、<tt><items></tt>という名前のテー
 ブルを作成します。
 
   >> items = Groonga::Hash.create(:name => "<items>", :persistent => true)
   => #<Groonga::Hash id: <18>, name: <<items>>, path: </tmp/bookmark.db.0000012>, domain: <nil>, range: <nil>, encoding: <:utf8>, size: <0>>
 
 
-これで+<items>+という名前のテーブルが作成できました。
+これで<tt><items></tt>という名前のテーブルが作成できました。
 
 テーブルはRubyのHashのように扱えます。
 
@@ -72,9 +72,9 @@ groongaには以下の3種類のテーブルがあります。
 items>テーブルにレコードを追加します。
 
   >> items.add("http://ja.wikipedia.org/wiki/Ruby")
-  => #<Groonga::Record:0x7f0ece6aeaf8 @table=#<Groonga::Hash id: <18>, name: <<items>>, path: </tmp/bookmark.db.0000012>, domain: <nil>, range: <nil>, encoding: <:utf8>, size: <1>>, @id=1>
+  => #<Groonga::Record ...>
   >> items.add("http://www.ruby-lang.org/")
-  => #<Groonga::Record:0x7f0ece6a9fa8 @table=#<Groonga::Hash id: <18>, name: <<items>>, path: </tmp/bookmark.db.0000012>, domain: <nil>, range: <nil>, encoding: <:utf8>, size: <2>>, @id=2>
+  => #<Groonga::Record ...>
 
 件数を確認すると確かに2件増えています。
 
@@ -83,21 +83,21 @@ items>テーブルにレコードを追加します。
 
 主キーを指定してレコードを取り出す時には以下のようにします。
 
-  >> items["http://ja.wikipedia.org/wiki/Ruby"]
-  => #<Groonga::Record:0x7f0ece699ab8 @table=#<Groonga::Hash id: <18>, name: <<items>>, path: </tmp/bookmark.db.0000012>, domain: <nil>, range: <nil>, encoding: <:utf8>, size: <2>>, @id=1>
+  >> items.find("http://ja.wikipedia.org/wiki/Ruby")
+  => #<Groonga::Record ...>
 
 == 全文検索を行う
 
 各itemのタイトル文字列を登録して、全文検索できるようにしてみ
 ましょう。
 
-まず+<items>+テーブルに+title+という名前のカラムを追加します。
+まず<tt><items></tt>テーブルに+title+という名前のカラムを追加します。
 
-  >> title_colum = items.define_column("title", "<text>")
-  => #<Groonga::VarSizeColumn id: <19>, name: <<items>.title>, path: (temporary), domain: <#<Groonga::Hash id: <18>, name: <<items>>, path: </tmp/bookmark.db.0000012>, domain: <nil>, range: <nil>, encoding: <:utf8>, size: <2>>>, range: <#<Groonga::Type id: <7>, name: <<text>>, path: (temporary), domain: <nil>, range: <65536>>>>
+  >> title_colum = items.define_column("title", "<text>", :persistent => true)
+  => #<Groonga::VarSizeColumn ...>
 
 2番目の引数は、追加するカラムのデータ型を示しています。
-+<int>+、+<text>+、+<longtext>+等の型が基本型として用意されて
+<tt><int></tt>、<tt><text></tt>、<tt><longtext></tt>等の型が基本型として用意されて
 います。
 
 全文検索するためには、文字列を分解して得られる各単語を格納す
@@ -106,42 +106,51 @@ items>テーブルにレコードを追加します。
 
   >> terms = Groonga::Hash.create(:name => "<terms>",
                                   :key_type => "<shorttext>",
-                                  :persistent => true)
-  => #<Groonga::Hash id: <21>, name: <<terms>>, path: </tmp/bookmark.db.0000015>, domain: <#<Groonga::Type id: <6>, name: <<shorttext>>, path: (temporary), domain: <nil>, range: <4096>>>, range: <nil>, encoding: <:utf8>, size: <0>>
-
-+<items>+テーブルの+title+カラムに対するインデックスを定義し
-ます。
-
-  >> title_index_column = terms.define_column("item_title", items,
-                                              :type => "index",
-                                              :with_position => true)
-  => #<Groonga::IndexColumn id: <22>, name: <<terms>.item_title>, path: (temporary), domain: <#<Groonga::Hash id: <21>, name: <<terms>>, path: </tmp/bookmark.db.0000015>, domain: <#<Groonga::Type id: <6>, name: <<shorttext>>, path: (temporary), domain: <nil>, range: <4096>>>, range: <nil>, encoding: <:utf8>, size: <0>>>, range: <#<Groonga::Hash id: <18>, name: <<items>>, path: </tmp/bookmark.db.0000012>, domain: <nil>, range: <nil>, encoding: <:utf8>, size: <2>>>>
-
-インデックス用カラムに、検索対象の+<items>+テーブルの+title+
-カラムを設定します。
-
-  >> title_index_column.source = title_column
-  => #<Groonga::VarSizeColumn id: <19>, name: <<items>.title>, path: (temporary), domain: <#<Groonga::Hash id: <18>, name: <<items>>, path: </tmp/bookmark.db.0000012>, domain: <nil>, range: <nil>, encoding: <:utf8>, size: <2>>>, range: <#<Groonga::Type id: <7>, name: <<text>>, path: (temporary), domain: <nil>, range: <65536>>>>
-
-少し違和感を感じるかも知れませんが、+<items>+テーブルのカラムに
-対するインデックスは、 +<terms>+テーブルのカラムとして定義しま
-す。
-
-+<items>+にレコードが登録されると、その中に含まれる単語に該当
-するレコードが+<terms>+に自動的に追加されるようになります。
-
-+<terms>+は、文書に含まれる語彙に相当する、やや特殊なテーブル
-だと言えます。しかし、他のテーブルと同様に語彙テーブルには自
-由にカラムを追加し、単語毎の様々な属性を管理することができま
-す。これはある種の検索処理を行う際には非常に便利に機能します。
+                                  :persistent => true,
+                                  :default_tokenizer => "<token:bigram>")
+  => #<Groonga::Hash ...>
+
+ここでは、トークナイザとして<tt>:default_tokenzier =>
+"<token:bigram>"</tt> を指定しています。トークナイザとは文字
+列を単語に分解するオブジェクトのことです。デフォルトではトー
+クナイザは指定されていません。全文検索を利用するためにはトー
+クナイザを指定する必要があるので、ここではN-gramの一種である
+バイグラムを指定しています。
+
+N-gramを利用した全文検索では、分解したN文字とその出現位置を利
+用して全文検索を行います。N-gramのNは文字列を何文字毎に分解す
+るかの文字数になります。groongaは1文字で分解するユニグラム、
+2文字のバイグラム、3文字のトリグラムをサポートしています。
+
+単語格納用テーブルの準備ができたので、<tt><items></tt>テーブ
+ルの+title+カラムに対するインデックスを定義します。
+
+  >> terms.define_index_column("item_title", items,
+                               :persistent => true,
+                               :source => "<items>.title")
+  => #<Groonga::IndexColumn ...>
+
+少し違和感を感じるかも知れませんが、<tt><items></tt>テーブル
+のカラムに対するインデックスは、<tt><terms></tt>テーブルのカ
+ラムとして定義します。
+
+<tt><items></tt>にレコードが登録されると、その中に含まれる単
+語に該当するレコードが<tt><terms></tt>に自動的に追加されるよ
+うになります。
+
+<tt><terms></tt>は、文書に含まれる語彙に相当する、やや特殊な
+テーブルだと言えます。しかし、他のテーブルと同様に語彙テーブ
+ルには自由にカラムを追加し、単語毎の様々な属性を管理すること
+ができます。これはある種の検索処理を行う際には非常に便利に機
+能します。
 
 これでテーブルの定義は完了です。
 
 先ほど登録した各レコードの+title+カラムに値をセットします。
 
-  >> items["http://ja.wikipedia.org/wiki/Ruby"]["title"] = "Ruby"
+  >> items.find("http://ja.wikipedia.org/wiki/Ruby")["title"] = "Ruby"
   => "Ruby"
-  >> items["http://www.ruby-lang.org/"]["title"] = "オブジェクトスクリプト言語Ruby"
+  >> items.find("http://www.ruby-lang.org/")["title"] = "オブジェクトスクリプト言語Ruby"
   "オブジェクトスクリプト言語Ruby"
 
 以下のようにして検索することができます。
@@ -150,11 +159,126 @@ items>テーブルにレコードを追加します。
   ["http://ja.wikipedia.org/wiki/Ruby", "http://www.ruby-lang.org/"]
 
 検索結果はGroonga::Hashで返されます。ハッシュのキーに見つかっ
-た+<items>+のレコードが入っています。上の例ではrecord.keyで
-+<items>+のレコードを取得して、さらにそのキーを指定して
-（record.key.key）で+<items>+のキーを返しています。
+た<tt><items></tt>のレコードが入っています。上の例では
++record.key+で<tt><items></tt>のレコードを取得して、さらにそ
+のキーを指定して（+record.key.key+）で<tt><items></tt>のキー
+を返しています。
 
 
 == マルチユーザ向けのブックマークアプリケーション
 
+ここまでで作った単機能のアプリケーションをもう少し拡張して、
+複数のユーザが、それぞれにコメントを記入できるブックマークア
+プリケーションにしてみましょう。
+
+まず、ユーザ情報とコメント情報を格納するテーブルを追加して、
+下図のようなテーブル構成にします。
+
+http://qwik.jp/senna/senna2.files/rect4605.png
+
+まず、<tt><users></tt>テーブルを追加します。
+
+  >> users = Groonga::Hash.create(:name => "<users>",
+                                  :key_type => "<shorttext>")
+  => #<Groonga::Hash ...>
+  >> users.define_column("name", "<text>")
+  => #<Groonga::VarSizeColumn ...>
+
+
+次に、<tt><comments></tt>テーブルを追加します。
+
+  >> comments = Groonga::Hash.create(:name => "<comments>",
+                                     :key_type => "<shorttext>")
+  => #<Groonga::Hash ...>
+  >> comments.define_column("item", items)
+  => #<Groonga::FixSizeColumn ..>
+  >> comments.define_column("author", users)
+  => #<Groonga::FixSizeColumn ..>
+  >> comments.define_column("content", "<text>")
+  => #<Groonga::VarSizeColumn ..>
+  >> comments.define_column("issued", "<time>")
+  => #<Groonga::FixSizeColumn ..>
+
+<tt><comments></tt>テーブルの+content+カラムを全文検索できる
+ようにインデックスを定義します。
+
+  >> terms.define_index_column("comment_content", comments,
+                               :source => "<comments>.content")
+  => #<Groonga::IndexColumn ...>
+
+これでテーブルが定義できました。
+
+続いてユーザを何人か追加します。
+
+  >> users.add("moritan", :name => "モリタン")
+  => #<Groonga::Record ...>
+  >> users.add("taporobo", :name => "タポロボ")
+  => #<Groonga::Record ...>
+
+次に、実際にユーザがブックマークを貼る時の処理を実行してみま
+しょう。
+
+ユーザ+moritan+が、はてなダイアリーのとあるページをブックマーク
+したと想定します。
+
+まず対象のページが<tt><items></tt>テーブルに登録済かどうか調
+べます。
+
+  >> items.find("http://d.hatena.ne.jp/brazil/20050829/1125321936")
+  => nil
+
+未登録なのでまず当該ページを<tt><items></tt>に登録します。
+
+  >> items.add("http://d.hatena.ne.jp/brazil/20050829/1125321936",
+               :title => "[翻訳]JavaScript: 世界で最も誤解されたプログラミング言語")
+  => #<Groonga::Record ...>
+
+次に、登録したitemを+item+カラムの値に指定して
+<tt><comments></tt>にレコードを登録します。
+
+  >> comments.add(:item => "http://d.hatena.ne.jp/brazil/20050829/1125321936",
+                  :author => "moritan",
+                  :content => "JavaScript LISP",
+                  :issued => 1187430026)
+  => #<Groonga::Record ...>
+
+== メソッド化
+
+上記の一連の手続きをメソッドにまとめてみます。
+
+  >> @items = items
+  >> @comments = comments
+  >> def add_bookmark(url, title, author, content, issued)
+  >>  item = @items.find(url) || @items.add(url, :title => title)
+  >>  @comments.add(:item => item,
+  >>                :author => author,
+  >>                :content => content,
+  >>                :issued => issued)
+  >> end
+
++itmes+と+comments+をインスタンス変数に代入しているのはメソッ
+ド内からでも見えるようにするためです。
+
++add_bookmark+は以下のような手順を実行しています。
+
+  * <tt><items></tt>テーブルに該当ページのレコードがあるかどうか調べる。
+  * レコードがなければ追加する。
+  * <tt><comments></tt>テーブルにレコードを登録する。
+
+作成したメソッドを呼び出していくつかブックマークを登録してみ
+ましょう。
+
+  >> add_bookmark("http://practical-scheme.net/docs/cont-j.html",
+                  "なんでも継続", "moritan", "継続 LISP Scheme", 1187568692)
+  => #<Groonga::Record ...>
+  >> add_bookmark("http://d.hatena.ne.jp/higepon/20070815/1187192864",
+                  "末尾再帰", "taporobo", "末尾再帰 Scheme LISP", 1187568793)
+  => #<Groonga::Record ...>
+  >> add_bookmark("http://practical-scheme.net/docs/cont-j.html",
+                  "なんでも継続", "taporobo", "トランポリン LISP continuation",
+                  1187568692)
+  => #<Groonga::Record ...>
+
+== 全文検索その2
+
 つづく。。。

data/benchmark/common.rb

@@ -0,0 +1,49 @@
+require 'benchmark'
+require 'tempfile'
+
+def memory_usage()
+  status = `cat /proc/#{$$}/status`
+  lines = status.split("\n")
+  lines.each do |line|
+    if line =~ /^VmRSS:/
+      line.gsub!(/.*:\s*(\d+).*/, '\1')
+      return line.to_i / 1024.0
+    end
+  end
+  return -1;
+end
+
+@items = []
+
+def item(label, &block)
+  @items << [label, block]
+end
+
+def report(index=0)
+  width = @items.collect do |label, _|
+    label.length
+  end.max
+
+  label, block = @items[index]
+  if label.nil?
+    puts "unavailable report ID: #{index}"
+    puts "available IDs:"
+    @items.each_with_index do |(label, block), i|
+      puts "#{i}: #{label}"
+    end
+    exit 1
+  end
+
+  if index.zero?
+    puts(" " * (width - 1) + Benchmark::Tms::CAPTION.rstrip + "memory".rjust(14))
+  end
+  # GC.disable
+  before = memory_usage
+  result = Benchmark.measure(&block)
+  # GC.enable
+  GC.start
+  size = memory_usage - before
+
+  formatted_size = "%10.3f" % size
+  puts "#{label.ljust(width)} #{result.to_s.strip} #{formatted_size}MB"
+end

data/benchmark/read-write-small-many-items.rb

@@ -0,0 +1,156 @@
+#!/usr/bin/ruby
+
+# This benchmark is based on Tokyo Cabinet's benchmark at
+# http://alpha.mixi.co.jp/blog/?p=791
+#
+# On my environment at 2009/05/16:
+# % for x in {0..9}; do ruby benchmark/read-write-small-many-items.rb $x; done
+#                           user     system      total        real        memory
+# Hash                  1.440000   0.120000   1.560000 (  2.018838)     47.230MB
+# groonga: Hash: memory 1.780000   0.170000   1.950000 (  2.331934)     30.582MB
+# groonga: Trie: memory 2.220000   0.150000   2.370000 (  2.788049)     22.594MB
+# groonga: Hash: file   1.810000   0.170000   1.980000 (  2.389940)     30.590MB
+# groonga: Trie: file   2.170000   0.150000   2.320000 (  2.862775)     22.594MB
+# Localmemcache: file   1.710000   0.240000   1.950000 (  2.311414)     46.410MB
+# TC: Hash: memory      1.540000   0.180000   1.720000 (  2.048307)     49.180MB
+# TC: Tree: memory      1.410000   0.160000   1.570000 (  1.891273)     37.691MB
+# TC: Hash: file        2.420000   2.950000   5.370000 (  7.122531)      9.258MB
+# TC: Tree: file        2.080000   0.220000   2.300000 (  2.876335)     13.234MB
+#
+# Ruby: Debian GNU/Linux sid at 2009/05/16:
+#       ruby 1.8.7 (2008-08-11 patchlevel 72) [x86_64-linux]
+# groonga: HEAD at 2009/05/16: ed49074fbc217b97c0b0b8d675f2417f9490c87e
+# Ruby/Groonga: trunk at 2009/05/16: r321
+# Localmemcache: HEAD at 2009/05/16: 6f8cfbd3a103c2be8d54834a65deb096d7cda34f
+# Tokyo Cabinet: 1.4.20
+# Tokyo Cabinet Ruby: 1.23
+#
+# NOTE: All C source codes are built with "-g -O0"
+# option. They will be more faster with "-O2" option.
+
+require File.join(File.dirname(__FILE__), "common.rb")
+
+n = 500000
+
+values = []
+n.times do |i|
+  values << "%08d" % i
+end
+
+item("Hash") do
+  @hash = {}
+  values.each do |value|
+    @hash[value] = value
+    @hash[value]
+  end
+end
+
+begin
+  base_dir = File.expand_path(File.join(File.dirname(__FILE__), ".."))
+  $LOAD_PATH.unshift(File.join(base_dir, "ext"))
+  $LOAD_PATH.unshift(File.join(base_dir, "lib"))
+
+  require 'groonga'
+  @database = Groonga::Database.create
+
+  item("groonga: Hash: memory") do
+    @hash = Groonga::Hash.create(:key_type => "<shorttext>",
+                                 :value_size => 8)
+    values.each do |value|
+      @hash[value] = value
+      @hash[value]
+    end
+  end
+
+  item("groonga: Trie: memory") do
+    @hash = Groonga::PatriciaTrie.create(:key_type => "<shorttext>",
+                                         :value_size => 8)
+    values.each do |value|
+      @hash[value] = value
+      @hash[value]
+    end
+  end
+
+  @hash_file = Tempfile.new("groonga-hash")
+  item("groonga: Hash: file") do
+    @hash = Groonga::Hash.create(:key_type => "<shorttext>",
+                                 :value_size => 8,
+                                 :path => @hash_file.path)
+    values.each do |value|
+      @hash[value] = value
+      @hash[value]
+    end
+  end
+
+  trie_file = Tempfile.new("groonga-trie")
+  item("groonga: Trie: file") do
+    @hash = Groonga::PatriciaTrie.create(:key_type => "<shorttext>",
+                                         :value_size => 8,
+                                         :path => trie_file.path)
+    values.each do |value|
+      @hash[value] = value
+      @hash[value]
+    end
+  end
+rescue LoadError
+end
+
+begin
+  require 'localmemcache'
+
+  item("Localmemcache: file") do
+    LocalMemCache.drop(:namespace => "read-write-small-many-items",
+                       :force => true)
+    @db = LocalMemCache.new(:namespace => "read-write-small-many-items")
+    values.each do |value|
+      @db[value] = value
+      @db[value]
+    end
+  end
+rescue LoadError
+end
+
+begin
+  require 'tokyocabinet'
+
+  item("TC: Hash: memory") do
+    @db = TokyoCabinet::ADB::new
+    @db.open("*#bnum=#{n}#mode=wct#xmsiz=0")
+    values.each do |value|
+      @db.put(value, value)
+      @db.get(value)
+    end
+  end
+
+  item("TC: Tree: memory") do
+    @db = TokyoCabinet::ADB::new
+    @db.open("+#bnum=#{n}#mode=wct#xmsiz=0")
+    values.each do |value|
+      @db.put(value, value)
+      @db.get(value)
+    end
+  end
+
+  hash_file = Tempfile.new(["tc-hash", ".tch"])
+  item("TC: Hash: file") do
+    @db = TokyoCabinet::ADB::new
+    @db.open("#{hash_file.path}#bnum=#{n}#mode=wct#xmsiz=0")
+    values.each do |value|
+      @db.put(value, value)
+      @db.get(value)
+    end
+  end
+
+  tree_file = Tempfile.new(["tc-tree", ".tcb"])
+  item("TC: Tree: file") do
+    @db = TokyoCabinet::ADB::new
+    @db.open("#{tree_file.path}#bnum=#{n}#mode=wct#xmsiz=0")
+    values.each do |value|
+      @db.put(value, value)
+      @db.get(value)
+    end
+  end
+rescue LoadError
+end
+
+report(Integer(ARGV[0] || 0))