Class | GServer
In: | gserver.rb
Parent: | Object

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

### Methods

connections in_service? join new serve shutdown start stop stop stopped?

### Constants

DEFAULT_HOST | = | "127.0.0.1"

### Attributes

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

### Public Class methods

in_service?(port, host = DEFAULT_HOST)

[Source]

    # File gserver.rb, line 98
      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)

[Source]

    # File gserver.rb, line 167
      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)

[Source]

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

### Public Instance methods

connections()

[Source]

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

join()

[Source]

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

serve(io)

[Source]

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

shutdown()

[Source]

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

start(maxConnections = -1)

[Source]

    # File gserver.rb, line 181
      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()

[Source]

    # File gserver.rb, line 103
      def stop
        @connectionsMutex.synchronize  {
          if @tcpServerThread
            @tcpServerThread.raise "stop"
          end
        }
      end

stopped?()

[Source]

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

[Validate]