gibson 1.0.2 → 1.0.3

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OGM1OGIwOGQzM2Y5NzhlNWEzYjk5NTBlNGNkNjg5NzcyYWUwNWZkNw==
+    NDkwOWNiM2EzZDcwYjAxMWNhMzUyNjYwODA0OWVmZjc0YzFlMjgxNQ==
   data.tar.gz: !binary |-
-    N2M4NzlhM2E0MDMzODcxZmUxZTUxYjI5MTBhZThiYjhjMzMxYzczMA==
+    NmI3MzIzMWNlOTgyMDY2MWM5NWM1YWE5NjkyNmNiZGI2NjZkNDc1Mg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NDk3ZjhjMDRmNTI1M2EyOTAwOGZjMDRmMTZiMDQwMzEzNGQ3MTBkMjc1NTYz
-    OGEwNWU4NDcxZjYyYzVlYjBjN2QwNzU3MjZhYWIwMDA1OGQxMWQ4YTYwZmIz
-    NTRkZDgxMzNkZDg4YzdjZGRhMTM1NGQyYjU4MDRhMzU0ODU2OTM=
+    Mjc3OGE1ZWI5YjYyMDllMGU1OTAyN2ZlZWRiMjQwYzViOWY2ZTQ5MmFlYTlh
+    OTNjYzFiZjkwZDI2ODg2NGMwZGY0N2QxOWJjODUyZjU0Yzk4ZWMxZDFiZjAw
+    MDVjMDk0ZGViOWMzOWJhMjI0YzQzODEzMDcwYWI5OTIyODYyMzU=
   data.tar.gz: !binary |-
-    OWIzYzY1OGRkNDkyNDViMTY2MTg5NWMzNDNiNzE4NmFjMmIwNmY4YzAwMjRj
-    NWM2YTkzNTk1MzAxYWRhNzUxZWM1M2JkOWFlMDJlYzI4MDliMmEyN2Y2MGY3
-    OWI1YzBlN2FlNDQ4NTQxNmVhNWFiMmZjNGNjNDZlOWI2MWEyMjk=
+    MGJkYTVhNGM5NDEyZTZjZGJjN2I0YmExMGI4ODcyMGM0NTdhN2QxYmVkN2Uy
+    ZDQ2Mzc1NzlhZDQzNDA4NmI4YzdjNWY0Njg0NzRiNWQ1ZGI0MjMzMGJlY2Ji
+    ZWY1N2E1YWRkYzkwMWQ2ZDA5MGJlMDQzMTBlYmJkMmI0YTg0ZmI=

data/lib/gibson/connection.rb

@@ -26,55 +26,86 @@
 # POSSIBILITY OF SUCH DAMAGE.
 module Gibson
     require 'socket'
-    
+    require 'timeout'
+
     class Connection
+        ## 
+        # Connection default options.
         DEFAULTS = {
+            # The UNIX socket path, if this option is set a UNIX socket connection will be used.
             :socket    => '/var/run/gibson.sock',
+            # The ip address to connect to, if this option is set a TCP socket connection will be used.
             :address   => nil,
+            # The tcp port to connect to.
             :port      => 10128,
+            # The connection and I/O timeout in milliseconds.
             :timeout   => 100,
+            # If a TCP connection will be used, set this to true to use the SO_KEEPALIVE flag on the socket.
             :keepalive => false
         }
 
+        ##
+        # Create a new Connection instance with custom options.
+        # If no options are specified, Connection.DEFAULTS will be used.
+        # For instance:
+        #    Gibson::Client.new                         # will create a connection to the default /var/run/gibson.sock UNIX socket.
+        #    Gibson::Client.new :address => '127.0.0.1' # will connect to localhost:10128
         def initialize(opts = {})
             @sock = nil
             @connected = false
             @options = DEFAULTS.merge(opts)
         end
 
+        ##
+        # Return true if connection is enstablished, otherwise false.
         def connected?
             @connected
         end
 
+        ##
+        # Attempt a connection with the specified options until @options[:timeout]
+        # is reached.
         def connect
-            if @options[:address] != nil
-                @sock = TCPSocket.new( @options[:address], @options[:port] ) 
-                @sock.setsockopt( Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true )
-                @sock.setsockopt( Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true ) if @options[:keepalive]
-            else
-                @sock = UNIXSocket.open( @options[:socket] )
-            end
+            Timeout.timeout(@options[:timeout]) do
+                if @options[:address] != nil
+                    @sock = TCPSocket.new( @options[:address], @options[:port] ) 
+                    @sock.setsockopt( Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true )
+                    @sock.setsockopt( Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true ) if @options[:keepalive]
+                else
+                    @sock = UNIXSocket.open( @options[:socket] )
+                end
 
-            @connected = true
+                @connected = true
+            end
         end
 
+        ##
+        # Close the connection.
         def close
-            @sock.close
+            @sock.close if connected?
         end
 
