dat-tcp 0.1.1 → 0.2.0

data/dat-tcp.gemspec

@@ -6,20 +6,18 @@ require 'dat-tcp/version'
 Gem::Specification.new do |gem|
   gem.name          = "dat-tcp"
   gem.version       = DatTCP::VERSION
-  gem.authors       = ["Collin Redding"]
-  gem.email         = ["collin.redding@me.com"]
-  gem.description   = "DatTCP is a generic threaded TCP server implementation. It provides a " \
-                      "simple to use interface for defining a TCP server. It is intended to be " \
-                      "used as a base for application-level servers."
-  gem.summary       = "DatTCP is a generic threaded TCP server for defining application-level " \
-                      "servers."
-  gem.homepage      = ""
+  gem.authors       = ["Collin Redding", "Kelly Redding"]
+  gem.email         = ["collin.redding@me.com", "kelly@kellyredding.com"]
+  gem.description   = "A generic threaded TCP server API.  It is"\
+                      " designed for use as a base for application servers."
+  gem.summary       = "A generic threaded TCP server API"
+  gem.homepage      = "https://github.com/redding/dat-tcp"
 
   gem.files         = `git ls-files -- lib/* Gemfile Rakefile *.gemspec`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_development_dependency('assert',        ['~>0.8'])
-  gem.add_development_dependency('assert-mocha',  ['~>0.1'])
+  gem.add_development_dependency('assert',        ['~> 1.0'])
+  gem.add_development_dependency('assert-mocha',  ['~> 1.0'])
 end

data/lib/dat-tcp.rb

@@ -1,158 +1,248 @@
-# DatTCP Server module is the main interface for defining a new server. It
-# should be mixed in and provides methods for starting and stopping the main
-# server loop. The `serve` method is intended to be overwritten so users can
-# define handling connections. It's primary loop is:
-#
-# 1. Wait for worker
-# 1. Accept connection
-# 2. Process connection by handing off to worker
-#
-# This is repeated until the server is stopped.
-#
-# Options:
-#   `max_workers`   - (integer) The maximum number of workers for processing
-#                     connections. More threads causes more concurrency but also
-#                     more overhead. This defaults to 4 workers.
-#   `debug`         - (boolean) Whether or not to have the server log debug
-#                     messages for when the server starts and stops and when a
-#                     client connects and disconnects.
-#   `ready_timeout` - (float) The timeout used with `IO.select` waiting for a
-#                     connection to occur. This can be set to 0 to not wait at
-#                     all. Defaults to 1 (second).
-#
-require 'logger'
+require 'ostruct'
 require 'socket'
 require 'thread'
 
 module DatTCP; end
 
 require 'dat-tcp/logger'
-require 'dat-tcp/workers'
+require 'dat-tcp/worker_pool'
 require 'dat-tcp/version'
 
 module DatTCP
 
   module Server
-    attr_reader :host, :port, :workers, :debug, :logger, :ready_timeout
-    attr_reader :tcp_server, :thread
 
-    def initialize(host, port, options = nil)
-      options ||= {}
-      options[:max_workers] ||= 4
+    attr_reader :logger
 
-      @host, @port = [ host, port ]
-      @logger = DatTCP::Logger.new(options[:debug])
-      @workers = DatTCP::Workers.new(options[:max_workers], self.logger)
-      @ready_timeout = options[:ready_timeout] || 1
+    def initialize(config = nil)
+      config = OpenStruct.new(config || {})
+      @backlog_size  = config.backlog_size  || 1024
+      @debug         = config.debug         || false
+      @min_workers   = config.min_workers   || 2
+      @max_workers   = config.max_workers   || 4
+      @ready_timeout = config.ready_timeout || 1
 
-      @mutex = Mutex.new
-      @condition_variable = ConditionVariable.new
+      @logger = DatTCP::Logger.new(@debug)
+
+      @tcp_server       = nil
+      @work_loop_thread = nil
+      @worker_pool      = nil
+      set_state :stop
     end
 
