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 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
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] |
# File lib/phusion_passenger/abstract_server.rb, line 116 116: def initialize(socket_filename = nil, password = nil) 117: @socket_filename = socket_filename 118: @password = password 119: @socket_filename ||= "#{passenger_tmpdir}/spawn-server/socket.#{Process.pid}.#{object_id}" 120: @password ||= generate_random_id(:base64) 121: 122: @message_handlers = {} 123: @signal_handlers = {} 124: @orig_signal_handlers = {} 125: end
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
# File lib/phusion_passenger/abstract_server.rb, line 267 267: def connect 268: channel = MessageChannel.new(UNIXSocket.new(@socket_filename)) 269: begin 270: channel.write_scalar(@password) 271: yield channel 272: ensure 273: channel.close 274: end 275: 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.
# File lib/phusion_passenger/abstract_server.rb, line 134 134: def start 135: if started? 136: raise ServerAlreadyStarted, "Server is already started" 137: end 138: 139: a, b = UNIXSocket.pair 140: File.unlink(@socket_filename) rescue nil 141: server_socket = UNIXServer.new(@socket_filename) 142: File.chmod(0700, @socket_filename) 143: 144: before_fork 145: @pid = fork 146: if @pid.nil? 147: has_exception = false 148: begin 149: STDOUT.sync = true 150: STDERR.sync = true 151: a.close 152: 153: # During Passenger's early days, we used to close file descriptors based 154: # on a white list of file descriptors. That proved to be way too fragile: 155: # too many file descriptors are being left open even though they shouldn't 156: # be. So now we close file descriptors based on a black list. 157: # 158: # Note that STDIN, STDOUT and STDERR may be temporarily set to 159: # different file descriptors than 0, 1 and 2, e.g. in unit tests. 160: # We don't want to close these either. 161: file_descriptors_to_leave_open = [0, 1, 2, 162: b.fileno, server_socket.fileno, 163: fileno_of(STDIN), fileno_of(STDOUT), fileno_of(STDERR) 164: ].compact.uniq 165: NativeSupport.close_all_file_descriptors(file_descriptors_to_leave_open) 166: # In addition to closing the file descriptors, one must also close 167: # the associated IO objects. This is to prevent IO.close from 168: # double-closing already closed file descriptors. 169: close_all_io_objects_for_fds(file_descriptors_to_leave_open) 170: 171: # At this point, RubyGems might have open file handles for which 172: # the associated file descriptors have just been closed. This can 173: # result in mysterious 'EBADFD' errors. So we force RubyGems to 174: # clear all open file handles. 175: Gem.clear_paths 176: 177: # Reseed pseudo-random number generator for security reasons. 178: srand 179: 180: start_synchronously(@socket_filename, @password, server_socket, b) 181: rescue Interrupt 182: # Do nothing. 183: has_exception = true 184: rescue Exception => e 185: has_exception = true 186: print_exception(self.class.to_s, e) 187: ensure 188: exit!(has_exception ? 1 : 0) 189: end 190: end 191: server_socket.close 192: b.close 193: @owner_socket = a 194: 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.
All hooks will be called, except before_fork().
# File lib/phusion_passenger/abstract_server.rb, line 200 200: def start_synchronously(socket_filename, password, server_socket, owner_socket) 201: @owner_socket = owner_socket 202: begin 203: reset_signal_handlers 204: initialize_server 205: begin 206: server_main_loop(password, server_socket) 207: ensure 208: finalize_server 209: end 210: rescue Interrupt 211: # Do nothing 212: ensure 213: @owner_socket = nil 214: revert_signal_handlers 215: File.unlink(socket_filename) rescue nil 216: server_socket.close 217: end 218: end
Return whether the server has been started.
# File lib/phusion_passenger/abstract_server.rb, line 247 247: def started? 248: return !!@owner_socket 249: 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.
# File lib/phusion_passenger/abstract_server.rb, line 225 225: def stop 226: if !started? 227: raise ServerNotStarted, "Server is not started" 228: end 229: 230: begin 231: @owner_socket.write("x") 232: rescue Errno::EPIPE 233: end 234: @owner_socket.close 235: @owner_socket = nil 236: File.unlink(@socket_filename) rescue nil 237: 238: # Wait at most 4 seconds for server to exit. If it doesn't do that, 239: # we kill it forcefully with SIGKILL. 240: if !Process.timed_waitpid(@pid, 4) 241: Process.kill('SIGKILL', @pid) rescue nil 242: Process.timed_waitpid(@pid, 1) 243: end 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.
# File lib/phusion_passenger/abstract_server.rb, line 300 300: def define_message_handler(message_name, handler) 301: @message_handlers[message_name.to_s] = handler 302: end
Define a handler for a signal.
# File lib/phusion_passenger/abstract_server.rb, line 305 305: def define_signal_handler(signal, handler) 306: @signal_handlers[signal.to_s] = handler 307: end
# File lib/phusion_passenger/abstract_server.rb, line 309 309: def fileno_of(io) 310: return io.fileno 311: rescue 312: return nil 313: 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.
# File lib/phusion_passenger/abstract_server.rb, line 292 292: def finalize_server 293: 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.
# File lib/phusion_passenger/abstract_server.rb, line 286 286: def initialize_server 287: end