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 < PhusionPassenger::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
server_pid()
click to toggle source
Return the PID of the started server. This is only valid if start() has
been called.
244: def server_pid
245: return @pid
246: end
start()
click to toggle source
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.
124: def start
125: if started?
126: raise ServerAlreadyStarted, "Server is already started"
127: end
128:
129: @parent_socket, @child_socket = UNIXSocket.pair
130: before_fork
131: @pid = fork
132: if @pid.nil?
133: begin
134: STDOUT.sync = true
135: STDERR.sync = true
136: @parent_socket.close
137:
138:
139:
140:
141:
142:
143:
144:
145:
146: file_descriptors_to_leave_open = [0, 1, 2, @child_socket.fileno,
147: fileno_of(STDIN), fileno_of(STDOUT), fileno_of(STDERR)].compact.uniq
148: NativeSupport.close_all_file_descriptors(file_descriptors_to_leave_open)
149:
150:
151:
152: close_all_io_objects_for_fds(file_descriptors_to_leave_open)
153:
154:
155:
156:
157:
158: Gem.clear_paths
159:
160:
161: srand
162:
163: start_synchronously(@child_socket)
164: rescue Interrupt
165:
166: rescue SignalException => signal
167: if signal.message == SERVER_TERMINATION_SIGNAL
168:
169: else
170: print_exception(self.class.to_s, signal)
171: end
172: rescue Exception => e
173: print_exception(self.class.to_s, e)
174: ensure
175: exit!
176: end
177: end
178: @child_socket.close
179: @parent_channel = MessageChannel.new(@parent_socket)
180: end
start_synchronously(socket)
click to toggle source
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().
189: def start_synchronously(socket)
190: @child_socket = socket
191: @child_channel = MessageChannel.new(socket)
192: begin
193: reset_signal_handlers
194: initialize_server
195: begin
196: main_loop
197: ensure
198: finalize_server
199: end
200: ensure
201: revert_signal_handlers
202: end
203: end
started?()
click to toggle source
Return whether the server has been started.
239: def started?
240: return !@parent_channel.nil?
241: end
stop()
click to toggle source
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.
210: def stop
211: if !started?
212: raise ServerNotStarted, "Server is not started"
213: end
214:
215: @parent_socket.close
216: @parent_channel = nil
217:
218:
219:
220:
221: begin
222: Timeout::timeout(3) do
223: Process.waitpid(@pid) rescue nil
224: end
225: rescue Timeout::Error
226: Process.kill(SERVER_TERMINATION_SIGNAL, @pid) rescue nil
227: begin
228: Timeout::timeout(3) do
229: Process.waitpid(@pid) rescue nil
230: end
231: rescue Timeout::Error
232: Process.kill('SIGKILL', @pid) rescue nil
233: Process.waitpid(@pid, Process::WNOHANG) rescue nil
234: end
235: end
236: end
before_fork()
click to toggle source
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.
251: def before_fork
252: end
client()
click to toggle source
Return the communication channel with the client (i.e. the parent process
that started the server). This is a MessageChannel object.
296: def client
297: return @child_channel
298: end
define_message_handler(message_name, handler)
click to toggle source
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.
271: def define_message_handler(message_name, handler)
272: @message_handlers[message_name.to_s] = handler
273: end
define_signal_handler(signal, handler)
click to toggle source
Define a handler for a signal.
276: def define_signal_handler(signal, handler)
277: @signal_handlers[signal.to_s] = handler
278: end
fileno_of(io)
click to toggle source
305: def fileno_of(io)
306: return io.fileno
307: rescue
308: return nil
309: end
finalize_server()
click to toggle source
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.
263: def finalize_server
264: end
initialize_server()
click to toggle source
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.
257: def initialize_server
258: end
quit_main()
click to toggle source
Tell the main loop to stop as soon as possible.
301: def quit_main
302: @done = true
303: end
server()
click to toggle source
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.
287: def server
288: if !started?
289: raise ServerNotStarted, "Server hasn't been started yet. Please call start() first."
290: end
291: return @parent_channel
292: end