-    def start
-      if !self.running?
-        @shutdown = false
-        !!self.start_server_thread
+    # Socket Options:
+    # * SOL_SOCKET   - specifies the protocol layer the option applies to.
+    #                  SOL_SOCKET is basic socket options (as opposed to
+    #                  something like IPPROTO_TCP for TCP socket options).
+    # * SO_REUSEADDR - indicates that the rules used in validating addresses
+    #                  supplied in a bind(2) call should allow reuse of local
+    #                  addresses. This will allow us to re-bind to a port if we
+    #                  were shutdown and started right away. This will still
+    #                  throw an "address in use" if a socket is active on the
+    #                  port.
+
+    def listen(*args)
+      build_server_method = if args.size == 2
+        :new
+      elsif args.size == 1
+        :for_fd
       else
-        false
+        raise InvalidListenArgsError.new
       end
+      set_state :listen
+      run_hook 'on_listen'
+      @tcp_server = TCPServer.send(build_server_method, *args)
+
+      @tcp_server.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+      run_hook 'configure_tcp_server', @tcp_server
+
+      @tcp_server.listen(@backlog_size)
     end
 
-    def stop
-      if self.running?
-        @shutdown = true
-        @mutex.synchronize do
-          while self.thread
-            @condition_variable.wait(@mutex)
-          end
-        end
-      else
-        false
-      end
+    def run(client_file_descriptors = nil)
+      raise NotListeningError.new if !self.listening?
+      set_state :run
+      run_hook 'on_run'
+      @work_loop_thread = Thread.new{ work_loop(client_file_descriptors) }
+    end
+
+    def pause(wait = true)
+      set_state :pause
+      run_hook 'on_pause'
+      wait_for_shutdown if wait
+    end
+
+    def stop(wait = true)
+      set_state :stop
+      run_hook 'on_stop'
+      wait_for_shutdown if wait
+    end
+
+    def halt(wait = true)
+      set_state :halt
+      run_hook 'on_halt'
+      wait_for_shutdown if wait
+    end
+
+    def stop_listening
+      @tcp_server.close rescue false
+      @tcp_server = nil
+    end
+
+    def ip
+      @tcp_server.addr[2] if self.listening?
+    end
+
+    def port
+      @tcp_server.addr[1] if self.listening?
+    end
+
+    def file_descriptor
+      @tcp_server.fileno if self.listening?
+    end
+
+    def client_file_descriptors
+      @worker_pool ? @worker_pool.connections.map(&:fileno) : []
     end
 
-    def join_thread(limit = nil)
-      @thread.join(limit) if self.running?
+    def listening?
+      !!@tcp_server
     end
 
     def running?
-      !!@thread
+      !!@work_loop_thread
     end
 
     # This method should be overwritten to handle new connections
     def serve(socket)
     end
 
-    def name
-      "#{self.class}|#{self.host}:#{self.port}"
+    # Hooks
+
+    def on_listen
+    end
+
+    def configure_tcp_server(tcp_server)
+    end
+
+    def on_run
+    end
+
+    def on_pause
+    end
+
+    def on_stop
+    end
+
+    def on_halt
     end
 
     def inspect
       reference = '0x0%x' % (self.object_id << 1)
-      "#<#{self.class}:#{reference} @host=#{self.host.inspect} @port=#{self.port.inspect}>"
+      "#<#{self.class}:#{reference}".tap do |inspect_str|
+        inspect_str << " @state=#{@state.inspect}"
+        if self.listening?
+          port, ip = @tcp_server.addr[1, 2]
+          inspect_str << " @ip=#{ip.inspect} @port=#{port.inspect}"
+        end
+        inspect_str << " @work_loop_status=#{@work_loop_thread.status.inspect}" if self.running?
+        inspect_str << ">"
+      end
     end
 
     protected
 
