cycr 0.1.0 → 0.2.0

data/.gitignore

@@ -2,3 +2,4 @@
 .*.sw?
 work
 doc
+.yardoc

data/README.rdoc

@@ -1,35 +1,52 @@
 = cycr
 
-* http://github.com/apohllo/cycr
+* http://github.com/apohllo/cycr - code
+* http://rubydoc.info/gems/cycr/frames - documentation
 
-= DESCRIPTION
+== DESCRIPTION
 
-'cycr' is a Ruby client for the (Open)Cyc server http://www.opencyc.org.
+*cycr* is a Ruby client for the (Open)Cyc server http://www.opencyc.org.
 
-= FEATURES/PROBLEMS
+== FEATURES
 
 * The text protocol is used to talk with Cyc
-* Ruby symbols are converted to Cyc symbols
+* Ruby symbols are converted to Cyc terms
 * Ruby arrays are converted to SubL arrays
 * Ruby calls on the client are transparently translated to SubL
-* Support for subcalls (like 'with-any-mt')
-* Support for NARTs might not be fully functional (but works somehow)
+* Support for subcalls (like +with-any-mt+)
+* connection drivers: regular socket and synchrony based communication
+* auto reconnecting the client after server downtime
+* thread safe client as an option
+
+== PROBLEMS
+
+* Support for NARTs might not be fully functional (works only with ResearchCyc)
 * Support for CycL queries not implemented yet!
 
-= SYNOPSIS
+== SYNOPSIS
 
-'cycr' is a Ruby client for the (Open)Cyc server. It is designed as a
+*cycr* is a Ruby client for the (Open)Cyc server. It is designed as a
 substitution for the original Java client. It allows for conversation
 with the ontology with regular Ruby objects (like symbols, arrays) 
-and also exposes the raw text protocol.
+and also exposes a raw text protocol.
+
+If you use this library you might be intereste in:
+
+* https://github.com/apohllo/cyc-console - replacement for Cyc console
+* https://github.com/apohllo/navicyc - Rails and ExtJS replacement for Cyc browser
+
 
-= REQUIREMENTS
+== REQUIREMENTS
 
 (Open)Cyc server with TCP communication enabled.
 
-= INSTALL
+== INSTALL
+
+The gem is available at rubygems.org, so you can install it with:
+
+  $ sudo gem install cycr
 
-You need RubyGems v.1.3.5 at least:
+In case of problems just make sure that you have RubyGems v.1.3.5 at least:
 
   $ gem -v
   1.2.0 # => not OK
@@ -38,61 +55,65 @@ You need RubyGems v.1.3.5 at least:
   $ gem -v 
   1.3.7 # => OK
 
-The gem is available at rubygems.org, so you can install it with:
-
-  $ sudo gem install cycr
 
 == BASIC USAGE
 
 Prerequisites:
 
-* Cyc server is running 
-** you can download it from http://www.opencyc.org
-* Telnet connection is on
-** type (enable-tcp-server :cyc-api 3601) in the cyc console or Cyc Browser
-   -> Tools -> Interactor
+* running Cyc server - you can download it from http://www.opencyc.org
+* Telnet connection is turned on.
+  Type +(enable-tcp-server :cyc-api 3601)+ in the cyc console 
+  or Cyc Browser -> Tools -> Interactor
+
+Then you can start +irb+ session to see it in action.
 
-The you can start 'irb' to see it in action:
+Include the cycr gem first
 
-  $ irb
-  # include the cycr gem
   require 'cycr'
 
-  # create the cyc client object, default host: localhost, port: 3601
+Create a cyc client object, default host: localhost, port: 3601
+
   cyc = Cyc::Client.new
 
-  # check if Dog generalizes to Animal
+Check if Dog generalizes to Animal
+
   cyc.genls? :Dog, :Animal # => true
 
-  # check if Animal generalizes to Dog
+Check if Animal generalizes to Dog
+
   cyc.genls? :Animal, :Dog # => nil
 
-  # check the minimal generalizations of Animal
+Check the minimal generalizations of Animal
+
   genls = cyc.min_genls :Animal
   # => [:"Organism-Whole", :"PerceptualAgent-Embodied",
-    :"Agent-NonArtifactual", :SolidTangibleThing, [:CollectionUnionFn,
-    [:TheSet, :Animal, [:GroupFn, :Animal]]],...
+  #  :"Agent-NonArtifactual", :SolidTangibleThing, [:CollectionUnionFn,
+  #  [:TheSet, :Animal, [:GroupFn, :Animal]]],...
+
+Check the maximal specializations of the first of the above results
 
-  # check the maximal specializations of the first of the above results
   cyc.max_specs genls.first
   # => [:Microorganism, :EukaryoticOrganism, :"Unvaccinated-Generic",
-    :"Vaccinated-Generic", :MulticellularOrganism, :Heterotroph, :Autotroph,
-    :Lichen, :TerrestrialOrganism, :Animal, :AquaticOrganism, :Mutant,
-    :Carnivore, :Extraterrestrial, :"Exotic-Foreign",...
+  #  :"Vaccinated-Generic", :MulticellularOrganism, :Heterotroph, :Autotroph,
+  #  :Lichen, :TerrestrialOrganism, :Animal, :AquaticOrganism, :Mutant,
+  #  :Carnivore, :Extraterrestrial, :"Exotic-Foreign",...
+
+It works with NARTs (but I didn't tested this functionality extensively,
+so this might cause some problems - beware):
 
