rubysl-gserver 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b59a46b0c246f54cb0d7b5e2cf785afc32e39a31
-  data.tar.gz: 4fd286c7d23568841c76702b13b8240ee0a8c998
+  metadata.gz: c66e019aa38de4678577becb51ea434ed86eb284
+  data.tar.gz: 4566b0d3787f35db9a222ea6d8e94860881fef1f
 SHA512:
-  metadata.gz: d3138998f198e787b8bfed1d5ecaf987ffd43642b7593c73681e6c0e8f8ae7700f246a9793fedde42252234f719734e164e7b94ac27909d135ad1211479e32f3
-  data.tar.gz: 41909ba24a7494f19c47172dca23aed0ff807b5a9074b8e1faec8d060f0cccae3e10a85f01694ae11f3375d5805b336f32dd7e6d3f696b59d1c3545cbf41f5a4
+  metadata.gz: 1121d30580a3695fb79ac3d6019502edb23ed7cef3fb810d727f09069abe17cff1e1a2e6832506aa70708f3d242671e766671d3592975dace394b7f7831e0ac1
+  data.tar.gz: 6a327e9484af7eeff55cfb874e320be054d5757272fb1747a2974c8dc8de4c5424dda6c9109f893419a3c7e3469e6cf58878e477bbc548586ee8a81afdc2ce6b

data/.travis.yml

@@ -1,8 +1,7 @@
 language: ruby
-before_install:
-  - gem update --system
-  - gem --version
-  - gem install rubysl-bundler
-script: bundle exec mspec spec
+env:
+  - RUBYLIB=lib
+script: bundle exec mspec
 rvm:
-  - rbx-nightly-18mode
+  - 1.9.3
+  - rbx-nightly-19mode

data/lib/rubysl/gserver/gserver.rb

@@ -4,16 +4,13 @@
 # Author::        John W. Small
 # Documentation:: Gavin Sinclair
 # Licence::       Freeware.
-#
-# See the class GServer for documentation.
-#
 
 require "socket"
 require "thread"
 
 #
 # GServer implements a generic server, featuring thread pool management,
-# simple logging, and multi-server management.  See HttpServer in 
+# simple logging, and multi-server management.  See HttpServer in
 # <tt>xmlrpc/httpserver.rb</tt> in the Ruby standard library for an example of
 # GServer in action.
 #
@@ -25,7 +22,7 @@ require "thread"
 # you the effort.  All events are optionally logged, but you can provide your
 # own event handlers if you wish.
 #
-# === Example
+# == Example
 #
 # Using GServer is simple.  Below we implement a simple time server, run it,
 # query it, and shut it down.  Try this code in +irb+:
@@ -34,30 +31,30 @@ require "thread"
 #
 #   #
 #   # A server that returns the time in seconds since 1970.
-#   # 
+#   #
 #   class TimeServer < GServer
 #     def initialize(port=10001, *args)
 #       super(port, *args)
 #     end
 #     def serve(io)
-#       io.puts(Time.now.to_i)
+#       io.puts(Time.now.to_s)
 #     end
 #   end
 #
 #   # Run the server with logging enabled (it's a separate thread).
 #   server = TimeServer.new
 #   server.audit = true                  # Turn logging on.
-#   server.start 
+#   server.start
 #
 #   # *** Now point your browser to http://localhost:10001 to see it working ***
 #
-#   # See if it's still running. 
+#   # See if it's still running.
 #   GServer.in_service?(10001)           # -> true
 #   server.stopped?                      # -> false
 #
 #   # Shut the server down gracefully.
 #   server.shutdown
-#   
+#
 #   # Alternatively, stop it immediately.
 #   GServer.stop(10001)
 #   # or, of course, "server.stop".
@@ -73,14 +70,14 @@ require "thread"
 # other methods as well if you wish, perhaps to collect statistics, or emit
 # more detailed logging.
 #
-#   connecting
-#   disconnecting
-#   starting
-#   stopping
+# * #connecting
+# * #disconnecting
+# * #starting
+# * #stopping
 #
-# The above methods are only called if auditing is enabled.
+# The above methods are only called if auditing is enabled, via #audit=.
 #
-# You can also override +log+ and +error+ if, for example, you wish to use a
+# You can also override #log and #error if, for example, you wish to use a
 # more sophisticated logging system.
 #
 class GServer
@@ -93,17 +90,28 @@ class GServer
   @@services = {}   # Hash of opened ports, i.e. services
   @@servicesMutex = Mutex.new
 
+  # Stop the server running on the given port, bound to the given host
+  #
+  # +port+:: port, as a FixNum, of the server to stop
+  # +host+:: host on which to find the server to stop
   def GServer.stop(port, host = DEFAULT_HOST)
     @@servicesMutex.synchronize {
       @@services[host][port].stop
     }
   end
 
+  # Check if a server is running on the given port and host
+  #
+  # +port+:: port, as a FixNum, of the server to check
+  # +host+:: host on which to find the server to check
+  #
+  # Returns true if a server is running on that port and host.
   def GServer.in_service?(port, host = DEFAULT_HOST)
     @@services.has_key?(host) and
       @@services[host].has_key?(port)
   end
 
+  # Stop the server
   def stop
     @connectionsMutex.synchronize  {
       if @tcpServerThread
@@ -112,25 +120,45 @@ class GServer
     }
   end
 
