1Net::Server::Multiplex(U3s)er Contributed Perl DocumentatNieotn::Server::Multiplex(3)
2
6 Net::Server::Multiplex - Multiplex several connections within one
7 process
8
10 package MyPlexer;
11 use base 'Net::Server::Multiplex';
13 sub mux_input {
15 #...code...
16 }
17 __PACKAGE__->run();
19
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 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 See examples/samplechat.pl distributed with Net::Server for a simple
37 chat server that uses several of these features.
38
40 The process flow is written in an open, easy to override, easy to hook,
41 fashion. The basic flow is shown below.
42 $self->configure_hook;
44 $self->configure(@_);
46 $self->post_configure;
48 $self->post_configure_hook;
50 $self->pre_bind;
52 $self->bind;
54 if( Restarting server ){
56 $self->restart_open_hook();
57 }
58 $self->post_bind_hook;
60 $self->post_bind;
62 $self->pre_loop_hook;
64 $self->loop; # This basically just runs IO::Multiplex::loop
66 # For routines inside a $self->loop
67 # See CLIENT PROCESSING below
68 $self->pre_server_close_hook;
70 $self->post_child_cleanup_hook;
72 $self->server_close;
74 if( Restarting server ){
76 $self->restart_close_hook();
77 $self->hup_server;
78 # Redo process again starting with configure_hook
79 }
80 The server then exits.
82
84 The following represents the client processing program flow:
85 $self->{server}->{client} = Net::Server::Proto::TCP->accept(); # NOTE: Multiplexed with mux_input() below
87 if (check_for_dequeue seconds have passed) {
89 $self->run_dequeue();
90 }
91 $self->get_client_info;
93 $self->post_accept_hook; # Net::Server style
95 if( $self->allow_deny
97 && $self->allow_deny_hook ){
99 # (Net::Server style $self->process_request() is never called.)
101 # A unique client specific object is created
103 # for all mux_* methods from this point on.
104 $self = __PACKAGE__->new($self, client);
105 $self->mux_connection; # IO::Multiplex style
107 for (every packet received) {
109 $self->mux_input; # NOTE: Multiplexed with accept() above
110 }
111 }else{
113 $self->request_denied_hook;
115 # 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 }
123 $self->mux_eof;
125 $self->post_process_request_hook;
127 $self->mux_close;
129 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
135 The *_hook methods mentioned above are meant to be overridden with your
136 own subroutines if you desire to provide additional functionality.
137 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
141 IO::Multiplex methods may access the Net::Server object at
142 "$self->{net_server}" if desired.
143 The process_request() method is never used with this personality.
145 The other Net::Server hooks and methods should work the same.
147 "$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
155 set_timeout
156 To utilize the optional timeout feature of IO::Multiplex, you need to
157 specify a timeout by using the set_timeout method.
158 $self->{net_server}->{mux}->set_timeout($fh, $seconds_from_now);
160 $fh may be either a client socket or a listen socket file descriptor
162 within the mux. $seconds_from_now may be fractional to achieve more
163 precise timeouts. This is used in conjuction with mux_timeout, which
164 you should define yourself.
165 mux_timeout
167 The main loop() routine will call $obj->mux_timeout($mux, $fh) when the
168 timeout specified in set_timeout is reached where $fh is the same as
169 the one specified in set_timeout() and $obj is its corresponding object
170 (either the unique client specific object or the main listen callback
171 object) and $mux is the main IO::Multiplex object itself.
172
174 Callback objects should support the following interface. You do not
175 have to provide all of these methods, just provide the ones you are
176 interested in. These are just like the IO::Multiplex hooks except that
177 STDOUT is tied to the corresponding client socket handle for your
178 convenience and to more closely emulate the Net::Server model.
179 However, unlike some other Net::Server personalities, you should never
180 read directly from STDIN yourself. You should define one or more of
181 the following methods:
182 mux_connection ($mux,$fh)
184 (OPTIONAL) Run once when the client first connects if the allow_deny
185 passes. Note that the "$self->{net_server}->{server}" property hash
186 may be modified by future connections through Net::Server. Any values
187 within it that this object may need to use later should be copied
188 within its own object at this point.
189 Example:
191 $self->{peerport} = $self->{net_server}->{server}->{peerport};
192 mux_input ($mux,$fh,\$data)
194 (REQUIRED) Run each time a packet is read. It should consume $data
195 starting at the left and leave unconsumed data in the scalar for future
196 calls to mux_input.
197 mux_eof ($mux,$fh,\$data)
199 (OPTIONAL) Run once when the client is done writing. It should consume
200 the rest of $data since mux_input() will never be run again.
201 mux_close ($mux,$fh)
203 (OPTIONAL) Run after the entire client socket has been closed. No more
204 attempts should be made to read or write to the client or to STDOUT.
205 mux_timeout ($mux,$fh)
207 (OPTIONAL) Run once when the set_timeout setting expires as explained
208 above.
209
211 This is only known to work with TCP servers.
212 If you need to use the IO::Multiplex style set_timeout / mux_timeout
214 interface, you cannot use the Net::Server style check_for_dequeue /
215 run_dequeue interface. It will not work if the check_for_dequeue
216 option is specified. The run_dequeue method is just a compatibility
217 interface to comply with the Net::Server::Fork style run_dequeue but is
218 implemented in terms of the IO::Multiplex style set_timeout and
219 mux_timeout methods.
220
222 Rob Brown <bbb@cpan.org>
223
225 Paul Seamons <paul@seamons.com>
226
228 This package may be distributed under the terms of either the
229 GNU General Public License
230 or the
231 Perl Artistic License
232 All rights reserved.
234
236 Net::Server by Paul Seamons <paul@seamons.com>,
237 IO::Multiplex by Bruce Keeler <bruce@gridpoint.com>.
239perl v5.12.0 2007-02-03 Net::Server::Multiplex(3)