spockets 0.0.6 → 0.1.0

data/README.rdoc

@@ -1,4 +1,4 @@
-== Spockets ==
+== Spockets
 
 Spockets is a simple library for dealing with multiple sockets.
 You supply a socket, and one or more blocks to
@@ -6,38 +6,37 @@ execute, and Spockets will make sure those blocks get
 executed when something comes in over the wire. It's just
 that simple.
 
-There is one requirement for spockets and that is the ActionPool.
-This just allows spockets to use a thread pool for executing
-blocks so you don't end up having to wait on slow blocks. You
-can even provide your own pool for spockets to use, so all the
-action can stay in one local pool.
+This library makes use of a thread pool for running user
+defined blocks. This setup allows us to use a single thread
+for socket monitoring, as well as prevents long running blocks
+from delaying everybody else.
 
-install (stable):
+=== install (easy):
 
-    gem install spockets
+    gem install actionpool
 
-install (unstable):
+=== install (less easy):
 
-    gem sources -a http://gems.github.com
-    gem install spox-spockets
+    git clone http://github.com/spox/actionpool.git
+    cd actionpool
+    gem build *.gemspec
+    gem install ./
 
-or
+=== install (less easy that's a little easier)
 
-    git clone http://github.com/spox/spockets.git
-    cd spockets
-    gem build spockets.gemspec
-    gem install ./
+{rip}[http://hellorip.com/about.html] makes it easy to install directly from a github repository.
 
-It has RDocs. They are short, but will be helpful and you
-should really consider giving them a look. If you want to
-view them online, you can see them here:
+=== Testing
 
-http://dev.modspox.com/~sine/spockets
+ActionPool is currently tested on:
 
-There is also a trac site. It has examples as well as
-a bug tracker. It's located at:
+* Ruby 1.8.6-p383
+* Ruby 1.8.7-p248
+* Ruby 1.9.1-p376
+* JRuby 1.4.0
 
-http://dev.modspox.com/trac/spockets
+It has RDocs. They are short, but will be helpful and you
+should really consider giving them a look.
 
 Examples are usually helpful, so here we go:
 
@@ -47,40 +46,25 @@ Code:
     require 'spockets'
     spockets = Spockets::Spockets.new
 
-    se = TCPServer.new(3000)
-    loop do
-        s = se.accept
-        puts "Socket: #{s}"
-        spockets.add(s){|string| puts "#{s}: #{string}" }
-    end
-    sleep
-
-
-Connecting:
-
-    > telnet 192.168.0.95 3000
-    Trying 192.168.0.95...
-    Connected to 192.168.0.95.
-    Escape character is '^]'.
-    goodbyeworld
-    ^]
-    telnet> quit
-    Connection closed.
-
-    > telnet 192.168.0.95 3000
-    Trying 192.168.0.95...
-    Connected to 192.168.0.95.
-    Escape character is '^]'.
-    foobar
-    complete
-    ^]
-    telnet> quit
-    Connection closed.
-
-Output:
-
-    Socket: #<TCPSocket:0x98ec5ac>
-    Socket: #<TCPSocket:0x98ec37c>
-    #<TCPSocket:0x98ec37c>: foobar
-    #<TCPSocket:0x98ec5ac>: goodbyeworld
-    #<TCPSocket:0x98ec37c>: complete
+    server = TCPServer.new('localhost', 4000)
+    socket = TCPSocket.new('localhost', 4000)
+    rsocket = server.accept
+    output = []
+    spockets.add(rsocket){|s|output << s.strip}
+    spockets.add(rsocket, 'data'){|s, d| output << "#{d}: #{s.strip}"}
+    spockets.on_close(rsocket){|s| output << "closed: #{s}"}
+    socket.puts "fubar"
+    socket.close
+    sleep(0.01)
+    p output
+
+    => ["fubar", "data: fubar", "closed: #<TCPSocket:0xb7637bdc>"]
+
+== Last remarks
+
+If you find any bugs, please report them through {github}[http://github.com/spox/spockets/issues]. If you are in need of any help, you can generally find me on DALnet and Freenode.
+
+== License
+
+    Spockets is licensed under the LGPLv3
+    Copyright (c) 2009 spox <spox@modspox.com>

data/lib/spockets.rb

@@ -1 +1,2 @@
+require 'rubygems'
 require 'spockets/Spockets'

data/lib/spockets/Exceptions.rb

@@ -1,37 +1,19 @@
 module Spockets
-
-    class DuplicateSocket < Exception
-        attr_reader :socket
-        def initialize(s)
-            @socket = s
-        end
-    end
     
-    class UnknownSocket < Exception
+    class UnknownSocket < StandardError
         attr_reader :socket
         def initialize(s)
             @socket = s
         end
     end
 
-    class AlreadyRunning < Exception
+    class AlreadyRunning < StandardError
     end
     
-    class NotRunning < Exception
+    class NotRunning < StandardError
     end
 
-    class Resync < Exception
-    end
-
-    class MissingArgument < Exception
-        attr_reader :argument
-        def initialize(a)
-            @argument = a
-        end
-
-        def to_s
-            "Missing required argument: #{@argument}"
-        end
+    class Resync < StandardError
     end
     
 end

data/lib/spockets/Spockets.rb

@@ -11,32 +11,51 @@ module Spockets
         # creates a new holder
         def initialize(args={})
             @sockets = {}
+            @sync = true
             @watcher = Watcher.new(:sockets => @sockets, :clean => args[:clean], :pool => args[:pool])
         end
+        
+        # Will sockets be resynced
+        def sync?
+            @sync.dup
+        end
+        
+        # b:: boolean
+        # Set whether resync on addition
+        def sync=(b)
+            @sync = b != false
+        end
+
+        # b:: boolean to force sync status to true
+        # Resync sockets in Watcher
+        def sync(b = nil)
+            @sync = b != false unless b.nil?
+            if(@sync)
+                begin
+                    @watcher.sync
+                rescue NotRunning
+                    start
+                end
+            end
+        end
 
         # socket:: socket to listen to
+        # data:: data to be passed to block. NOTE: string from 
+        # socket will be prepended to argument list
         # block:: block to execute when activity is received
         # Adds a socket to the list to listen to. When a string
         # is received on the socket, it will send it to the block
         # for processing
-        def add(socket, &block)
-            raise DuplicateSocket.new(socket) if @sockets.has_key?(socket)
-            @sockets[socket] = {}
-            @sockets[socket][:procs] = [block]
-            begin
-                @watcher.sync
-            rescue NotRunning
-                start
+        def add(socket, *data, &block)
+            raise ArgumentError.new('Block must be supplied') unless block_given?
+            raise ArgumentError.new('Block must allow at least one argument') if block.arity == 0
+            if(block.arity > 0 && block.arity != (data.size + 1))
+                raise ArgumentError.new('Invalid number of arguments for block')
             end
-        end
-
-        # socket:: socket in list
-        # block:: additional block to execute
-        # This will add additional blocks to the associated
-        # socket to be executed when a new string is received
-        def extra(socket, &block)
-            raise UnknownSocket.new(socket) unless @sockets.has_key?(socket)
-            @sockets[socket][:procs] << block
+            @sockets[socket] ||= {}
+            @sockets[socket][:procs] ||= []
+            @sockets[socket][:procs] << [data, block]
+            sync
         end
 
         # socket:: socket to remove
@@ -44,20 +63,24 @@ module Spockets
         def remove(socket)
             raise UnknownSocket.new(socket) unless @sockets.has_key?(socket)
             @sockets.delete(socket)
-            begin
-                @watcher.sync
-            rescue NotRunning
-                start
-            end
+            sync
         end
         
         # socket:: socket to add close action
+        # data:: data to be passed to the block. NOTE: socket
+        # will be prepended to argument list
         # block:: action to perform on socket close
         # Executes block when socket has been closed. Ideal
         # for reconnection needs
-        def on_close(socket, &block)
+        def on_close(socket, *data, &block)
             raise UnknownSocket.new(socket) unless @sockets.has_key?(socket)
-            @sockets[socket][:closed] = block
+            raise ArgumentError.new('Block must be supplied') unless block_given?
+            raise ArgumentError.new('Block must allow at least one argument') if block.arity == 0
+            if(block.arity > 0 && block.arity != (data.size + 1))
+                raise ArgumentError.new('Invalid number of arguments for block')
+            end
+            @sockets[socket][:closed] ||= []
+            @sockets[socket][:closed] << [data, block]
         end
         
         # remove all sockets

data/lib/spockets/Watcher.rb

@@ -1,5 +1,4 @@
 require 'actionpool'
-require 'actionpool/Exceptions'
 require 'iconv'
 
 module Spockets
@@ -9,8 +8,9 @@ module Spockets
         # :clean:: clean UTF8 strings or provide block to run on every read string
         # :pool:: ActionPool to use
         # Creates a new watcher for sockets
-        def initialize(args)
-            raise MissingArgument.new(:sockets) unless args[:sockets]
+        def initialize(args={})
+            raise ArgumentError.new('Expecting argument hash') unless args.is_a?(Hash)
+            raise ArgumentError.new('Missing required argument :sockets') unless args[:sockets] && args[:sockets].is_a?(Hash)
             @sockets = args[:sockets]
             @runner = nil
             @clean = args[:clean] && (args[:clean].is_a?(Proc) || args[:clean].is_a?(TrueClass)) ? args[:clean] : nil
@@ -21,18 +21,33 @@ module Spockets
 
         # start the watcher
         def start
-            @stop = false
-            @runner = Thread.new{watch} if @runner.nil? && @sockets.size > 0
+            if(@sockets.size < 0)
+                raise 'No sockets available for listening'
+            elsif(!@runner.nil? && @runner.alive?)
+                raise AlreadyRunning.new
+            else
+                @stop = false
+                @runner = Thread.new{watch}
+            end
         end
 
         # stop the watcher
         def stop
-            @stop = true
-            @runner.join(0.1)
-            @runner.raise Resync.new
-            @runner.join(0.1)
-            @runner.kill unless @runner.nil? || @runner.alive?
-            @runner = nil
+            if(@runner.nil? && @stop)
+                raise NotRunning.new
+            elsif(@runner.nil? || !@runner.alive?)
+                @stop = true
+                @runner = nil
+            else
+                @stop = true
+                if(@runner)
+                    @runner.raise Resync.new if @runner.alive? && @runner.stop?
+                    @runner.join(0.05) if @runner
+                    @runner.kill if @runner && @runner.alive?
+                end
+                @runner = nil
+            end
+            nil
         end
 
         # is the watcher running?
@@ -52,7 +67,8 @@ module Spockets
         end
         
         private
-        
+
+        # Watch the sockets and send strings for processing
         def watch
             until(@stop)
                 begin
@@ -60,7 +76,11 @@ module Spockets
                     for sock in resultset[0]
                         string = sock.gets
                         if(sock.closed? || string.nil?)
-                            @sockets[sock][:closed].call(sock) if @sockets[sock].has_key?(:closed)
+                            if(@sockets[sock][:closed])
+                                @sockets[sock][:closed].each do |pr|
+                                    pr[1].call(*([sock]+pr[0]))
+                                end
+                            end
                             @sockets.delete(sock)
                         else
                             string = clean? ? do_clean(string) : string
@@ -74,10 +94,18 @@ module Spockets
             @runner = nil
         end
 
+        # string:: String from socket
+        # sock:: Socket string originated from
         def process(string, sock)
-            @sockets[sock][:procs].each{|b| @pool.process{ b.call(string)}}
+            @sockets[sock][:procs].each do |pr|
+                @pool.process do
+                    pr[1].call(*([string]+pr[0]))
+                end
+            end
         end
 
+        # string:: String to be cleaned
+        # Applies clean block to string
         def do_clean(string)
             unless(@ic.nil?)
                 return untaint(string)
@@ -85,7 +113,9 @@ module Spockets
                 return @clean.call(string)
             end
         end
-        
+
+        # s:: string
+        # Attempt to clean up string
         def untaint(s)
             @ic.iconv(s + ' ')[0..-2]
         end

metadata

@@ -1,27 +1,27 @@
 --- !ruby/object:Gem::Specification 
 name: spockets
 version: !ruby/object:Gem::Version 
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors: 
-- spox
+  - spox
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2009-06-27 00:00:00 -07:00
+date: 2010-01-15 00:00:00 Z
 default_executable: 
 dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: ActionPool
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
+  - !ruby/object:Gem::Dependency 
+    name: actionpool
+    type: :runtime
+    version_requirement: 
+    version_requirements: !ruby/object:Gem::Requirement 
+      requirements: 
+        - - ~>
+          - !ruby/object:Gem::Version 
+            version: 0.2.3
+      version: 
 description: Socket helper library
 email: spox@modspox.com
 executables: []
@@ -29,43 +29,45 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README.rdoc
+  - README.rdoc
 files: 
-- README.rdoc
-- CHANGELOG
-- lib/spockets.rb
-- lib/spockets/Exceptions.rb
-- lib/spockets/Spockets.rb
-- lib/spockets/Watcher.rb
+  - README.rdoc
+  - CHANGELOG
+  - lib/spockets.rb
+  - lib/spockets/Exceptions.rb
+  - lib/spockets/Spockets.rb
+  - lib/spockets/Watcher.rb
 has_rdoc: true
-homepage: http://dev.modspox.com/trac/spockets
+homepage: http://github.com/spox/spockets
+licenses: []
+
 post_install_message: 
 rdoc_options: 
-- --title
-- Spockets
-- --main
-- README.rdoc
-- --line-numbers
+  - --title
+  - Spockets
+  - --main
+  - README.rdoc
+  - --line-numbers
 require_paths: 
-- lib
+  - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
   version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.1
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: Socket Helper
 test_files: []