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
- before_fork
- client
- define_message_handler
- define_signal_handler
- finalize_server
- initialize_server
- new
- quit_main
- server
- server_pid
- start
- start_synchronously
- stop
Class Passenger::AbstractServer::ServerError
Class Passenger::AbstractServer::ServerNotStarted
Class Passenger::AbstractServer::UnknownMessage
SERVER_TERMINATION_SIGNAL | = | "SIGTERM" |
[ show source ]
# 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
[ show source ]
# File lib/passenger/abstract_server.rb, line 190 190: def server_pid 191: return @pid 192: end
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.
[ show source ]
# 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 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().
[ show source ]
# 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 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.
[ show source ]
# 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
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.
[ show source ]
# File lib/passenger/abstract_server.rb, line 197 197: def before_fork 198: end
Return the communication channel with the client (i.e. the parent process that started the server). This is a MessageChannel object.
[ show source ]
# File lib/passenger/abstract_server.rb, line 242 242: def client 243: return @child_channel 244: end
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.
[ show source ]
# 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 a handler for a signal.
[ show source ]
# File lib/passenger/abstract_server.rb, line 222 222: def define_signal_handler(signal, handler) 223: @signal_handlers[signal.to_s] = handler 224: end
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.
[ show source ]
# File lib/passenger/abstract_server.rb, line 209 209: def finalize_server 210: end
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.
[ show source ]
# File lib/passenger/abstract_server.rb, line 203 203: def initialize_server 204: end
Tell the main loop to stop as soon as possible.
[ show source ]
# File lib/passenger/abstract_server.rb, line 247 247: def quit_main 248: @done = true 249: end
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.
[ show source ]
# 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