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 connections).  The spawned server programs under
35       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
47           variable
48
49       •   perform a graceful shutdown when receiving SIGTERM
50
51       A Net::Server personality that can be run under Server::Starter exists
52       under the name Net::Server::SS::PreFork.
53

METHODS

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

AUTHOR

64       Kazuho Oku
65

SEE ALSO

67       Net::Server::SS::PreFork
68

LICENSE

70       This library is free software; you can redistribute it and/or modify it
71       under the same terms as Perl itself.
72
73
74
75perl v5.32.1                      2021-01-27                Server::Starter(3)