1Server::Starter(3)    User Contributed Perl Documentation   Server::Starter(3)
2
3
4

NAME

6       Server::Starter - a superdaemon for hot-deploying server programs
7

SYNOPSIS

9         # from command line
10         % start_server --port=80 my_httpd
11
12         # in my_httpd
13         use Server::Starter qw(server_ports);
14
15         my $listen_sock = IO::Socket::INET->new(
16             Proto => 'tcp',
17         );
18         $listen_sock->fdopen((values %{server_ports()})[0], 'w')
19             or die "failed to bind to listening socket:$!";
20
21         while (1) {
22             if (my $conn = $listen_sock->accept) {
23                 ....
24             }
25         }
26

DESCRIPTION

28       It is often a pain to write a server program that supports graceful
29       restarts, with no resource leaks.  Server::Starter, solves the problem
30       by splitting the task into two.  One is start_server, a script provided
31       as a part of the module, which works as a superdaemon that binds to
32       zero or more TCP ports or unix sockets, and repeatedly spawns the
33       server program that actually handles the necessary tasks (for example,
34       responding to incoming commenctions).  The spawned server programs
35       under Server::Starter call accept(2) and handle the requests.
36
37       To gracefully restart the server program, send SIGHUP to the
38       superdaemon.  The superdaemon spawns a new server program, and if (and
39       only if) it starts up successfully, sends SIGTERM to the old server
40       program.
41
42       By using Server::Starter it is much easier to write a hot-deployable
43       server.  Following are the only requirements a server program to be run
44       under Server::Starter should conform to:
45
46       - receive file descriptors to listen to through an environment variable
47       - perform a graceful shutdown when receiving SIGTERM
48
49       A Net::Server personality that can be run under Server::Starter exists
50       under the name Net::Server::SS::PreFork.
51

METHODS

53       server_ports
54           Returns zero or more file descriptors on which the server program
55           should call accept(2) in a hashref.  Each element of the hashref
56           is: (host:port|port|path_of_unix_socket) => file_descriptor.
57
58       start_server
59           Starts the superdaemon.  Used by the "start_server" scirpt.
60

AUTHOR

62       Kazuho Oku
63

SEE ALSO

65       Net::Server::SS::PreFork
66

LICENSE

68       This library is free software; you can redistribute it and/or modify it
69       under the same terms as Perl itself.
70
71
72
73perl v5.12.2                      2011-01-18                Server::Starter(3)