-    def start_server_thread
-      @tcp_server = TCPServer.new(self.host, self.port)
-      @mutex.synchronize do
-        @thread = Thread.new{ self.work_loop }
+    def work_loop(client_file_descriptors = nil)
+      self.logger.info "Starting work loop..."
+      pool_args = [ @min_workers, @max_workers, @debug ]
+      @worker_pool = DatTCP::WorkerPool.new(*pool_args){|socket| serve(socket) }
+      self.enqueue_file_descriptors(client_file_descriptors || [])
+      while @state.run?
+        @worker_pool.enqueue_connection self.accept_connection
       end
+      self.logger.info "Stopping work loop..."
+      shutdown_worker_pool if !@state.halt?
+    rescue Exception => exception
+      self.logger.error "Exception occurred, stopping server!"
+      self.logger.error "#{exception.class}: #{exception.message}"
+      self.logger.error exception.backtrace.join("\n")
+    ensure
+      close_connection if !@state.pause?
+      clear_thread
+      self.logger.info "Stopped work loop"
     end
 
-    # Notes:
-    # * If the server has been shutdown, then `accept_connection` will return
-    #   `nil` always. This will exit the loop and begin shutting down the server.
-    def work_loop
-      self.logger.info("Starting...")
-      while !@shutdown
-        connection = self.accept_connection
-        self.workers.process(connection){|client| self.serve(client) } if connection
+    def enqueue_file_descriptors(file_descriptors)
+      file_descriptors.each do |file_descriptor|
+        @worker_pool.enqueue_connection TCPSocket.for_fd(file_descriptor)
       end
-    rescue Exception => exception
-      self.logger.info("Exception occurred, stopping server!")
-    ensure
-      self.shutdown_server_thread(exception)
-    end
-
-    # This method is a accept-loop waiting for a new connection. It uses
-    # `IO.select` with a timeout to wait for a socket to be ready. Once the
-    # socket is ready, it calls `accept` and returns the connection. If the
-    # server socket doesn't have a new connection waiting, the loop starts over.
-    # In the case the server has been shutdown, it will also break out of the
-    # loop.
-    #
-    # Notes:
-    # * If the server has been shutdown this will return `nil`.
+    end
+
+    # An accept-loop waiting for new connections. Will wait for a connection
+    # (up to `ready_timeout`) and accept it. `IO.select` with the timeout
+    # allows the server to be responsive to shutdowns.
     def accept_connection
-      loop do
-        if IO.select([ @tcp_server ], nil, nil, self.ready_timeout)
-          return @tcp_server.accept
-        elsif @shutdown
-          return
-        end
+      while @state.run?
+        return @tcp_server.accept if self.connection_ready?
       end
     end
 
-    # Notes:
-    # * Stopping the workers is a graceful shutdown. It will let them each finish
-    #   processing by joining their threads.
-    def shutdown_server_thread(exception = nil)
-      self.logger.info("Stopping...")
-      @tcp_server.close rescue false
-      self.logger.info("  letting any running workers finish...")
-      self.workers.finish
-      self.logger.info("Stopped")
-      if exception
-        self.logger.error("#{exception.class}: #{exception.message}")
-        self.logger.error(exception.backtrace.join("\n"))
+    def connection_ready?
+      !!IO.select([ @tcp_server ], nil, nil, @ready_timeout)
+    end
+
+    def shutdown_worker_pool
+      self.logger.info "Shutting down worker pool, letting it finish..."
+      @worker_pool.shutdown
+    end
+
+    def close_connection
+      self.logger.info "Closing TCP server connection..."
+      self.stop_listening
+    end
+
+    def clear_thread
+      @work_loop_thread = nil
+    end
+
+    def wait_for_shutdown
+      @work_loop_thread.join if @work_loop_thread
+    end
+
+    def run_hook(method, *args)
+      self.send(method, *args)
+    end
+
+    def set_state(name)
+      @state = State.new(name)
+    end
+
+    class State < String
+
+      def initialize(value)
+        super value.to_s
       end
