From 33a233ab9c3794ee93539d34517df01b2839f8eb Mon Sep 17 00:00:00 2001 From: gsinclair Date: Tue, 4 May 2004 14:54:59 +0000 Subject: * lib/gserver.rb: documented git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@6244 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 4 +++ lib/gserver.rb | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 80 insertions(+), 2 deletions(-) diff --git a/ChangeLog b/ChangeLog index ac720665ed..fb33a0886a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Tue May 4 23:52:00 2004 Gavin Sinclair + + * lib/gserver.rb: documented + Tue May 4 23:46:00 2004 Gavin Sinclair * lib/xmlrpc/README.txt: introduced for documentation purposes 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 xmlrpc/httpserver.rb 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 GServer.stop(port). 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" -- cgit v1.2.3