-  # It works with NARTs (but I didn't tested this functionality extensively,
-  # so this might cause some problems - beware):
   genls[4]
   # => [:CollectionUnionFn, [:TheSet, :Animal, [:GroupFn, :Animal]]]
 
   cyc.max_specs genls[4]
   # => [:Animal, [:GroupFn, :Animal]]
 
-  # What is more, you might even build complex subcalls, such as:
+What is more, you might even build complex subcalls, such as:
+
   cyc.genls? :Person, :HomoSapiens # => nil
   cyc.with_any_mt{|cyc| cyc.genls? :Person, :HomoSapiens} # => true
 
-  # The assertions are parsed, as well as Cyc symbols and variables
+The assertions are parsed, as well as Cyc symbols and variables
+
   keys = cyc.key_predicate_rule_index :isa
   # => [:POS, :NEG]
   keys[0].class
@@ -106,8 +127,8 @@ The you can start 'irb' to see it in action:
   # => [:BACKWARD]
   rules = cyc.gather_predicate_rule_index :isa, keys[0], keys1[2], keys2[0]
   # => [[:implies, [:and, [:objectOfPossessionTransfer, :TheBuying, ?OBJ], 
-        [:activityObjectType, :TheSelectingAProduct, ?PREFERED]], 
-        [:isa, ?OBJ, ?PREFERED]] : BuyingMt]
+  #     [:activityObjectType, :TheSelectingAProduct, ?PREFERED]], 
+  #     [:isa, ?OBJ, ?PREFERED]] : BuyingMt]
   cyc.assertion_p rules[0]
   # => true
 
@@ -115,28 +136,62 @@ The you can start 'irb' to see it in action:
   # => ?OBJ
   rules[0].formula[1][1][2].class
   # => Cyc::Variable
-  # the variable cannot be checked for type, since it won't be bound
+
+The variable cannot be checked for type, since it won't be bound.
 
 
-  # If you want to see the query which is send to Cyc, just turn on
-  # debugging:
+If you want to see the query which is send to Cyc, just turn on
+debugging:
+
   cyc.debug = true
-  cyc.genls? :Dog, :Anial
+  cyc.genls? :Dog, :Animal
   # Send: (genls? #$Dog #$Animal)
   # Recv: 200 T
   # => true 
 
-  # The same way, you can turn it off:
+The same way, you can turn it off:
+
   cyc.debug = false
 
-  # Remember to close the client on exit
+Remember to close the client on exit
+
   cyc.close
 
+By default a Cyc client uses regular TCP socket communication and is not 
+thread safe. To turn-on thread-safety pass a +thread_safe+ option to the 
+constructor:
+ 
+  cyc = Cyc::Client.new(:thread_safe => true)
+
+Alternatively you can use a client with fibers and Event Machine synchrony 
+To set-up event machine driver before requiring +cycr+:
+
+  require 'cyc/connection/synchrony'
+  require 'cycr'
+
+Make sure that you have 'em-synchrony' gem installed. A sample code looks as
+follows:
+
+  EM.synchrony do
+    cyc = EM::Synchrony::ConnectionPool.new(size => 5) do
+      Cyc::Client.new :url => 'cyc://localhost:3601', :debug => true
+    end
+    Fiber.new do
+      puts "Ani", cyc.fi_complete("Ani").inspect
+    end.resume
+    puts "Mi", cyc.talk('(fi-complete "Mi")').inspect
+    EM.stop
+  end
+
+`Mi` will arrive before `Ani`
+
+Warning: always use +EM::Synchrony::ConnectionPool+ to handle Fiber concurrency race conditions.
+
 == LICENSE:
  
 (The MIT/X11 License)
 
-Copyright (c) 2008-2012 Aleksander Pohl
+Copyright (c) 2008-2012 Aleksander Pohl, Rafal Michalski
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/Rakefile

@@ -1,3 +1,6 @@
+$:.unshift "lib"
+require 'cyc/version'
+
 task :default => [:test]
 
 $gem_name = "cycr"
@@ -29,3 +32,8 @@ desc "Clean"
 task :clean do
   sh "rm #$gem_name*.gem" 
 end
+
+desc "Show changelog from the last release"
+task :changelog do
+  sh "git log v#{Cyc::VERSION}.. --pretty=%s | tee"
+end

data/changelog.txt

@@ -1,3 +1,18 @@
+0.2.0
+- Rake task for changelog
+- Support for Ruby 1.8 dropped
+- Remove support for Client.new(host,port) syntax (use options instead)
+- Documentation updates.
+- Fix README formatting
+- :host & :port options added to client constructor
+- Fixed multiprocess tests
+- Removal of unused code
+- Early detect broken connection to allow conn.write again; connected? return value
+- Client reuses driver connection while reconnecting
+- Client#check_parenthesis much faster
+- Parser: include NIL in results - missing NILs may brake partial results
+- Thread safety support
+- Cyc::Client rework to allow multiple connection drivers
 0.1.0
 - Add license info to some files
 - Add tests to Rakefile

