* lib/gserver.rb: documented

* lib/xmlrpc/README.txt: introduced for documentation purposes


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@6245 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

lib/gserver.rb

@@ -1,10 +1,84 @@
+#
 # Copyright (C) 2001 John W. Small All Rights Reserved
-# mailto:jsmall@laser.net  subject:ruby-generic-server
-# Freeware
+#
+# 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 <tt>xmlrpc/httpserver.rb</tt> in the Ruby standard library for
+# an example of +GServer+ in action.
+#
+# Any kind of application-level server can be implemented using this class.  It accepts
+# multiple simultaneous connections from clients, up to an optional maximum number.  Several
+# _services_ (i.e. one service per TCP port) can be run simultaneously, and stopped at any time
+# through the class method <tt>GServer.stop(port)</tt>.  All the threading issues are handled,
+# saving you the effort.  All events are optionally logged, but you can provide your own event
+# handlers if you wish.
+#
+# === 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+:
+#
+#   require 'gserver'
+#
+#   #
+#   # 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)
+#     end
+#   end
+#
+#   # Run the server with logging enabled (it's a separate thread).
+#   server = TimeServer.new
+#   server.audit = true                  # Turn logging on.
+#   server.start 
+#
+#   # *** Now point your browser to http://localhost:10001 to see it working ***
+#
+#   # 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".
+#
+# All the business of accepting connections and exception handling is taken care of.  All we
+# have to do is implement the method that actually serves the client.
+#
+# === Advanced
+#
+# As the example above shows, the way to use +GServer+ is to subclass it to create a specific
+# server, overriding the +serve+ method.  You can override other methods as well if you wish,
+# perhaps to collect statistics, or emit more detailed logging.
+#
+#   connecting
+#   disconnecting
+#   starting
+#   stopping
+#
+# The above methods are only called if auditing is enabled.
+#
+# You can also override +log+ and +error+ if, for example, you wish to use a more sophisticated
+# logging system.
+#
 class GServer
 
   DEFAULT_HOST = "127.0.0.1"