Class | PhusionPassenger::AbstractServer
In: | lib/phusion_passenger/abstract_server.rb
Parent: | Object

An abstract base class for a server that has the following properties:

- The server listens on a password protected Unix socket.
- The server is multithreaded and handles one client per thread.
- The server is owned by one or more processes. If all processes close their reference to the server, then the server will quit.
- The server‘s main loop may be run in a child process (and so is asynchronous from the parent process).
- One can communicate with the server through discrete MessageChannel messages, as opposed to byte streams.
- The server can pass file descriptors (IO objects) back to the client.

The server will also reset all signal handlers. That is, it will respond to all signals in the default manner. The only exception is SIGHUP, which is ignored. One may define additional signal handlers using define_signal_handler().

Before an AbstractServer can be used, it must first be started by calling start(). When it is no longer needed, stop() should be called.

Here‘s an example on using AbstractServer:

     class MyServer < PhusionPassenger::AbstractServer
        def initialize
           super()
           define_message_handler(:hello, :handle_hello)
        end

        def hello(first_name, last_name)
           connect do |channel|
              channel.write('hello', first_name, last_name)
              reply, pointless_number = channel.read
              puts "The server said: #{reply}"
              puts "In addition, it sent this pointless number: #{pointless_number}"
           end
        end

     private
        def handle_hello(channel, first_name, last_name)
           channel.write("Hello #{first_name} #{last_name}, how are you?", 1234)
        end
     end

     server = MyServer.new
     server.start
     server.hello("Joe", "Dalton")
     server.stop

### Methods

before_fork connect define_message_handler define_signal_handler fileno_of finalize_server initialize_server new server_pid start start_synchronously started? stop

### Included Modules

Utils

### Classes and Modules

Class PhusionPassenger::AbstractServer::InvalidPassword
Class PhusionPassenger::AbstractServer::ServerAlreadyStarted
Class PhusionPassenger::AbstractServer::ServerError
Class PhusionPassenger::AbstractServer::ServerNotStarted
Class PhusionPassenger::AbstractServer::UnknownMessage

### Attributes

ignore_password_errors | [RW] |
max_idle_time | [RW] | The maximum time that this AbstractServer may be idle. Used by AbstractServerCollection to determine when this object should be cleaned up. nil or 0 indicate that this object should never be idle cleaned.
next_cleaning_time | [RW] | Used by AbstractServerCollection to remember when this AbstractServer should be idle cleaned.
password | [R] |

### Public Class methods

new(socket_filename = nil, password = nil)

### Public Instance methods

connect() {|channel| ...}

Connects to the server and yields a channel for communication. The first message‘s name must match a handler name. The connection can only be used for a single handler cycle; after the handler is done, the connection will be closed.

      server.connect do |channel|
         channel.write("a message")
         ...
      end

Raises: SystemCallError, IOError, SocketError

server_pid()

Return the PID of the started server. This is only valid if start has been called.

start()

Start the server. This method does not block since the server runs asynchronously from the current process.

You may only call this method if the server is not already started. Otherwise, a ServerAlreadyStarted will be raised.

Derived classes may raise additional exceptions.

start_synchronously(socket_filename, password, server_socket, owner_socket)

Start the server, but in the current process instead of in a child process. This method blocks until the server‘s main loop has ended.

All hooks will be called, except before_fork().

started?()

Return whether the server has been started.

stop()

Stop the server. The server will quit as soon as possible. This method waits until the server has been stopped.

When calling this method, the server must already be started. If not, a ServerNotStarted will be raised.

### Protected Instance methods

before_fork()

A hook which is called when the server is being started, just before forking a new process. The default implementation does nothing, this method is supposed to be overrided by child classes.

define_message_handler(message_name, handler)

Define a handler for a message. message_name is the name of the message to handle, and handler is the name of a method to be called (this may either be a String or a Symbol).

A message is just a list of strings, and so handler will be called with the message as its arguments, excluding the first element. See also the example in the class description.

define_signal_handler(signal, handler)

Define a handler for a signal.

fileno_of(io)
finalize_server()

A hook which is called when the server is being stopped. This is called in the child process, after the main loop has been left. The default implementation does nothing, this method is supposed to be overrided by child classes.

initialize_server()

A hook which is called when the server is being started. This is called in the child process, before the main loop is entered. The default implementation does nothing, this method is supposed to be overrided by child classes.

[Validate]