data/cycr.gemspec

@@ -1,18 +1,22 @@
+$:.unshift "lib"
+require 'cyc/version'
+
 Gem::Specification.new do |s|
   s.name = "cycr"
-  s.version = "0.1.0"
+  s.version = Cyc::VERSION.to_s
+  s.required_ruby_version = '>= 1.9.2'
   s.date = "#{Time.now.strftime("%Y-%m-%d")}"
   s.summary = "Ruby client for the (Open)Cyc server"
   s.email = "apohllo@o2.pl"
   s.homepage = "http://github.com/apohllo/cycr"
   s.require_path = "lib"
   s.description = "Ruby wrapper for (Open)Cyc server and ontology"
-  s.has_rdoc = false
-  s.authors = ['Aleksander Pohl']
+  s.authors = ['Aleksander Pohl', 'Rafal Michalski']
   s.files = `git ls-files`.split("\n")
   s.test_files = Dir.glob("spec/**/*") + Dir.glob("integration/**/*")
   s.rdoc_options = ["--main", "README.rdoc"]
   s.has_rdoc = true
   s.extra_rdoc_files = ["README.rdoc"]
-  s.add_development_dependency("rspec", [">= 1.2.9"])
+  s.add_development_dependency("rspec", ["~> 2.8.0"])
+  s.add_development_dependency("em-synchrony", ["~> 1.0.0"])
 end

data/integration/client.rb

@@ -1,16 +1,8 @@
 $:.unshift "lib"
 require 'cycr'
+require 'cyc/connection/synchrony' if defined? Fiber
 
-describe Cyc::Client do
-  before(:each) do
-    @client = Cyc::Client.new()
-#    @client.debug = true
-  end
-
-  after(:each) do
-    @client.close
-  end
-
+shared_examples Cyc::Client do
   it "should allow to talk to the server" do
     @client.talk("(constant-count)").should_not == nil
   end
@@ -53,15 +45,141 @@ describe Cyc::Client do
     @client.talk('(gather-predicate-extent-index #$minimizeExtent)').size.should > 100
   end
 
-  it "should allow multiple processes to use the client" do
-    parent_pid = Process.pid
-    if fork
-      @client.find_constant("Cat")
-    else
-      @client.find_constant("Dog")
+end
+
+describe Cyc::Client do
+  include_examples Cyc::Client
+
+  it "should have socket driver" do
+    @client.driver.type.should == :socket
+  end
+
+  before(:all) do
+    Cyc::Connection.driver = Cyc::Connection::SocketDriver
+    @client = Cyc::Client.new()
+#    @client.debug = true
+  end
+
+  after(:each) do
+    @client.close
+  end
+
+end
+
+if defined? Cyc::Connection::SynchronyDriver
+  describe Cyc::Connection::SynchronyDriver do
+    include_examples Cyc::Client
+
+    it "should have synchrony driver" do
+      @client.driver.type.should == :synchrony
+    end
+
+    around(:each) do |test_case|
+      EM.synchrony do
+        @client = Cyc::Client.new(:driver => Cyc::Connection::SynchronyDriver)
+  #    @client.debug = true
+        test_case.call
+        @client.close
+        EM.stop
+      end
+    end
+
+  end
+
+  describe "synchrony fiber concurrency" do
+    around(:each) do |test_case|
+      EM.synchrony do
+        @client = EM::Synchrony::ConnectionPool.new(size: 1) do
+          Cyc::Client.new(:driver => Cyc::Connection::SynchronyDriver, :debug => false)
+        end
+        test_case.call
+        @client.close
+        EM.stop
+      end
+    end
+
+    # this is a little bit loooong test
+    # but tests aync nature of Fibers and composite results (subseq x)
+    it "should have consistent results running long query in separate fibers" do
+      @fiber = Fiber.current
+      done = 0
+      size = ('A'..'Z').to_a.each do |char|
+        Fiber.new do
+          result_size = @client.fi_complete(char).each do |value|
+            value.to_s[0].upcase.should == char
+          end.length
+          result_size.should > 0
+          done += 1
+          EM.next_tick { @fiber.resume }
+        end.resume
+      end.size
+      while done < size
+        @fiber = Fiber.current
+        Fiber.yield
+      end
     end
-    if Process.pid == parent_pid
-      Process.waitall
+  end
+end
+
+describe "client thread concurrency" do
+
+  before(:all) do
+    Cyc::Connection.driver = Cyc::Connection::SocketDriver
+    @client = Cyc::Client.new :thread_safe => true
+    # @client.debug = true
+  end
+
+  it "should have socket driver" do
+    @client.driver.type.should == :socket
+  end
+
+  it "should have thread_safe? flag set" do
+    @client.thread_safe?.should == true
+  end
+
+  it "should have consistent results running long query in separate threads" do
+    results = {}
+    mutex = Mutex.new
+    ('A'..'Z').map do |char|
+      Thread.new do
+        Thread.pass
+        result = @client.fi_complete char
+        @client.close
+        mutex.synchronize { results[char] = result }
+      end
+    end.each {|t| t.join }
+    results.each_pair do |char, result|
+      result.should_not == nil
+      size = result.each do |value|
+        value.to_s[0].upcase.should == char
+      end.length
+      size.should > 0
     end
   end
