Net::Server::Multiplex(3pm)

1Net::Server::Multiplex(U3s)er Contributed Perl DocumentatNieotn::Server::Multiplex(3)
2
3
4

NAME

6       Net::Server::Multiplex - Multiplex several connections within one
7       process
8

SYNOPSIS

10           package MyPlexer;
11
12           use base qw(Net::Server::Multiplex);
13
14           sub mux_input {
15               #...code...
16           }
17
18           __PACKAGE__->run();
19

DESCRIPTION

21       This personality is designed to handle multiple connections all within
22       one process.  It should only be used with protocols that are guaranteed
23       to be able to respond quickly on a packet by packet basis.  If
24       determining a response could take a while or an unknown period of time,
25       all other connections established will block until the response
26       completes.  If this condition might ever occur, this personality should
27       probably not be used.
28
29       This takes some nice features of Net::Server (like the server listen
30       socket setup, configuration file processing, safe signal handling,
31       convenient inet style STDIN/STDOUT handling, logging features,
32       deamonization and pid tracking, and restartability -SIGHUP) and some
33       nice features of IO::Multiplex (automatic buffered IO and per-file-
34       handle objects) and combines them for an easy-to-use interace.
35
36       See examples/samplechat.pl distributed with Net::Server for a simple
37       chat server that uses several of these features.
38

PROCESS FLOW

40       The process flow is written in an open, easy to override, easy to hook,
41       fashion.  The basic flow is shown below.
42
43           $self->configure_hook;
44
45           $self->configure(@_);
46
47           $self->post_configure;
48
49           $self->post_configure_hook;
50
51           $self->pre_bind;
52
53           $self->bind;
54
55           if (Restarting server) {
56               $self->restart_open_hook();
57           }
58
59           $self->post_bind_hook;
60
61           $self->post_bind;
62
63           $self->pre_loop_hook;
64
65           $self->loop; # This basically just runs IO::Multiplex::loop
66           # For routines inside a $self->loop
67           # See CLIENT PROCESSING below
68
69           $self->pre_server_close_hook;
70
71           $self->post_child_cleanup_hook;
72
73           $self->server_close;
74
75           if (Restarting server) {
76               $self->restart_close_hook();
77               $self->hup_server;
78               # Redo process again starting with configure_hook
79         }
80
81       The server then exits.
82

CLIENT PROCESSING

84       The following represents the client processing program flow:
85
86           $self->{server}->{client} = Net::Server::Proto::TCP->accept();  # NOTE: Multiplexed with mux_input() below
87
88           if (check_for_dequeue seconds have passed) {
89               $self->run_dequeue();
90           }
91
92           $self->get_client_info;
93
94           $self->post_accept_hook; # Net::Server style
95
96           if ($self->allow_deny
97               && $self->allow_deny_hook) {
98
99             # (Net::Server style $self->process_request() is never called.)
100
101             # A unique client specific object is created
102             # for all mux_* methods from this point on.
103             $self = __PACKAGE__->new($self, client);
104
105             $self->mux_connection; # IO::Multiplex style
106
107             for (every packet received) {
108               $self->mux_input;  # NOTE: Multiplexed with accept() above
109             }
110
111           } else {
112
113             $self->request_denied_hook;
114
115             # Notice that if either allow_deny or allow_deny_hook fails, then
116             # new(), mux_connection(), and mux_input() will never be called.
117             # mux_eof() and mux_close() will still be called, but using a
118             # common listen socket callback object instead of a unique client
119             # specific object.
120
121           }
122
123           $self->mux_eof;
124
125           $self->post_process_request_hook;
126
127           $self->mux_close;
128
129       This process then loops multiplexing between the accept() for the next
130       connection and mux_input() when input arrives to avoid blocking either
131       one.
132

HOOKS

