Extended maintenance of Ruby versions 1.8.7 and 1.9.2 ended on July 31, 2014. Read more

In Files

  • gserver.rb

Class/Module Index [+]

Quicksearch

GServer

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_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.

Constants

DEFAULT_HOST

Attributes

audit[RW]
debug[RW]
host[R]
maxConnections[R]
port[R]
stdlog[RW]

Public Class Methods

in_service?(port, host = DEFAULT_HOST) click to toggle source
 
               # File gserver.rb, line 102
def GServer.in_service?(port, host = DEFAULT_HOST)
  @@services.has_key?(host) and
    @@services[host].has_key?(port)
end
            
new(port, host = DEFAULT_HOST, maxConnections = 4, stdlog = $stderr, audit = false, debug = false) click to toggle source
 
               # File 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
            
stop(port, host = DEFAULT_HOST) click to toggle source
 
               # File gserver.rb, line 96
def GServer.stop(port, host = DEFAULT_HOST)
  @@servicesMutex.synchronize {
    @@services[host][port].stop
  }
end
            

Public Instance Methods

connections() click to toggle source
 
               # File gserver.rb, line 123
def connections
  @connections.size
end
            
join() click to toggle source
 
               # File gserver.rb, line 127
def join
  @tcpServerThread.join if @tcpServerThread
end
            
serve(io) click to toggle source
 
               # File gserver.rb, line 90
def serve(io)
end
            
shutdown() click to toggle source
 
               # File gserver.rb, line 119
def shutdown
  @shutdown = true
end
            
start(maxConnections = -1) click to toggle source
 
               # File 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
            
stop() click to toggle source
 
               # File gserver.rb, line 107
def stop
  @connectionsMutex.synchronize  {
    if @tcpServerThread
      @tcpServerThread.raise "stop"
    end
  }
end
            
stopped?() click to toggle source
 
               # File gserver.rb, line 115
def stopped?
  @tcpServerThread == nil
end
            

Protected Instance Methods

connecting(client) click to toggle source
 
               # File gserver.rb, line 134
def connecting(client)
  addr = client.peeraddr
  log("#{self.class.to_s} #{@host}:#{@port} client:#{addr[1]} " +
      "#{addr[2]}<#{addr[3]}> connect")
  true
end
            
disconnecting(clientPort) click to toggle source
 
               # File gserver.rb, line 141
def disconnecting(clientPort)
  log("#{self.class.to_s} #{@host}:#{@port} " +
    "client:#{clientPort} disconnect")
end
            
error(detail) click to toggle source
 
               # File gserver.rb, line 158
def error(detail)
  log(detail.backtrace.join("\n"))
end
            
log(msg) click to toggle source
 
               # File gserver.rb, line 162
def log(msg)
  if @stdlog
    @stdlog.puts("[#{Time.new.ctime}] %s" % msg)
    @stdlog.flush
  end
end
            
starting() click to toggle source
 
               # File gserver.rb, line 148
def starting()
  log("#{self.class.to_s} #{@host}:#{@port} start")
end
            
stopping() click to toggle source
 
               # File gserver.rb, line 152
def stopping()
  log("#{self.class.to_s} #{@host}:#{@port} stop")
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus