Class: GServer

Inherits:
Object show all
Defined in:
lib/gserver.rb

Overview

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

Constant Summary

DEFAULT_HOST = 
"127.0.0.1"
@@services =

Hash of opened ports, i.e. services

{}
@@servicesMutex = 
Mutex.new

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (GServer) initialize(port, host = DEFAULT_HOST, maxConnections = 4, stdlog = $stderr, audit = false, debug = false)

A new instance of GServer



171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/gserver.rb', line 171

def initialize(port, host = DEFAULT_HOST, maxConnections = 4,
  stdlog = $stderr, audit = false, debug = false)
  @tcpServerThread = nil
  @port = port
  @host = host
  @maxConnections = maxConnections
  @connections = []
  @connectionsMutex = Mutex.new
  @connectionsCV = ConditionVariable.new
  @stdlog = stdlog
  @audit = audit
  @debug = debug
end

Instance Attribute Details

- (Object) audit

Returns the value of attribute audit



132
133
134
 
# File 'lib/gserver.rb', line 132

def audit
  @audit
end

- (Object) debug

Returns the value of attribute debug



132
133
134
 
# File 'lib/gserver.rb', line 132

def debug
  @debug
end

- (Object) host (readonly)

Returns the value of attribute host



131
132
133
 
# File 'lib/gserver.rb', line 131

def host
  @host
end

- (Object) maxConnections (readonly)

Returns the value of attribute maxConnections



131
132
133
 
# File 'lib/gserver.rb', line 131

def maxConnections
  @maxConnections
end

- (Object) port (readonly)

Returns the value of attribute port



131
132
133
 
# File 'lib/gserver.rb', line 131

def port
  @port
end

- (Object) stdlog

Returns the value of attribute stdlog



132
133
134
 
# File 'lib/gserver.rb', line 132

def stdlog
  @stdlog
end

Class Method Details

+ (Boolean) in_service?(port, host = DEFAULT_HOST)

Returns:

  • (Boolean) 


102
103
104
105
 
# File 'lib/gserver.rb', line 102

def GServer.in_service?(port, host = DEFAULT_HOST)
  @@services.has_key?(host) and
    @@services[host].has_key?(port)
end

+ (Object) stop(port, host = DEFAULT_HOST) 



96
97
98
99
100
 
# File 'lib/gserver.rb', line 96

def GServer.stop(port, host = DEFAULT_HOST)
  @@servicesMutex.synchronize {
    @@services[host][port].stop
  }
end

Instance Method Details

- (Object) connections 



123
124
125
 
# File 'lib/gserver.rb', line 123

def connections
  @connections.size
end

- (Object) join 



127
128
129
 
# File 'lib/gserver.rb', line 127

def join
  @tcpServerThread.join if @tcpServerThread
end

- (Object) serve(io) 



90
91
 
# File 'lib/gserver.rb', line 90

def serve(io)
end

- (Object) shutdown 



119
120
121
 
# File 'lib/gserver.rb', line 119

def shutdown
  @shutdown = true
end

- (Object) start(maxConnections = 1) 



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/gserver.rb', line 185

def start(maxConnections = -1)
  raise "running" if !stopped?
  @shutdown = false
  @maxConnections = maxConnections if maxConnections > 0
  @@servicesMutex.synchronize  {
    if GServer.in_service?(@port,@host)
      raise "Port already in use: #{host}:#{@port}!"
    end
    @tcpServer = TCPServer.new(@host,@port)
    @port = @tcpServer.addr[1]
    @@services[@host] = {} unless @@services.has_key?(@host)
    @@services[@host][@port] = self;
  }
  @tcpServerThread = Thread.new {
    begin
      starting if @audit
      while !@shutdown
        @connectionsMutex.synchronize  {
           while @connections.size >= @maxConnections
             @connectionsCV.wait(@connectionsMutex)
           end
        }
        client = @tcpServer.accept
        @connections << Thread.new(client)  { |myClient|
          begin
            myPort = myClient.peeraddr[1]
            serve(myClient) if !@audit or connecting(myClient)
          rescue => detail
            error(detail) if @debug
          ensure
            begin
              myClient.close
            rescue
            end
            @connectionsMutex.synchronize {
              @connections.delete(Thread.current)
              @connectionsCV.signal
            }
            disconnecting(myPort) if @audit
          end
        }
      end
    rescue => detail
      error(detail) if @debug
    ensure
      begin
        @tcpServer.close
      rescue
      end
      if @shutdown
        @connectionsMutex.synchronize  {
           while @connections.size > 0
             @connectionsCV.wait(@connectionsMutex)
           end
        }
      else
        @connections.each { |c| c.raise "stop" }
      end
      @tcpServerThread = nil
      @@servicesMutex.synchronize  {
        @@services[@host].delete(@port)
      }
      stopping if @audit
    end
  }
  self
end

- (Object) stop 



107
108
109
110
111
112
113
 
# File 'lib/gserver.rb', line 107

def stop
  @connectionsMutex.synchronize  {
    if @tcpServerThread
      @tcpServerThread.raise "stop"
    end
  }
end

- (Boolean) stopped?

Returns:

  • (Boolean) 


115
116
117
 
# File 'lib/gserver.rb', line 115

def stopped?
  @tcpServerThread == nil
end