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 '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 deter‐
24       mining a response could take a while or an unknown period of time, all
25       other connections established will block until the response completes.
26       If this condition might ever occur, this personality should probably
27       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, con‐
31       venient inet style STDIN/STDOUT handling, logging features, deamoniza‐
32       tion and pid tracking, and restartability -SIGHUP) and some nice fea‐
33       tures of IO::Multiplex (automatic buffered IO and per-file-handle
34       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
98             && $self->allow_deny_hook ){
99
100           # (Net::Server style $self->process_request() is never called.)
101
102           # A unique client specific object is created
103           # for all mux_* methods from this point on.
104           $self = __PACKAGE__->new($self, client);
105
106           $self->mux_connection; # IO::Multiplex style
107
108           for (every packet received) {
109             $self->mux_input;  # NOTE: Multiplexed with accept() above
110           }
111
112         }else{
113
114           $self->request_denied_hook;
115
116           # Notice that if either allow_deny or allow_deny_hook fails, then
117           # new(), mux_connection(), and mux_input() will never be called.
118           # mux_eof() and mux_close() will still be called, but using a
119           # common listen socket callback object instead of a unique client
120           # specific object.
121
122         }
123
124         $self->mux_eof;
125
126         $self->post_process_request_hook;
127
128         $self->mux_close;
129
130       This process then loops multiplexing between the accept() for the next
131       connection and mux_input() when input arrives to avoid blocking either
132       one.
133

HOOKS

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

TIMEOUTS

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

CALLBACK INTERFACE

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

BUGS

218       This is only known to work with TCP servers.
219
220       If you need to use the IO::Multiplex style set_timeout / mux_timeout
221       interface, you cannot use the Net::Server style check_for_dequeue /
222       run_dequeue interface.  It will not work if the check_for_dequeue
223       option is specified.  The run_dequeue method is just a compatibility
224       interface to comply with the Net::Server::Fork style run_dequeue but is
225       implemented in terms of the IO::Multiplex style set_timeout and
226       mux_timeout methods.
227

AUTHOR

229       Rob Brown <bbb@cpan.org>
230

MAINTAINER

232       Paul Seamons <paul@seamons.com>
233

LICENSE

235         This package may be distributed under the terms of either the
236         GNU General Public License
237            or the
238         Perl Artistic License
239
240         All rights reserved.
241