+
+end
+
+describe "client multiple processes" do
+
+  before(:all) do
+    Cyc::Connection.driver = Cyc::Connection::SocketDriver
+    @client = Cyc::Client.new()
+#    @client.debug = true
+  end
+
+  after(:each) do
+    @client.close
+  end
+
+  it "should have socket driver" do
+    @client.driver.type.should == :socket
+  end
+
+  it "should allow multiple processes to use the client" do
+    fork { @client.find_constant("Cat").should == :Cat }
+    fork { @client.find_constant("Dog").should == :Dog }
+    @client.find_constant("Animal").should == :Animal
+    Process.waitall
+  end
+
 end

data/lib/cyc/assertion.rb

@@ -2,7 +2,7 @@ module Cyc
   # Author:: Aleksander Pohl (mailto:apohllo@o2.pl)
   # License:: MIT/X11 License
   #
-  # This class represent the Cyc assertions.
+  # This class represent a Cyc assertion.
   class Assertion
     # The logical formula of the assertion.
     attr_reader :formula

data/lib/cyc/builder.rb

@@ -2,9 +2,9 @@ module Cyc
   # This class is used to capture calls to the Cyc client, to allow
   # nested calls, like
   #
-  # cyc.with_any_mt do |cyc|
-  #   cyc.comment :Collection
-  # end
+  #   cyc.with_any_mt do |cyc|
+  #     cyc.comment :Collection
+  #   end
   class Builder
     def initialize
       reset

data/lib/cyc/client.rb

@@ -1,99 +1,169 @@
-require 'net/telnet'
+require 'uri'
+require 'cyc/connection'
 require 'cyc/exception'
 
-module Cyc
+module Cyc #:nodoc:
   # Author:: Aleksander Pohl (mailto:apohllo@o2.pl)
   # License:: MIT/X11 License
   #
-  # This class is the implementation of the Cyc server client.
+  # This class is the implementation of a Cyc client.
+  #
+  # Example:
+  #
+  #   cyc = Cyc::Client.new
+  #   cyc.genls? :Dog, :Animal # checks if Dog generalizes to Animal
+  #   #=> true
+  #   cyc.genls? :Animal, :Dog # checks if Animal generalizes to Dog
+  #   #=> nil
   class Client
     # If set to true, all communication with the server is logged
     # to standard output
     attr_accessor :debug
-    attr_reader :host, :port
+
+    # The +host+ the client connects to.
+    attr_reader :host
+
+    # The +port+ the client connects to.
+    attr_reader :port
+
+    # The +driver+ the client uses to connect to the server.
+    attr_reader :driver
+
+    # +true+ if the client is thread safe.
+    attr_reader :thread_safe
+    alias_method :thread_safe?, :thread_safe
+
+    # The +connection+ object - direct usage is discouraged.
+    # Use connection() call instead.
+    attr_accessor :conn
+    protected :conn
 
     # Creates new Client.
-    def initialize(host="localhost",port="3601",debug=false)
-      @debug = debug
-      @host = host
-      @port = port
+    # Usage:
+    #   Cyc::Client.new [options = {}]
+    #
+    # options:
+    # - +:host+ = +localhost+   server address
+    # - +:port+ = +3601+        server port
+    # - +:debug+ = +false+      initial debug flag
+    # - +:timeout+ = +0.2+      connection timeout in seconds
+    # - +:url+ (String):        +cyc://host:port+ overrides +:host+, +:port+
+    # - +:driver+ (Class) = Cyc::Connection::Socket  client connection driver class
+    # - +:thread_safe+ = +true+   set to +true+ if you want to share client between
+    #   threads
+    #
+    # Example:
+    #   Cyc::Client.new
+    #   Cyc::Client.new :host => 'cyc.example', :port => 3661, :debug => true
+    #   Cyc::Client.new :debug => true, :url => 'cyc://localhost/3661',
+    #     :timeout => 1.5, :driver => Cyc::Connection::SynchronyDriver
+    #
+    # Thread safe client:
+    #   Cyc::Client.new :thread_safe => true
+    def initialize(options={})
       @pid = Process.pid
-      @parser = Parser.new
-      @mts_cache = {}
-      @builder = Builder.new
+      unless Hash === options
+        raise ArgumentError.new("The Client.new(host,port) API is no longer supported.")
+      end
+      @host = options[:host] || "localhost"
+      @port = (options[:port] || 3601).to_i
+      if url = options[:url]
+        url = URI.parse(url)
+        @host = url.host || @host
+        @port = url.port || @port
+      end
+      @timeout = (options[:timeout] || 0.2).to_f
+      @driver = options[:driver] || Connection.driver
+      @debug = !!options[:debug]
+      @thread_safe = !!options[:thread_safe]
+
+      if @thread_safe
+        self.extend ThreadSafeClientExtension
+      else
+        @conn = nil
+      end
+    end
+
+    # Returns +true+ if the client is connected with the server.
+    def connected?
+      (conn=self.conn) && conn.connected? && @pid == Process.pid || false
     end
 
     # (Re)connects to the cyc server.
     def reconnect