+  # Returns true if the server has stopped.
   def stopped?
     @tcpServerThread == nil
   end
 
+  # Schedule a shutdown for the server
   def shutdown
     @shutdown = true
   end
 
+  # Return the current number of connected clients
   def connections
     @connections.size
   end
 
+  # Join with the server thread
   def join
     @tcpServerThread.join if @tcpServerThread
   end
 
-  attr_reader :port, :host, :maxConnections
-  attr_accessor :stdlog, :audit, :debug
+  # Port on which to listen, as a FixNum
+  attr_reader :port
+  # Host on which to bind, as a String
+  attr_reader :host
+  # Maximum number of connections to accept at at ime, as a FixNum
+  attr_reader :maxConnections
+  # IO Device on which log messages should be written
+  attr_accessor :stdlog
+  # Set to true to cause the callbacks #connecting, #disconnecting, #starting,
+  # and #stopping to be called during the server's lifecycle
+  attr_accessor :audit
+  # Set to true to show more detailed logging
+  attr_accessor :debug
 
+  # Called when a client connects, if auditing is enabled.
+  #
+  # +client+:: a TCPSocket instances representing the client that connected
+  #
+  # Return true to allow this client to connect, false to prevent it.
   def connecting(client)
     addr = client.peeraddr
     log("#{self.class.to_s} #{@host}:#{@port} client:#{addr[1]} " +
@@ -138,6 +166,10 @@ class GServer
     true
   end
 
+
+  # Called when a client disconnects, if audition is enabled.
+  #
+  # +clientPort+:: the port of the client that is connecting
   def disconnecting(clientPort)
     log("#{self.class.to_s} #{@host}:#{@port} " +
       "client:#{clientPort} disconnect")
@@ -145,20 +177,30 @@ class GServer
 
   protected :connecting, :disconnecting
 
+  # Called when the server is starting up, if auditing is enabled.
   def starting()
     log("#{self.class.to_s} #{@host}:#{@port} start")
   end
 
+  # Called when the server is shutting down, if auditing is enabled.
   def stopping()
     log("#{self.class.to_s} #{@host}:#{@port} stop")
   end
 
   protected :starting, :stopping
 
+  # Called if #debug is true whenever an unhandled exception is raised.
+  # This implementation simply logs the backtrace.
+  #
+  # +detail+:: The Exception that was caught
   def error(detail)
     log(detail.backtrace.join("\n"))
   end
 
+  # Log a message to #stdlog, if it's defined.  This implementation
+  # outputs the timestamp and message to the log.
+  #
+  # +msg+:: the message to log
   def log(msg)
     if @stdlog
       @stdlog.puts("[#{Time.new.ctime}] %s" % msg)
@@ -168,6 +210,15 @@ class GServer
 
   protected :error, :log
 
+  # Create a new server
+  #
+  # +port+:: the port, as a FixNum, on which to listen.
+  # +host+:: the host to bind to
+  # +maxConnections+:: The maximum number of simultaneous connections to
+  #                    accept
+  # +stdlog+:: IO device on which to log messages
+  # +audit+:: if true, lifecycle callbacks will be called.  See #audit
+  # +debug+:: if true, error messages are logged.  See #debug
   def initialize(port, host = DEFAULT_HOST, maxConnections = 4,
     stdlog = $stderr, audit = false, debug = false)
     @tcpServerThread = nil
@@ -182,8 +233,13 @@ class GServer
     @debug = debug
   end
 
+  # Start the server if it isn't already running
+  #
+  # +maxConnections+::
+  #   override +maxConnections+ given to the constructor.  A negative
+  #   value indicates that the value from the constructor should be used.
   def start(maxConnections = -1)
-    raise "running" if !stopped?
+    raise "server is already running" if !stopped?
     @shutdown = false
     @maxConnections = maxConnections if maxConnections > 0
     @@servicesMutex.synchronize  {
@@ -205,7 +261,8 @@ class GServer
              end
           }
           client = @tcpServer.accept
-          @connections << Thread.new(client)  { |myClient|
+          Thread.new(client)  { |myClient|
+            @connections << Thread.current
             begin
               myPort = myClient.peeraddr[1]
               serve(myClient) if !@audit or connecting(myClient)

data/lib/rubysl/gserver/version.rb

@@ -1,5 +1,5 @@
 module RubySL
   module GServer
-    VERSION = "1.0.0"
+    VERSION = "2.0.0"
   end
 end

data/rubysl-gserver.gemspec

@@ -16,11 +16,10 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "rubysl-socket", "~> 1.0"
-  spec.add_runtime_dependency "rubysl-thread", "~> 1.0"
+  spec.add_runtime_dependency "rubysl-socket", "~> 2.0"
+  spec.add_runtime_dependency "rubysl-thread", "~> 2.0"
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "mspec", "~> 1.5"
-  spec.add_development_dependency "rubysl-prettyprint", "~> 1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubysl-gserver
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Brian Shirai
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-26 00:00:00.000000000 Z
+date: 2013-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubysl-socket
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rubysl-thread
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -80,20 +80,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.5'
-- !ruby/object:Gem::Dependency
-  name: rubysl-prettyprint
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.0'
 description: Ruby standard library gserver.
 email:
 - brixen@gmail.com