Class

GServer

In:

Parent:

GServer implements a generic server, featuring thread pool management, simple logging, and multi-server 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.

Methods

connecting connections disconnecting error in_service? join log new serve shutdown start starting stop stop stopped? stopping

Constants

DEFAULT_HOST = "127.0.0.1"

Attributes

 audit
 debug
 host
 maxConnections
 port
 stdlog

Public Class methods

in_service?(port, host = DEFAULT_HOST)

     # File gserver.rb, line 98
 98:   def GServer.in_service?(port, host = DEFAULT_HOST)
 99:     @@services.has_key?(host) and
100:       @@services[host].has_key?(port)
101:   end

new(port, host = DEFAULT_HOST, maxConnections = 4, stdlog = $stderr, audit = false, debug = false)

     # File gserver.rb, line 167
167:   def initialize(port, host = DEFAULT_HOST, maxConnections = 4,
168:     stdlog = $stderr, audit = false, debug = false)
169:     @tcpServerThread = nil
170:     @port = port
171:     @host = host
172:     @maxConnections = maxConnections
173:     @connections = []
174:     @connectionsMutex = Mutex.new
175:     @connectionsCV = ConditionVariable.new
176:     @stdlog = stdlog
177:     @audit = audit
178:     @debug = debug
179:   end

stop(port, host = DEFAULT_HOST)

    # File gserver.rb, line 92
92:   def GServer.stop(port, host = DEFAULT_HOST)
93:     @@servicesMutex.synchronize {
94:       @@services[host][port].stop
95:     }
96:   end

Public Instance methods

     # File gserver.rb, line 119
119:   def connections
120:     @connections.size
121:   end

     # File gserver.rb, line 123
123:   def join
124:     @tcpServerThread.join if @tcpServerThread
125:   end

    # File gserver.rb, line 86
86:   def serve(io)
87:   end

     # File gserver.rb, line 115
115:   def shutdown
116:     @shutdown = true
117:   end

start(maxConnections = -1)

     # File gserver.rb, line 181
181:   def start(maxConnections = -1)
182:     raise "running" if !stopped?
183:     @shutdown = false
184:     @maxConnections = maxConnections if maxConnections > 0
185:     @@servicesMutex.synchronize  {
186:       if GServer.in_service?(@port,@host)
187:         raise "Port already in use: #{host}:#{@port}!"
188:       end
189:       @tcpServer = TCPServer.new(@host,@port)
190:       @port = @tcpServer.addr[1]
191:       @@services[@host] = {} unless @@services.has_key?(@host)
192:       @@services[@host][@port] = self;
193:     }
194:     @tcpServerThread = Thread.new {
195:       begin
196:         starting if @audit
197:         while !@shutdown
198:           @connectionsMutex.synchronize  {
199:              while @connections.size >= @maxConnections
200:                @connectionsCV.wait(@connectionsMutex)
201:              end
202:           }
203:           client = @tcpServer.accept
204:           @connections << Thread.new(client)  { |myClient|
205:             begin
206:               myPort = myClient.peeraddr[1]
207:               serve(myClient) if !@audit or connecting(myClient)
208:             rescue => detail
209:               error(detail) if @debug
210:             ensure
211:               begin
212:                 myClient.close
213:               rescue
214:               end
215:               @connectionsMutex.synchronize {
216:                 @connections.delete(Thread.current)
217:                 @connectionsCV.signal
218:               }
219:               disconnecting(myPort) if @audit
220:             end
221:           }
222:         end
223:       rescue => detail
224:         error(detail) if @debug
225:       ensure
226:         begin
227:           @tcpServer.close
228:         rescue
229:         end
230:         if @shutdown
231:           @connectionsMutex.synchronize  {
232:              while @connections.size > 0
233:                @connectionsCV.wait(@connectionsMutex)
234:              end
235:           }
236:         else
237:           @connections.each { |c| c.raise "stop" }
238:         end
239:         @tcpServerThread = nil
240:         @@servicesMutex.synchronize  {
241:           @@services[@host].delete(@port)
242:         }
243:         stopping if @audit
244:       end
245:     }
246:     self
247:   end

     # File gserver.rb, line 103
103:   def stop
104:     @connectionsMutex.synchronize  {
105:       if @tcpServerThread
106:         @tcpServerThread.raise "stop"
107:       end
108:     }
109:   end

     # File gserver.rb, line 111
111:   def stopped?
112:     @tcpServerThread == nil
113:   end

Protected Instance methods

connecting(client)

     # File gserver.rb, line 130
130:   def connecting(client)
131:     addr = client.peeraddr
132:     log("#{self.class.to_s} #{@host}:#{@port} client:#{addr[1]} " +
133:         "#{addr[2]}<#{addr[3]}> connect")
134:     true
135:   end

disconnecting(clientPort)

     # File gserver.rb, line 137
137:   def disconnecting(clientPort)
138:     log("#{self.class.to_s} #{@host}:#{@port} " +
139:       "client:#{clientPort} disconnect")
140:   end

     # File gserver.rb, line 154
154:   def error(detail)
155:     log(detail.backtrace.join("\n"))
156:   end

     # File gserver.rb, line 158
158:   def log(msg)
159:     if @stdlog
160:       @stdlog.puts("[#{Time.new.ctime}] %s" % msg)
161:       @stdlog.flush
162:     end
163:   end

     # File gserver.rb, line 144
144:   def starting()
145:     log("#{self.class.to_s} #{@host}:#{@port} start")
146:   end

     # File gserver.rb, line 148
148:   def stopping()
149:     log("#{self.class.to_s} #{@host}:#{@port} stop")
150:   end

Search

Ruby API Docs

Links