+      # reuse existing connection driver
+      # to prevent race condition between fibers
+      conn = (self.conn||= @driver.new)
+      conn.disconnect if connected?
       @pid = Process.pid
-      @conn = Net::Telnet.new("Port" => @port, "Telnetmode" => false,
-                              "Timeout" => 600, "Host" => @host)
+      puts "connecting: #@host:#@port $$#@pid" if @debug
+      conn.connect(@host, @port, @timeout)
+      self
     end
 
+    # Usually the connection will be established on first use
+    # however connect() allows to force early connection:
+    #   Cyc::Client.new().connect
+    # Usefull in fiber concurrent environment to setup connection early.
+    alias_method :connect, :reconnect
     # Returns the connection object. Ensures that the pid of current
     # process is the same as the pid, the connection was initialized with.
     #
     # If the block is given, the command is guarded by assertion, that
     # it will be performed, even if the connection was reset.
     def connection
-      if @conn.nil? or @pid != Process.pid
-        reconnect
-      end
+      reconnect unless connected?
       if block_given?
         begin
-          yield @conn
+          yield conn
         rescue Errno::ECONNRESET
           reconnect
-          yield @conn
+          yield conn
         end
       else
-        @conn
+        conn
       end
     end
 
     protected :connection, :reconnect
 
-    # Clears the microtheory cache.
-    def clear_cache
-      @mts_cache = {}
-    end
-
-    # Closes connection with the server
+    # Closes connection with the server.
     def close
-      connection{|c| c.puts("(api-quit)")}
-      @conn = nil
+      conn.write("(api-quit)") if connected?
+    rescue Errno::ECONNRESET
+    ensure
+      self.conn = nil
     end
 
-    # Sends message +msg+ to the Cyc server and returns a parsed answer.
-    def talk(msg, options={})
-      send_message(msg)
+    # Sends the +messsage+ to the Cyc server and returns a parsed answer.
+    def talk(message, options={})
+      send_message(message)
       receive_answer(options)
     end
 
-    # Sends message +msg+ to the Cyc server and
+    # Sends the +message+ to the Cyc server and
     # returns the raw answer (i.e. not parsed).
-    def raw_talk(msg, options={})
-      send_message(msg)
+    def raw_talk(message, options={})
+      send_message(message)
       receive_raw_answer(options)
     end
 
-    # Scans the :message: to find out if the parenthesis are matched.
-    # Raises UnbalancedClosingParenthesis exception if there is not matched closing
+    # Scans the +message+ to find out if the parenthesis are matched.
+    # Raises UnbalancedClosingParenthesis exception if there is a not matched closing
     # parenthesis. The message of the exception contains the string with the
     # unmatched parenthesis highlighted.
-    # Raises UnbalancedOpeningParenthesis exception if there is not matched opening
+    # Raises UnbalancedOpeningParenthesis exception if there is a not matched opening
     # parenthesis.
     def check_parenthesis(message)
       count = 0
-      position = 0
-      message.scan(/./) do |char|
-        position += 1
-        next if char !~ /\(|\)/
+      message.scan(/[()]/) do |char|
         count += (char == "(" ?  1 : -1)
         if count < 0
+          # this *is* thread safe
+          position = $~.offset(0)[0]
           raise UnbalancedClosingParenthesis.
-            new((position > 1 ? message[0..position-2] : "") +
-              "<error>)</error>" + message[position..-1])
+            new((position > 1 ? message[0...position] : "") +
+              "<error>)</error>" + message[position+1..-1])
         end
       end
       raise UnbalancedOpeningParenthesis.new(count) if count > 0
@@ -101,74 +171,44 @@ module Cyc
 
     # Sends a raw message to the Cyc server. The user is
     # responsible for receiving the answer by calling
-    # +receive_answer+ or +receive_raw_answer+.
+    # receive_answer or receive_raw_answer.
     def send_message(message)
-      position = 0
       check_parenthesis(message)
-      @last_message = message
       puts "Send: #{message}" if @debug
-      connection{|c| c.puts(message)}
+      connection{|c| c.write(message)}
     end
 
     # Receives and parses an answer for a message from the Cyc server.
     def receive_answer(options={})
-      receive_raw_answer do |answer|
+      receive_raw_answer do |answer, last_message|
         begin
-          result = @parser.parse(answer,options[:stack])
+          result = Parser.new.parse answer, options[:stack]
         rescue ContinueParsing => ex
-          result = ex.stack
-          current_result = result
-          last_message = @last_message
+          current_result = result = ex.stack
           while current_result.size == 100 do
             send_message("(subseq #{last_message} #{result.size} " +
                          "#{result.size + 100})")
             current_result = receive_answer(options) || []
             result.concat(current_result)
           end
-        rescue CycError => ex
-          puts ex.to_s
-          return nil
         end
         return result
       end
     end
 
-    # Receives raw answer from server. If a +block+ is given
+    # Receives raw answer from server. If a block is given
     # the answer is yield to the block, otherwise the answer is returned.
     def receive_raw_answer(options={})