+        ##
+        # Wait for the socket to be in a writable state for @options[:timeout] milliseconds.
         def wait_writable
             IO.select(nil, [@sock], nil, @options[:timeout] ) || raise(Timeout::Error, "IO timeout")
         end
 
+        ##
+        # Wait for the socket to be in a readable state for @options[:timeout] milliseconds.
         def wait_readable
             IO.select( [@sock], nil, nil, @options[:timeout] ) || raise(Timeout::Error, "IO timeout")
         end
 
+        ##
+        # Write data to the socket.
         def write(data)
             wait_writable
             @sock.write data
         end
 
+        ##
+        # Read specified amount of data from the socket.
         def read(n)
             wait_readable
             @sock.recv n

data/lib/gibson/gibson.rb

@@ -29,16 +29,23 @@ require 'gibson/connection'
 
 module Gibson
     class Client
+        ##
+        # Create a new Gibson::Client instance, the options are passed to
+        # Gibson::Connection initialize method.
         def initialize(opts = {})
             @connection = nil
             @options = opts
         end
 
+        ##
+        # Create the connection.
         def connect
             @connection = Connection.new( @options )
             @connection.connect
         end
 
+        ##
+        # Decode a REPL_VAL reply.
         def decode_val( encoding, size, data )
             # plain string
             if encoding == Protocol::ENCODINGS[:plain]
@@ -56,6 +63,8 @@ module Gibson
             end
         end
 
+        ##
+        # Decode a REPL_KVAL reply.
         def decode_kval( data, size )
             left = size - 4
             count, data  = data.unpack( 'L<a' + left.to_s )
@@ -83,6 +92,8 @@ module Gibson
             obj
         end
 
+        ##
+        # Reply decoding wrapper.
         def decode( code, encoding, size, data )
             if code == Protocol::REPLIES[:val]
                 decode_val encoding, size, data
@@ -101,6 +112,10 @@ module Gibson
             end
         end
 
+        ##
+        # Send a query to the server given its opcode and arguments payload.
+        # Return the decoded data, or raise one of the RuntimeErrors defined 
+        # inside Gibson::Protocol.
         def query( opcode, payload = '' )
             connect if @connection == nil or not @connection.connected?
 
@@ -115,10 +130,21 @@ module Gibson
             decode code, encoding, size, data
         end
 
+        ##
+        # This method will be called for every undefined method call
+        # of Gibson::Client mapping the method to its opcode and creating
+        # its argument payload.
+        # For instance a call to:
+        #   client = Gibson::Client.new
+        #   client.set 0, 'foo', 'bar'
+        # Will be executed as:
+        #   client.query Protocol::COMMANDS[:set], '0 foo bar'
         def method_missing(name, *arguments)
             if Protocol::COMMANDS.has_key? name 
                 query Protocol::COMMANDS[name], arguments.join(' ')
             end
         end
+
+        private :decode_val, :decode_kval, :decode
     end
 end

data/lib/gibson/protocol.rb

@@ -25,13 +25,19 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 module Gibson
+    # A generic protocol error.
     class GenericError < RuntimeError; end
+    # Key or prefix not found.
     class NotFoundError < RuntimeError; end
+    # Specified value is not a number.
     class NaNError < RuntimeError; end
+    # The server is out of memory.
     class OutOfMemoryError < RuntimeError; end
+    # The object is locked and can't be modified.
     class LockedError < RuntimeError; end
 
     class Protocol
+        # Query opcodes.
         COMMANDS = {
             :set     => 1,
             :ttl     => 2,
@@ -57,6 +63,7 @@ module Gibson
             :end     => 0xff
         }
 
+        # Server replies opcodes.
         REPLIES = {
             :error 	   => 0, # Generic error
             :not_found => 1, # Key/Prefix not found
@@ -68,6 +75,7 @@ module Gibson
             :kval	   => 7  # Ok, [ key => value, ... ] follows
         }
 
+        # Error code to exception map.
         ERRORS = {
             0 => GenericError,
             1 => NotFoundError,
@@ -76,12 +84,18 @@ module Gibson
             4 => LockedError
         }
 
+        # Incoming data encodings.
         ENCODINGS = {
-            :plain  => 0x00, # the item is in plain encoding and data points to its buffer
-            :lzf    => 0x01, # PLAIN but compressed data with lzf
-            :number => 0x02  # the item contains a number and data pointer is actually that number
+            # the item is in plain encoding and data points to its buffer
+            :plain  => 0x00, 
+            # PLAIN but compressed data with lzf
+            :lzf    => 0x01, 
+            # the item contains a number and data pointer is actually that number
+            :number => 0x02 
         }
 
+        ##
+        # Return true if the specified code is an error code, otherwise false.
         def self.error? (code)
             code >= REPLIES[:error] && code <= REPLIES[:locked]
         end

data/lib/gibson/version.rb

@@ -25,6 +25,6 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 module Gibson 
-    VERSION = '1.0.2'
+    VERSION = '1.0.3'
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gibson
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Simone Margaritelli