* 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

2 files changed, 107 insertions, 2 deletions

diff --git a/lib/gserver.rb b/lib/gserver.rb
index 14f765a90c..371fceb290 100644
--- a/lib/gserver.rb
+++ b/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"
diff --git a/lib/xmlrpc/README.txt b/lib/xmlrpc/README.txt
new file mode 100644
index 0000000000..ade842d8b1
--- /dev/null
+++ b/lib/xmlrpc/README.txt
@@ -0,0 +1,31 @@
+= XMLRPC for Ruby, Standard Library Documentation
+
+== Overview
+
+XMLRPC is a lightweight protocol that enables remote procedure calls over
+HTTP.  It is defined at http://www.xmlrpc.com.
+
+XMLRPC allows you to create simple distributed computing solutions that span
+computer languages.  Its distinctive feature is its simplicity compared to
+other approaches like SOAP and CORBA.
+
+The Ruby standard library package 'xmlrpc' enables you to create a server that
+implements remote procedures and a client that calls them.  Very little code
+is required to achieve either of these.
+
+== Example
+
+Try the following code.  It calls a standard demonstration remote procedure.
+
+  require 'xmlrpc/client'
+  require 'pp'
+
+  server = XMLRPC::Client.new2("http://xmlrpc-c.sourceforge.net/api/sample.php")
+  result = server.call("sample.sumAndDifference", 5, 3)
+  pp result
+
+== Documentation
+
+See http://www.ntecs.de/projects/xmlrpc4r.  There is plenty of detail there to
+use the client and implement a server.
+