-      answer = connection{|c| c.waitfor(/./)}
-      puts "Recv: #{answer}" if @debug
-      if answer.nil?
-        raise CycError.new("Unknwon error occured. " +
-          "Check the submitted query in detail:\n" +
-          @last_message)
-      end
-      while not answer =~ /\n/ do
-        next_answer = connection{|c| c.waitfor(/./)}
-        puts "Recv: #{next_answer}" if @debug
-        if answer.nil?
-          answer = next_answer
-        else
-          answer += next_answer
-        end
-      end
-      # XXX ignore some potential asynchronous answers
-      # XXX check if everything works ok
-      #answer = answer.split("\n")[-1]
-      answer = answer.sub(/(\d\d\d) (.*)/,"\\2")
-      if($1.to_i == 200)
+      status, answer, last_message = connection{|c| c.read}
+      puts "Recv: #{last_message} -> #{status} #{answer}" if @debug
+      if status == 200
         if block_given?
-          yield answer
+          yield answer, last_message
         else
           return answer
         end
       else
-        unless $2.nil?
-          raise CycError.new($2.sub(/^"/,"").sub(/"$/,"") + "\n" + @last_message)
-        else
-          raise CycError.new("Unknown error! #{answer}")
-        end
-        nil
+        raise CycError.new(answer.sub(/^"/,"").sub(/"$/,"") + "\n" + last_message)
       end
     end
 
@@ -176,11 +216,12 @@ module Cyc
     # are translated into corresponding calls for Cyc server.
     #
     # E.g. if users initializes the client and calls some Ruby method
+    #
     #   cyc = Cyc::Client.new
     #   cyc.genls? :Dog, :Animal
     #
     # He/She returns a parsed answer from the server:
-    #   => "T"
+    #   => true
     #
     # Since dashes are not allowed in Ruby method names they are replaced
     # with underscores:
@@ -193,7 +234,7 @@ module Cyc
     #
     # As you see the Ruby symbols are translated into Cyc terms (not Cyc symbols!).
     #
-    # It is also possible to nest the calls to build more complex functions:
+    # It is also possible to nest the calls to build more complex calls:
     #
     #   cyc.with_any_mt do |cyc|
     #     cyc.min_genls :Dog
@@ -204,9 +245,22 @@ module Cyc
     #   (with-any-mt (min-genls #$Dog))
     #
     def method_missing(name,*args,&block)
-      @builder.reset
-      @builder.send(name,*args,&block)
-      talk(@builder.to_cyc)
+      builder = Builder.new
+      builder.send(name,*args,&block)
+      talk(builder.to_cyc)
+    end
+  end
+
+  module ThreadSafeClientExtension #:nodoc:
+    THR_VAR_TEMLPATE='_cyc_client_$%s_%s'
+
+    def self.extend_object(obj)
+      obj.instance_variable_set "@thrconn", (THR_VAR_TEMLPATE%[obj.object_id, 'conn']).intern
+      super
     end
+
+    protected
+    def conn; Thread.current[@thrconn]; end
+    def conn=(conn); Thread.current[@thrconn] = conn; end
   end
 end

data/lib/cyc/connection/buffer.rb

@@ -0,0 +1,69 @@
+require "cyc/exception"
+
+module Cyc #:nodoc:
+  module Connection #:nodoc:
+    # Author:: Rafal Michalski (mailto:royaltm75@gmail.com)
+    # Licence:: MIT/X11 License
+    #
+    # DataBuffer is chunky text data to server answer assembly class.
+    #
+    # Usage:
+    #
+    #   b = DataBuffer.new
+    #   b << "200 Some response\n" << "300 Some other" << " response\n" << "additional data\n"
+    #   b.next_result
+    #   => [200, "Some response"]
+    #   b.next_result
+    #   => [300, "Some other response\nadditional data"]
+    #   b.next_result
+    #   => nil
+    #   b << "Invalid response\n"
+    #   b.next_result("meta data")
+    #   Cyc::ProtocolError:
+    #     Unexpected data from server: "Invalid response", check the submitted query in detail:
+    #       "meta data"
+    #
+    class DataBuffer
+      EOL = "\n"
+      RESULT_MATCH = /^(\d\d\d) (.*)$/m
+
+      # Initializes an empty buffer.
+      def initialize
+        @buffer = ""
+      end
+
+      # Appends +data+ to the buffer.
+      def <<(data)
+        @buffer << data
+      end
+
+      # Returns the next complete result stored in the buffer.
+      def next_result(org_message=nil)
+        res_end = 0
+        size = @buffer.length
+        while res_end = @buffer.index(EOL, res_end)
+          res_end += 1
+          if res_end == size || RESULT_MATCH === @buffer[res_end..-1]
+            result = @buffer.slice!(0, res_end).chomp EOL
+            if RESULT_MATCH === result
+              return [$1.to_i, $2]
+            else
+              raise ProtocolError.new("Unexpected data from server: #{result.inspect}, " +
+                "check the submitted query in detail:\n#{org_message.inspect}")
+            end
+          end
+        end
+      end
+
+      # String representation of the buffer.
+      def to_s
+        @buffer
+      end
+
+      # Clears the buffer contents.
+      def discard!
+        @buffer.clear
+      end
+    end
+  end
+end

data/lib/cyc/connection/driver.rb

