spox-spockets 0.0.6

data/CHANGELOG

@@ -0,0 +1,11 @@
+0.0.6
+    * Fixed bug exposed when extremely fast input
+      is received.
+0.0.5
+
+    * Added a delete alias
+    * Added an on_close method to set an action
+        to run when a closed socket is detected
+    * Added an include? method to check if a socket
+        is currently being watched
+    * Added clear method to remove all sockets

data/README.rdoc

@@ -0,0 +1,86 @@
+== Spockets ==
+
+Spockets is a simple library for dealing with multiple sockets.
+You supply a socket, and one or more blocks to
+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.
+
+install (stable):
+
+    gem install spockets
+
+install (unstable):
+
+    gem sources -a http://gems.github.com
+    gem install spox-spockets
+
+or
+
+    git clone http://github.com/spox/spockets.git
+    cd spockets
+    gem build spockets.gemspec
+    gem install ./
+
+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:
+
+http://dev.modspox.com/~sine/spockets
+
+There is also a trac site. It has examples as well as
+a bug tracker. It's located at:
+
+http://dev.modspox.com/trac/spockets
+
+Examples are usually helpful, so here we go:
+
+Code:
+
+    require 'socket'
+    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

data/lib/spockets.rb

@@ -0,0 +1 @@
+require 'spockets/Spockets'

data/lib/spockets/Exceptions.rb

@@ -0,0 +1,37 @@
+module Spockets
+
+    class DuplicateSocket < Exception
+        attr_reader :socket
+        def initialize(s)
+            @socket = s
+        end
+    end
+    
+    class UnknownSocket < Exception
+        attr_reader :socket
+        def initialize(s)
+            @socket = s
+        end
+    end
+
+    class AlreadyRunning < Exception
+    end
+    
+    class NotRunning < Exception
+    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
+    end
+    
+end

data/lib/spockets/Spockets.rb

@@ -0,0 +1,96 @@
+require 'spockets/Exceptions'
+require 'spockets/Watcher'
+
+module Spockets
+
+    class Spockets
+
+        # :pool:: ActionPool if you would like to consolidate
+        # :clean:: Clean string. Set to true for default or 
+        #          provide a block to clean strings
+        # creates a new holder
+        def initialize(args={})
+            @sockets = {}
+            @watcher = Watcher.new(:sockets => @sockets, :clean => args[:clean], :pool => args[:pool])
+        end
+
+        # socket:: socket to listen to
+        # 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
+            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
+        end
+
+        # socket:: socket to remove
+        # Removes socket from list
+        def remove(socket)
+            raise UnknownSocket.new(socket) unless @sockets.has_key?(socket)
+            @sockets.delete(socket)
+            begin
+                @watcher.sync
+            rescue NotRunning
+                start
+            end
+        end
+        
+        # socket:: socket to add close action
+        # block:: action to perform on socket close
+        # Executes block when socket has been closed. Ideal
+        # for reconnection needs
+        def on_close(socket, &block)
+            raise UnknownSocket.new(socket) unless @sockets.has_key?(socket)
+            @sockets[socket][:closed] = block
+        end
+        
+        # remove all sockets
+        def clear
+            @sockets.clear
+            stop
+        end
+
+        # start spockets
+        def start
+            raise AlreadyRunning.new if @watcher.running?
+            @watcher.start
+        end
+
+        # stop spockets
+        def stop
+            raise NotRunning.new unless @watcher.running?
+            @watcher.stop
+        end
+
+        # currently watching sockets
+        def running?
+            !@watcher.nil? && @watcher.running?
+        end
+        
+        # socket:: a socket
+        # check if the given socket is being watched
+        def include?(socket)
+            @sockets.has_key?(socket)
+        end
+        
+        alias :delete :remove
+        
+    end
+
+end

data/lib/spockets/Watcher.rb

@@ -0,0 +1,93 @@
+require 'actionpool'
+require 'actionpool/Exceptions'
+require 'iconv'
+
+module Spockets
+    class Watcher
+
+        # :sockets:: socket list
+        # :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]
+            @sockets = args[:sockets]
+            @runner = nil
+            @clean = args[:clean] && (args[:clean].is_a?(Proc) || args[:clean].is_a?(TrueClass)) ? args[:clean] : nil
+            @pool = args[:pool] && args[:pool].is_a?(ActionPool::Pool) ? args[:pool] : ActionPool::Pool.new
+            @ic = @clean && @clean.is_a?(TrueClass) ? Iconv.new('UTF-8//IGNORE', 'UTF-8') : nil
+            @stop = true
+        end
+
+        # start the watcher
+        def start
+            @stop = false
+            @runner = Thread.new{watch} if @runner.nil? && @sockets.size > 0
+        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
+        end
+
+        # is the watcher running?
+        def running?
+            !@stop
+        end
+        
+        # clean incoming strings
+        def clean?
+            @clean
+        end
+
+        # Ensure all sockets are being listened to
+        def sync
+            raise NotRunning.new if @runner.nil?
+            @runner.raise Resync.new
+        end
+        
+        private
+        
+        def watch
+            until(@stop)
+                begin
+                    resultset = Kernel.select(@sockets.keys, nil, nil, nil)
+                    for sock in resultset[0]
+                        string = sock.gets
+                        if(sock.closed? || string.nil?)
+                            @sockets[sock][:closed].call(sock) if @sockets[sock].has_key?(:closed)
+                            @sockets.delete(sock)
+                        else
+                            string = clean? ? do_clean(string) : string
+                            process(string.dup, sock)
+                        end
+                    end
+                rescue Resync
+                    # break select and relisten #
+                end
+            end
+            @runner = nil
+        end
+
+        def process(string, sock)
+            @sockets[sock][:procs].each{|b| @pool.process{ b.call(string)}}
+        end
+
+        def do_clean(string)
+            unless(@ic.nil?)
+                return untaint(string)
+            else
+                return @clean.call(string)
+            end
+        end
+        
+        def untaint(s)
+            @ic.iconv(s + ' ')[0..-2]
+        end
+    end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: spox-spockets
+version: !ruby/object:Gem::Version 
+  version: 0.0.6
+platform: ruby
+authors: 
+- spox
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-16 00:00:00 -07:00
+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: 
+description: Socket helper library
+email: spox@modspox.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- 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
+post_install_message: 
+rdoc_options: 
+- --title
+- Spockets
+- --main
+- README.rdoc
+- --line-numbers
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Socket Helper
+test_files: []
+