An abstract base class for a server, with the following properties:

  • The server has exactly one client, and is connected to that client at all times. The server will quit when the connection closes.
  • The server‘s main loop may be run in a child process (and so is asynchronous from the main process).
  • One can communicate with the server through discrete messages (as opposed to byte streams).
  • The server can pass file descriptors (IO objects) back to the client.

A message is just an ordered list of strings. The first element in the message is the _message name_.

The server will also reset all signal handlers (in the child process). 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 < Passenger::AbstractServer
    def initialize
       super()
       define_message_handler(:hello, :handle_hello)
    end

    def hello(first_name, last_name)
       send_to_server('hello', first_name, last_name)
       reply, pointless_number = recv_from_server
       puts "The server said: #{reply}"
       puts "In addition, it sent this pointless number: #{pointless_number}"
    end

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

 server = MyServer.new
 server.start
 server.hello("Joe", "Dalton")
 server.stop
Methods
Included Modules
Classes and Modules
Class Passenger::AbstractServer::ServerAlreadyStarted
Class Passenger::AbstractServer::ServerError
Class Passenger::AbstractServer::ServerNotStarted
Class Passenger::AbstractServer::UnknownMessage
Constants
SERVER_TERMINATION_SIGNAL = "SIGTERM"
Public Class methods
new()
    # File lib/passenger/abstract_server.rb, line 87
87:         def initialize
88:                 @done = false
89:                 @message_handlers = {}
90:                 @signal_handlers = {}
91:                 @orig_signal_handlers = {}
92:         end
Public Instance methods
server_pid()

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

     # File lib/passenger/abstract_server.rb, line 190
190:         def server_pid
191:                 return @pid
192:         end
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.

     # File lib/passenger/abstract_server.rb, line 101
101:         def start
102:                 if !@parent_channel.nil?
103:                         raise ServerAlreadyStarted, "Server is already started"
104:                 end
105:         
106:                 @parent_socket, @child_socket = UNIXSocket.pair
107:                 before_fork
108:                 @pid = fork do
109:                         begin
110:                                 STDOUT.sync = true
111:                                 STDERR.sync = true
112:                                 @parent_socket.close
113:                                 NativeSupport.close_all_file_descriptors([0, 1, 2, @child_socket.fileno])
114:                                 start_synchronously(@child_socket)
115:                         rescue Interrupt
116:                                 # Do nothing.
117:                         rescue SignalException => signal
118:                                 if signal.message == SERVER_TERMINATION_SIGNAL
119:                                         # Do nothing.
120:                                 else
121:                                         print_exception(self.class.to_s, signal)
122:                                 end
123:                         rescue Exception => e
124:                                 print_exception(self.class.to_s, e)
125:                         ensure
126:                                 exit!
127:                         end
128:                 end
129:                 @child_socket.close
130:                 @parent_channel = MessageChannel.new(@parent_socket)
131:         end
start_synchronously(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.

socket is the socket that the server should listen on. The server main loop will end if the socket has been closed.

All hooks will be called, except before_fork().

     # File lib/passenger/abstract_server.rb, line 140
140:         def start_synchronously(socket)
141:                 @child_socket = socket
142:                 @child_channel = MessageChannel.new(socket)
143:                 begin
144:                         reset_signal_handlers
145:                         initialize_server
146:                         begin
147:                                 main_loop
148:                         ensure
149:                                 finalize_server
150:                         end
151:                 ensure
152:                         revert_signal_handlers
153:                 end
154:         end
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.

     # File lib/passenger/abstract_server.rb, line 161
161:         def stop
162:                 if @parent_channel.nil?
163:                         raise ServerNotStarted, "Server is not started"
164:                 end
165:                 
166:                 @parent_socket.close
167:                 @parent_channel = nil
168:                 
169:                 # Wait at most 5 seconds for server to exit. If it doesn't do that,
170:                 # we kill it. If that doesn't work either, we kill it forcefully with
171:                 # SIGKILL.
172:                 begin
173:                         Timeout::timeout(3) do
174:                                 Process.waitpid(@pid) rescue nil
175:                         end
176:                 rescue Timeout::Error
177:                         Process.kill(SERVER_TERMINATION_SIGNAL, @pid) rescue nil
178:                         begin
179:                                 Timeout::timeout(3) do
180:                                         Process.waitpid(@pid) rescue nil
181:                                 end
182:                         rescue Timeout::Error
183:                                 Process.kill('SIGKILL', @pid) rescue nil
184:                                 Process.waitpid(@pid, Process::WNOHANG) rescue nil
185:                         end
186:                 end
187:         end
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.

     # File lib/passenger/abstract_server.rb, line 197
197:         def before_fork
198:         end
client()

Return the communication channel with the client (i.e. the parent process that started the server). This is a MessageChannel object.

     # File lib/passenger/abstract_server.rb, line 242
242:         def client
243:                 return @child_channel
244:         end
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.

     # File lib/passenger/abstract_server.rb, line 217
217:         def define_message_handler(message_name, handler)
218:                 @message_handlers[message_name.to_s] = handler
219:         end
define_signal_handler(signal, handler)

Define a handler for a signal.

     # File lib/passenger/abstract_server.rb, line 222
222:         def define_signal_handler(signal, handler)
223:                 @signal_handlers[signal.to_s] = handler
224:         end
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.

     # File lib/passenger/abstract_server.rb, line 209
209:         def finalize_server
210:         end
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.

     # File lib/passenger/abstract_server.rb, line 203
203:         def initialize_server
204:         end
quit_main()

Tell the main loop to stop as soon as possible.

     # File lib/passenger/abstract_server.rb, line 247
247:         def quit_main
248:                 @done = true
249:         end
server()

Return the communication channel with the server. This is a MessageChannel object.

Raises ServerNotStarted if the server hasn‘t been started yet.

This method may only be called in the parent process, and not in the started server process.

     # File lib/passenger/abstract_server.rb, line 233
233:         def server
234:                 if @parent_channel.nil?
235:                         raise ServerNotStarted, "Server hasn't been started yet. Please call start() first."
236:                 end
237:                 return @parent_channel
238:         end