@@ -0,0 +1,12 @@
+module Cyc #:nodoc:
+  # Use Cyc::Connection.driver = Cyc::Connection::SomeDriver
+  # to set default connection driver.
+  module Connection
+    EOL = "\n"
+    class << self
+      # The driver used to connect to the Cyc server.
+      attr_accessor :driver
+    end
+  end
+end
+Cyc::Connection.driver = nil

data/lib/cyc/connection/socket.rb

@@ -0,0 +1,95 @@
+require "socket"
+require "cyc/connection/driver"
+require "cyc/exception"
+require "cyc/connection/buffer"
+
+module Cyc #:nodoc:
+  module Connection #:nodoc:
+    # TCPSocket Cyc::Client driver
+    # Author:: Rafal Michalski (mailto:royaltm75@gmail.com)
+    # Licence:: MIT/X11 License
+    #
+    # Default driver for Cyc::Client.
+    #
+    class SocketDriver
+      # The type of the driver, i.e. +:socket+.
+      def self.type; :socket; end
+
+      # Initialize a new driver.
+      def initialize
+        @sock = nil
+        @buffer = DataBuffer.new
+        @last_message = nil
+      end
+
+      # Returns true if the driver is connected to the server.
+      def connected?
+        !! @sock
+      end
+
+      # Connects to the server on +host+ and +port+ with given
+      # connection +timeout+.
+      def connect(host, port, timeout=0.2)
+        with_timeout(timeout.to_f) do
+          @sock = TCPSocket.new(host, port)
+          @sock.sync = true
+          @sock.binmode
+          #@sock.setsockopt Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1
+        end
+      end
+
+      # Disconnects the driver from the server.
+      def disconnect
+        @sock.close if @sock
+      rescue
+        # This should go to log #2.
+      ensure
+        @sock = nil
+        @buffer.discard!
+      end
+
+      # Send a message to the server.
+      def write(rawmsg)
+        @last_message = rawmsg
+        @sock.write(rawmsg + EOL)
+        # ensure that the connection is still with a server
+        # and wait for an answer at the same time
+        if @sock.eof?
+          disconnect
+          raise Errno::ECONNRESET
+        end
+      end
+
+      # Read next message from the server.
+      def read
+        begin
+          @buffer << @sock.readpartial(4096)
+        end until result = @buffer.next_result(@last_message)
+        result << @last_message
+      rescue IOError, EOFError, Errno::ECONNRESET
+        disconnect
+        raise Errno::ECONNRESET
+      end
+
+    protected
+
+      # borrowed from redis-rb
+      begin
+        require "system_timer"
+
+        def with_timeout(seconds, &block)
+          SystemTimer.timeout_after(seconds, &block)
+        end
+
+      rescue LoadError
+        require "timeout"
+
+        def with_timeout(seconds, &block)
+          Timeout.timeout(seconds, &block)
+        end
+      end
+    end
+  end
+end
+
+Cyc::Connection.driver = Cyc::Connection::SocketDriver

data/lib/cyc/connection/synchrony.rb

