Permalink
Browse files

* lib/gserver.rb: Improve documentation. Patch by David Copeland.

	  [Ruby 1.9 - Bug #4705]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31596 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
  • Loading branch information...
1 parent e60f744 commit 28c2fa2fdb56abb6960ee40b9364706059f0ea65 @drbrain drbrain committed May 16, 2011
Showing with 74 additions and 13 deletions.
  1. +5 −0 ChangeLog
  2. +69 −13 lib/gserver.rb
View
@@ -1,3 +1,8 @@
+Tue May 17 06:28:14 2011 Eric Hodel <drbrain@segment7.net>
+
+ * lib/gserver.rb: Improve documentation. Patch by David Copeland.
+ [Ruby 1.9 - Bug #4705]
+
Tue May 17 06:21:15 2011 Eric Hodel <drbrain@segment7.net>
* lib/cgi.rb: Add toplevel documentation to class CGI
View
@@ -4,9 +4,6 @@
# Author:: John W. Small
# Documentation:: Gavin Sinclair
# Licence:: Freeware.
-#
-# See the class GServer for documentation.
-#
require "socket"
require "thread"
@@ -25,7 +22,7 @@
# 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+:
@@ -73,14 +70,14 @@
# 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 @@ def serve(io)
@@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,53 +120,87 @@ def stop
}
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]} " +
"#{addr[2]}<#{addr[3]}> connect")
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")
end
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 @@ def log(msg)
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 @@ def initialize(port, host = DEFAULT_HOST, maxConnections = 4,
@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 {

0 comments on commit 28c2fa2

Please sign in to comment.