-      @mutex.synchronize do
-        @thread = nil
-        @condition_variable.signal
+
+      [ :listen, :run, :stop, :halt, :pause ].each do |name|
+        define_method("#{name}?"){ self.to_sym == name }
       end
-      true
+
+    end
+
+  end
+
+  class InvalidListenArgsError < ArgumentError
+
+    def initialize
+      super "invalid arguments, must be either a file descriptor or an ip and port"
+    end
+
+  end
+
+  class NotListeningError < RuntimeError
+
+    def initialize
+      super "`listen` must be called before calling `run`"
     end
 
   end

data/lib/dat-tcp/version.rb

@@ -1,3 +1,3 @@
 module DatTCP
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/dat-tcp/worker_pool.rb

@@ -0,0 +1,213 @@
+require 'thread'
+
+require 'dat-tcp/logger'
+
+module DatTCP
+
+  class WorkerPool
+    attr_reader :logger, :spawned
+
+    def initialize(min = 0, max = 1, debug = false, &serve_proc)
+      @min_workers = min
+      @max_workers = max
+      @logger      = DatTCP::Logger.new(debug)
+      @serve_proc  = serve_proc
+
+      @queue           = DatTCP::Queue.new
+      @workers_waiting = DatTCP::WorkersWaiting.new
+
+      @mutex   = Mutex.new
+      @workers = []
+      @spawned = 0
+
+      @min_workers.times{ self.spawn_worker }
+    end
+
+    def connections
+      @queue.items
+    end
+
+    def waiting
+      @workers_waiting.count
+    end
+
+    # Check if all workers are busy before adding the connection. When the
+    # connection is added, a worker will stop waiting (if it was idle). Because
+    # of that, we can't reliably check if all workers are busy. We might think
+    # all workers are busy because we just woke up a sleeping worker to serve
+    # this connection. Then we would spawn a worker to do nothing.
+    def enqueue_connection(socket)
+      return if !socket
+      new_worker_needed = all_workers_are_busy?
+      @queue.push socket
+      self.spawn_worker if new_worker_needed && havent_reached_max_workers?
+    end
+
+    # Shutdown each worker and then the queue. Shutting down the queue will
+    # signal any workers waiting on it to wake up, so they can start shutting
+    # down. If a worker is processing a connection, then it will be joined and
+    # allowed to finish.
+    # **NOTE** Any connections that are on the queue are not served.
+    def shutdown
+      @workers.each(&:shutdown)
+      @queue.shutdown
+
+      # use this pattern instead of `each` -- we don't want to call `join` on
+      # every worker (especially if they are shutting down on their own), we
+      # just want to make sure that any who haven't had a chance to finish
+      # get to (this is safe, otherwise you might get a dead thread in the
+      # `each`).
+      @workers.first.join until @workers.empty?
+    end
+
+    # public, because workers need to call it for themselves
+    def despawn_worker(worker)
+      @mutex.synchronize do
+        @spawned -= 1
+        @workers.delete worker
+      end
+    end
+
+    protected
+
+    def spawn_worker
+      @mutex.synchronize do
+        worker = DatTCP::Worker.new(self, @queue, @workers_waiting) do |socket|
+          self.serve_socket(socket)
+        end
+        @workers << worker
+        @spawned += 1
+        worker
+      end
+    end
+
+    def serve_socket(socket)
+      begin
+        @serve_proc.call(socket)
+      rescue Exception => exception
+        self.logger.error "Exception raised while serving connection!"
+        self.logger.error "#{exception.class}: #{exception.message}"
+        self.logger.error exception.backtrace.join("\n")
+      ensure
+        socket.close rescue false
+      end
+    end
+
+    def all_workers_are_busy?
+      @workers_waiting.count <= 0
+    end
+
+    def havent_reached_max_workers?
+      @mutex.synchronize do
+        @spawned < @max_workers
+      end
+    end
+
+  end
+
+  class Queue
+
+    def initialize
+      @items = []
+      @shutdown = false
+      @mutex              = Mutex.new
+      @condition_variable = ConditionVariable.new
+    end
+
+    def items
+      @mutex.synchronize{ @items }
+    end
+
+    # Add the connection and wake up the first worker (the `signal`) that's
+    # waiting (because of `wait_for_new_connection`)
+    def push(socket)
+      raise "Unable to add connection while shutting down" if @shutdown
+      @mutex.synchronize do
+        @items << socket
+        @condition_variable.signal
+      end
+    end
+
+    def pop
+      @mutex.synchronize{ @items.pop }
+    end
+
+    def empty?
+      @mutex.synchronize{ @items.empty? }
+    end
+
+    # wait to be signaled by `push`
+    def wait_for_new_connection
+      @mutex.synchronize{ @condition_variable.wait(@mutex) }
+    end
+
+    # wake up any workers who are idle (because of `wait_for_new_connection`)
+    def shutdown
+      @shutdown = true
+      @mutex.synchronize{ @condition_variable.broadcast }
+    end
+
+  end
+
+  class Worker
+
+    def initialize(pool, queue, workers_waiting, &block)
+      @pool            = pool
+      @queue           = queue
+      @workers_waiting = workers_waiting
+      @block           = block
+      @shutdown        = false
+      @thread          = Thread.new{ work_loop }
+    end
+
+    def shutdown
+      @shutdown = true
+    end
+
+    def join
+      @thread.join if @thread
+    end
+
+    protected
+
+    def work_loop
+      loop do
+        self.wait_for_work
+        break if @shutdown
+        @block.call @queue.pop
+      end
+    ensure
+      @pool.despawn_worker(self)
+    end
+
+    # Wait for a connection to serve by checking if the queue is empty.
+    def wait_for_work
+      while @queue.empty?
+        return if @shutdown
+        @workers_waiting.increment
+        @queue.wait_for_new_connection
+        @workers_waiting.decrement
+      end
+    end
+
+  end
+
+  class WorkersWaiting
+    attr_reader :count
+
+    def initialize
+      @mutex = Mutex.new
+      @count = 0
+    end
+
+    def increment
+      @mutex.synchronize{ @count += 1 }
+    end
+
+    def decrement
+      @mutex.synchronize{ @count -= 1 }
+    end
+
+  end
+
+end

metadata

@@ -1,21 +1,22 @@
 --- !ruby/object:Gem::Specification 
 name: dat-tcp
 version: !ruby/object:Gem::Version 
-  hash: 25
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Collin Redding
+- Kelly Redding
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2012-11-14 00:00:00 Z
+date: 2013-02-16 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   prerelease: false
@@ -24,11 +25,11 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 27
+        hash: 15
         segments: 
+        - 1
         - 0
-        - 8
-        version: "0.8"
+        version: "1.0"
   requirement: *id001
   name: assert
   type: :development
@@ -39,17 +40,18 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 9
+        hash: 15
         segments: 
-        - 0
         - 1
-        version: "0.1"
+        - 0
+        version: "1.0"
   requirement: *id002
   name: assert-mocha
   type: :development
-description: DatTCP is a generic threaded TCP server implementation. It provides a simple to use interface for defining a TCP server. It is intended to be used as a base for application-level servers.
+description: A generic threaded TCP server API.  It is designed for use as a base for application servers.
 email: 
 - collin.redding@me.com
+- kelly@kellyredding.com
 executables: []
 
 extensions: []
@@ -63,8 +65,8 @@ files:
 - lib/dat-tcp.rb
 - lib/dat-tcp/logger.rb
 - lib/dat-tcp/version.rb
-- lib/dat-tcp/workers.rb
-homepage: ""
+- lib/dat-tcp/worker_pool.rb
+homepage: https://github.com/redding/dat-tcp
 licenses: []
 
 post_install_message: 
@@ -96,6 +98,6 @@ rubyforge_project:
 rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
-summary: DatTCP is a generic threaded TCP server for defining application-level servers.
+summary: A generic threaded TCP server API
 test_files: []
 

data/lib/dat-tcp/workers.rb

@@ -1,99 +0,0 @@
-# DatTCP's workers is a class for managing the worker threads that are
-# spun up to handle clients. It manages a list of working threads and provides
-# external methods for working with them. Working threads are managed by
-# creating a new one when `process` is called. A client connection and a block
-# are passed to the worker thread for it to handle the connection. Once it's
-# done handling the thread, the connection is closed and the thread is removed
-# from the list. This iignals some of the other methods that the workers class
-# provides that wait on threads to finish.
-#
-require 'thread'
-
-require 'dat-tcp/logger'
-
-module DatTCP
-
-  class Workers
-    attr_reader :max, :list, :logger
-
-    def initialize(max = 1, logger = nil)
-      @max = max
-      @logger = logger || DatTCP::Logger::Null.new
-      @list = []
-
-      @mutex = Mutex.new
-      @condition_variable = ConditionVariable.new
-    end
-
-    # This uses the mutex and condition variable to sleep the current thread
-    # until signaled. When a thread closes down, it signals, causing this thread
-    # to wakeup. This will run the loop again, and as long as a worker is
-    # available, the method will return. Otherwise it will sleep again waiting
-    # to be signaled.
-    def wait_for_available
-      @mutex.synchronize do
-        while self.list.size >= self.max
-          @condition_variable.wait(@mutex)
-        end
-      end
-    end
-
-    def process(connecting_socket, &block)
-      self.wait_for_available
-      worker_id = self.list.size + 1
-      @list << Thread.new{ self.serve_client(worker_id, connecting_socket, &block) }
-    end
-
-    # Finish simply sleeps the current thread until signaled. Again, when a
-    # worker thread closes down, it signals. This will cause this to wake up and
-    # continue running the loop. Once the list is empty, the method will return.
-    # Otherwise this will sleep until signaled again. This is a graceful
-    # shutdown, letting the threads finish their processing.
-    def finish
-      @mutex.synchronize do
-        @list.reject!{|thread| !thread.alive? }
-        while !self.list.empty?
-          @condition_variable.wait(@mutex)
-        end
-      end
-    end
-
-    protected
-
-    def log(message, worker_id)
-      self.logger.info("[Worker##{worker_id}] #{message}") if self.logger
-    end
-
-    def serve_client(worker_id, connecting_socket, &block)
-      begin
-        Thread.current["client_address"] = connecting_socket.peeraddr[1, 2].reverse.join(':')
-        self.log("Connecting #{Thread.current["client_address"]}", worker_id)
-        block.call(connecting_socket)
-      rescue Exception => exception
-        self.log("Exception occurred, stopping worker", worker_id)
-      ensure
-        self.disconnect_client(worker_id, connecting_socket, exception)
-      end
-    end
-
-    # Closes the client connection and also shuts the thread down. This is done
-    # by removing the thread from the list. This is wrapped in a mutex
-    # synchronize, to ensure only one thread interacts with list at a time. Also
-    # the condition variable is signaled to trigger the `finish` or
-    # `wait_for_available` methods.
-    def disconnect_client(worker_id, connecting_socket, exception)
-      connecting_socket.close rescue false
-      @mutex.synchronize do
-        @list.delete(Thread.current)
-        @condition_variable.signal
-      end
-      if exception
-        self.log("#{exception.class}: #{exception.message}", worker_id)
-        self.log(exception.backtrace.join("\n"), worker_id)
-      end
-      self.log("Disconnecting #{Thread.current["client_address"]}", worker_id)
-    end
-
-  end
-
-end