@@ -0,0 +1,167 @@
+require "em-synchrony"
+require "cyc/connection/driver"
+require "cyc/exception"
+require "cyc/connection/buffer"
+module Cyc #:nodoc:
+  module Connection #:nodoc:
+    class ConnectionClient < EventMachine::Connection
+      include EventMachine::Deferrable
+
+      def post_init
+        @req = []
+        @connected = false
+        @buffer = DataBuffer.new
+      end
+
+      def connection_completed
+        @connected = true
+        succeed
+      end
+
+      def connected?
+        @connected
+      end
+
+      def receive_data(data)
+        @buffer << data
+
+        begin
+          while (result = @buffer.next_result(@req.first))
+            unless @req.empty?
+              msg, req = @req.shift(2)
+              req.succeed(result << msg)
+            end
+          end
+        rescue RuntimeError => err
+          @req.each_slice(2) {|_, r| r.fail [:error, err]}
+          @req.clear
+          close_connection
+        end
+      end
+
+      def read
+        EventMachine::Synchrony.sync @req.last unless @req.empty?
+      end
+
+      def send(data)
+        @req << data << EventMachine::DefaultDeferrable.new
+        callback { send_data data + EOL }
+        @req.last
+      end
+
+      def unbind
+        @connected = false
+        @buffer.discard!
+        unless @req.empty?
+          @req.each_slice(2) {|_, r| r.fail [:error, Errno::ECONNRESET]}
+          @req.clear
+        end
+        fail
+      end
+    end
+
+    # EM-Synchrony Cyc::Client driver
+    # Author:: Rafal Michalski (mailto:royaltm75@gmail.com)
+    # Licence:: MIT/X11 License
+    #
+    # Requires: igrigorik/em-synchrony
+    #
+    # To use this driver simply require this file
+    # e.g.
+    #   require 'cyc/connection/synchrony'
+    # beside 'cycr'
+    #
+    # If required before 'cycr' then the SocketDriver will not be loaded
+    # (however you can still load it by hand: require 'cyc/connection/socket'
+    # but be carefull though it will override default Cyc::Connection.driver).
+    #
+    # If required after 'cycr' then the SocketDriver will be preserved but
+    # the default driver will be set to SynchronyDriver.
+    #
+    # Async fiber example:
+    #
+    #   require 'cyc/connection/synchrony'
+    #   require 'cycr'
+    #   EM.synchrony do
+    #     cyc = EM::Synchrony::ConnectionPool.new(size: 5) do
+    #       Cyc::Client.new :url => 'cyc://localhost:3601', :debug => true
+    #     end
+    #     puts cyc.driver, cyc.driver.type.inspect
+    #     Fiber.new do
+    #       puts "Ani", cyc.fi_complete("Ani").inspect
+    #     end.resume
+    #     puts "Mi", cyc.talk('(fi-complete "Mi")').inspect
+    #     EM.stop
+    #   end
+    #
+    # `Mi` will arrive before `Ani`
+    #
+    # Warning: always use EM::Synchrony::ConnectionPool to handle Fiber
+    # concurrency race conditions.
+    class SynchronyDriver
+      # The type of the driver, i.e. +:synchrony+.
+      def self.type; :synchrony; end
+
+      # Initialize a new driver.
+      def initialize
+        @connection = nil
+      end
+
+      # Returns true if the driver is connected to the server.
+      def connected?
+        @connection && @connection.connected?
+      end
+
+      # Connects to the server on +host+ and +port+ with given
+      # connection time-out.
+      def connect(host, port, timeout)
+        conn = EventMachine.connect(host, port, ConnectionClient) do |c|
+          c.pending_connect_timeout = [Float(timeout), 0.1].max
+        end
+
+        setup_connect_callbacks(conn, Fiber.current)
+      end
+
+      # Disconnects the driver from the server.
+      def disconnect
+        @connection.close_connection
+        @connection = nil
+      end
+
+      # Send a message to the server.
+      def write(rawmsg)
+        @connection.send(rawmsg)
+      end
+
+      # Read next message from the server.
+      def read
+        status, answer, msg = @connection.read
+        if status == :error
+          raise answer
+        else
+          return [status, answer, msg]
+        end
+      end
+
+    private
+
+      def setup_connect_callbacks(conn, f)
+        conn.callback do
+          @connection = conn
+          f.resume conn
+        end
+
+        conn.errback do
+          @connection = conn
+          f.resume :refused
+        end
+
+        r = Fiber.yield
+        raise Errno::ECONNREFUSED if r == :refused
+        r
+      end
+    end
+  end
+end
+
+Cyc::Connection.driver = Cyc::Connection::SynchronyDriver

data/lib/cyc/connection.rb

@@ -0,0 +1,2 @@
+require "cyc/connection/driver"
+require "cyc/connection/socket" if Cyc::Connection.driver.nil?

data/lib/cyc/exception.rb

@@ -22,6 +22,9 @@ module Cyc
 
   # Error raised if the message sent to the server has
   # more closing parentheses than opening parentheses.
+  # The exception message should indicate where is the
+  # first unbalanced closing parenthesis using 'error'
+  # tag.
   class UnbalancedClosingParenthesis < CycError
   end
 
@@ -40,4 +43,9 @@ module Cyc
     end
   end
 
+  # Exception raised by the parser if data received from server
+  # is not in expected format.
+  class ProtocolError < CycError
+  end
+
 end

data/lib/cyc/parser.rb

@@ -50,6 +50,8 @@ module Cyc
           top = stack.pop
           stack[-1].push top
           raise ContinueParsing.new(stack[0][0])
+        when :nil
+          stack[-1] << nil
         when :assertion_sep
           # ignore
         end

data/lib/cyc/version.rb

@@ -0,0 +1,3 @@
+module Cyc
+  VERSION = "0.2.0"
+end

data/lib/cycr.rb

@@ -8,3 +8,4 @@ require 'cyc/parser'
 require 'cyc/sexpr.rex'
 require 'cyc/symbol'
 require 'cyc/variable'
+require 'cyc/version'

metadata

@@ -2,15 +2,16 @@
 name: cycr
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Aleksander Pohl
+- Rafal Michalski
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2012-02-13 00:00:00 Z
+date: 2012-03-16 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
@@ -18,11 +19,22 @@ dependencies:
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
-        version: 1.2.9
+        version: 2.8.0
   type: :development
   version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: em-synchrony
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  version_requirements: *id002
 description: Ruby wrapper for (Open)Cyc server and ontology
 email: apohllo@o2.pl
 executables: []
@@ -43,6 +55,11 @@ files:
 - lib/cyc/builder.rb
 - lib/cyc/client.rb
 - lib/cyc/collection.rb
+- lib/cyc/connection.rb
+- lib/cyc/connection/buffer.rb
+- lib/cyc/connection/driver.rb
+- lib/cyc/connection/socket.rb
+- lib/cyc/connection/synchrony.rb
 - lib/cyc/exception.rb
 - lib/cyc/extensions.rb
 - lib/cyc/parser.rb
@@ -50,6 +67,7 @@ files:
 - lib/cyc/sexpr.rex.rb
 - lib/cyc/symbol.rb
 - lib/cyc/variable.rb
+- lib/cyc/version.rb
 - lib/cycr.rb
 - spec/parser.rb
 homepage: http://github.com/apohllo/cycr
@@ -66,7 +84,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      version: "0"
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: