ruby-changes:19555
From: drbrain <ko1@a...>
Date: Tue, 17 May 2011 06:31:19 +0900 (JST)
Subject: [ruby-changes:19555] drbrain:r31596 (trunk): * lib/gserver.rb: Improve documentation. Patch by David Copeland.
drbrain 2011-05-17 06:31:06 +0900 (Tue, 17 May 2011) New Revision: 31596 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=31596 Log: * lib/gserver.rb: Improve documentation. Patch by David Copeland. [Ruby 1.9 - Bug #4705] Modified files: trunk/ChangeLog trunk/lib/gserver.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 31595) +++ ChangeLog (revision 31596) @@ -1,3 +1,8 @@ +Tue May 17 06:28:14 2011 Eric Hodel <drbrain@s...> + + * lib/gserver.rb: Improve documentation. Patch by David Copeland. + [Ruby 1.9 - Bug #4705] + Tue May 17 06:21:15 2011 Eric Hodel <drbrain@s...> * lib/cgi.rb: Add toplevel documentation to class CGI Index: lib/gserver.rb =================================================================== --- lib/gserver.rb (revision 31595) +++ lib/gserver.rb (revision 31596) @@ -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 @@ @@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 @@ } 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 @@ 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 @@ 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 @@ 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 @@ @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 { -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/