summaryrefslogtreecommitdiff
path: root/lib/gserver.rb
diff options
context:
space:
mode:
authorgsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2004-05-04 14:54:59 +0000
committergsinclair <gsinclair@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2004-05-04 14:54:59 +0000
commit33a233ab9c3794ee93539d34517df01b2839f8eb (patch)
tree336f13389172c6eff50a02eda0e464bfd327aa63 /lib/gserver.rb
parent36e4f2fcf104ddc58e4c617a86cc37d9f540216d (diff)
* lib/gserver.rb: documented
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@6244 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/gserver.rb')
-rw-r--r--lib/gserver.rb78
1 files changed, 76 insertions, 2 deletions
diff --git a/lib/gserver.rb b/lib/gserver.rb
index 14f765a..371fceb 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"