134       The *_hook methods mentioned above are meant to be overridden with your
135       own subroutines if you desire to provide additional functionality.
136
137       The loop() method of Net::Server has been overridden to run the loop
138       routine of IO::Multiplex instead.  The Net::Server methods may access
139       the IO::Multiplex object at "$self->{mux}" if desired.  The
140       IO::Multiplex methods may access the Net::Server object at
141       "$self->{net_server}" if desired.
142
143       The process_request() method is never used with this personality.
144
145       The other Net::Server hooks and methods should work the same.
146
147       "$self->run_dequeue()"
148           This hook only gets called in conjunction with the
149           check_for_dequeue setting.  It will run every check_for_dequeue
150           seconds.  Since no forking is done, this hook should run fast in
151           order to prevent blocking the rest of the processing.
152

TIMEOUTS

154   set_timeout
155       To utilize the optional timeout feature of IO::Multiplex, you need to
156       specify a timeout by using the set_timeout method.
157
158       $self->{net_server}->{mux}->set_timeout($fh, $seconds_from_now);
159
160       $fh may be either a client socket or a listen socket file descriptor
161       within the mux.  $seconds_from_now may be fractional to achieve more
162       precise timeouts.  This is used in conjunction with mux_timeout, which
163       you should define yourself.
164
165   mux_timeout
166       The main loop() routine will call $obj->mux_timeout($mux, $fh) when the
167       timeout specified in set_timeout is reached where $fh is the same as
168       the one specified in set_timeout() and $obj is its corresponding object
169       (either the unique client specific object or the main listen callback
170       object) and $mux is the main IO::Multiplex object itself.
171

CALLBACK INTERFACE

173       Callback objects should support the following interface.  You do not
174       have to provide all of these methods, just provide the ones you are
175       interested in.  These are just like the IO::Multiplex hooks except that
176       STDOUT is tied to the corresponding client socket handle for your
177       convenience and to more closely emulate the Net::Server model.
178       However, unlike some other Net::Server personalities, you should never
179       read directly from STDIN yourself.  You should define one or more of
180       the following methods:
181
182   mux_connection ($mux,$fh)
183       (OPTIONAL) Run once when the client first connects if the allow_deny
184       passes.  Note that the "$self->{net_server}->{server}" property hash
185       may be modified by future connections through Net::Server.  Any values
186       within it that this object may need to use later should be copied
187       within its own object at this point.
188
189         Example:
190         $self->{peerport} = $self->{net_server}->{server}->{peerport};
191
192   mux_input ($mux,$fh,\$data)
193       (REQUIRED) Run each time a packet is read.  It should consume $data
194       starting at the left and leave unconsumed data in the scalar for future
195       calls to mux_input.
196
197   mux_eof ($mux,$fh,\$data)
198       (OPTIONAL) Run once when the client is done writing.  It should consume
199       the rest of $data since mux_input() will never be run again.
200
201   mux_close ($mux,$fh)
202       (OPTIONAL) Run after the entire client socket has been closed.  No more
203       attempts should be made to read or write to the client or to STDOUT.
204
205   mux_timeout ($mux,$fh)
206       (OPTIONAL) Run once when the set_timeout setting expires as explained
207       above.
208

BUGS

210       This is only known to work with TCP servers.
211
212       If you need to use the IO::Multiplex style set_timeout / mux_timeout
213       interface, you cannot use the Net::Server style check_for_dequeue /
214       run_dequeue interface.  It will not work if the check_for_dequeue
215       option is specified.  The run_dequeue method is just a compatibility
216       interface to comply with the Net::Server::Fork style run_dequeue but is
217       implemented in terms of the IO::Multiplex style set_timeout and
218       mux_timeout methods.
219

AUTHOR

221       Rob Brown <bbb@cpan.org>
222

MAINTAINER

224       Paul Seamons <paul@seamons.com>
225

LICENSE

227         This package may be distributed under the terms of either the
228         GNU General Public License
229            or the
230         Perl Artistic License
231
232         All rights reserved.
233