IO::Multiplex - Manage IO on many file handles
use IO::Multiplex;
my $mux = new IO::Multiplex;
$mux->add($fh1);
$mux->add(\*FH2);
$mux->set_callback_object(...);
$mux->listen($server_socket);
$mux->loop;
sub mux_input {
...
}
IO::Multiplex is designed to take the effort out of managing
multiple file handles. It is essentially a really fancy front end to
the select system call. In addition to maintaining the select
loop, it buffers all input and output to/from the file handles. It
can also accept incoming connections on one or more listen sockets.
It is object oriented in design, and will notify you of significant events
by calling methods on an object that you supply. If you are not using
objects, you can simply supply __PACKAGE__ instead of an object reference.
You may have one callback object registered for each file handle, or one global one. Possibly both -- the per-file handle callback object will be used instead of the global one.
Each file handle may also have a timer associated with it. A callback function is called when the timer expires.
When input arrives on a file handle, the mux_input method is called
on the appropriate callback object. This method is passed three
arguments (in addition to the object reference itself of course):
The method should remove the data that it has consumed from the reference supplied. It may leave unconsumed data in the input buffer.
If IO::Multiplex did not handle output to the file handles as well
as input from them, then there is a chance that the program could
block while attempting to write. If you let the multiplexer buffer
the output, it will write the data only when the file handle is
capable of receiveing it.
The basic method for handing output to the multiplexer is the write
method, which simply takes a file descriptor and the data to be
written, like this:
$mux->write($fh, "Some data");
For convenience, when the file handle is added to the multiplexer, it
is tied to a special class which intercepts all attempts to write to the
file handle. Thus, you can use print and printf to send output to the
handle in a normal manner:
printf $fh "%s%d%X", $foo, $bar, $baz
Unfortunately, Perl support for tied file handles is incomplete, and
functions such as send cannot be supported.
Also, file handle object methods such as the send method of
IO::Socket cannot be intercepted.
This is a simple telnet-like program, which demonstrates the concepts covered so far. It does not really work too well against a telnet server, but it does OK against the sample server presented further down.
use IO::Socket;
use IO::Multiplex;
# Create a multiplex object
my $mux = new IO::Multiplex;
# Connect to the host/port specified on the command line,
# or localhost:23
my $sock = new IO::Socket::INET(Proto => 'tcp',
PeerAddr => shift || 'localhost',
PeerPort => shift || 23)
or die "socket: $@";
# add the relevant file handles to the mux
$mux->add($sock);
$mux->add(\*STDIN);
# We want to buffer output to the terminal. This prevents the program
# from blocking if the user hits CTRL-S for example.
$mux->add(\*STDOUT);
# We're not object oriented, so just request callbacks to the
# current package
$mux->set_callback_object(__PACKAGE__);
# Enter the main mux loop.
$mux->loop;
# mux_input is called when input is available on one of
# the descriptors.
sub mux_input {
my $package = shift;
my $mux = shift;
my $fh = shift;
my $input = shift;
# Figure out whence the input came, and send it on to the
# other place.
if ($fh == $sock) {
print STDOUT $$input;
} else {
print $sock $$input;
}
# Remove the input from the input buffer.
$$input = '';
}
# This gets called if the other end closes the connection.
sub mux_close {
print STDERR "Connection Closed\n";
exit;
}
Servers are just as simple to write. We just register a listen socket
with the multiplex object listen method. It will automatically
accept connections on it and add them to its list of active file handles.
This example is a simple chat server.
use IO::Socket;
use IO::Multiplex;
my $mux = new IO::Multiplex;
# Create a listening socket
my $sock = new IO::Socket::INET(Proto => 'tcp',
LocalPort => shift || 2300,
Listen => 4)
or die "socket: $@";
# We use the listen method instead of the add method.
$mux->listen($sock);
$mux->set_callback_object(__PACKAGE__);
$mux->loop;
sub mux_input {
my $package = shift;
my $mux = shift;
my $fh = shift;
my $input = shift;
# The handles method returns a list of references to handles which
# we have registered, except for listen sockets.
foreach $c ($mux->handles) {
print $c $$input;
}
$$input = '';
}
Let us take a look at the beginnings of a multi-user game server. We will have a Player object for each player.
# Paste the above example in here, up to but not including the
# mux_input subroutine.
# mux_connection is called when a new connection is accepted.
sub mux_connection {
my $package = shift;
my $mux = shift;
my $fh = shift;
# Construct a new player object
Player->new($mux, $fh);
}
package Player;
my %players = ();
sub new {
my $package = shift;
my $self = bless { mux => shift,
fh => shift } => $package;
# Register the new player object as the callback specifically for
# this file handle.
$self->{mux}->set_callback_object($self, $self->{fh});
print $self->{fh}
"Greetings, Professor. Would you like to play a game?\n";
# Register this player object in the main list of players
$players{$self} = $self;
$mux->set_timeout($self->{fh}, 1);
}
sub players { return values %players; }
sub mux_input {
my $self = shift;
shift; shift; # These two args are boring
my $input = shift; # Scalar reference to the input
# Process each line in the input, leaving partial lines
# in the input buffer
while ($$input =~ s/^(.*?)\n//) {
$self->process_command($1);
}
}
sub mux_close {
my $self = shift;
# Player disconnected;
# [Notify other players or something...]
delete $players{$self};
}
# This gets called every second to update player info, etc...
sub mux_timeout {
my $self = shift;
my $mux = shift;
$self->heartbeat;
$mux->set_timeout($self->{fh}, 1);
}
Construct a new IO::Multiplex object.
$mux = new IO::Multiplex;
Add a socket to be listened on. The socket should have had the
bind and listen system calls already applied to it. The IO::Socket
module will do this for you.
$socket = new IO::Socket::INET(Listen => ..., LocalAddr => ...);
$mux->listen($socket);
Connections will be automatically accepted and added to the multiplex
object. The mux_connection callback method will also be called.
Add a file handle to the multiplexer.
$mux->add($fh);
As a side effect, this sets non-blocking mode on the handle, and disables STDIO buffering. It also ties it to intercept output to the handle.
Removes a file handle from the multiplexer. This also unties the handle. It does not currently turn STDIO buffering back on, or turn off non-blocking mode.
$mux->remove($fh);
Set the object on which callbacks are made. If you are not using objects, you can specify the name of the package into which the method calls are to be made.
If a file handle is supplied, the callback object is specific for that handle:
$mux->set_callback_object($object, $fh);
Otherwise, it is considered a default callback object, and is used when events occur on a file handle that does not have its own callback object.
$mux->set_callback_object(__PACKAGE__);
The previously registered object (if any) is returned.
See also the CALLBACK INTERFACE section.
Remove any pending output on a file descriptor.
$mux->kill_output($fh);
Return or set the output buffer for a descriptor
$output = $mux->outbuffer($fh);
$mux->outbuffer($fh, $output);
Return or set the input buffer for a descriptor
$input = $mux->inbuffer($fh);
$mux->inbuffer($fh, $input);
Set the timer for a file handle. The timeout value is a certain number of
seconds in the future, after which the mux_timeout callback is called.
If the Time::HiRes module is installed, the timers may be specified in
fractions of a second.
Timers are not reset automatically.
$mux->set_timeout($fh, 23.6);
Use $mux->set_timeout($fh, undef) to cancel a timer.
Returns a list of handles that the IO::Multiplex object knows about,
excluding listen sockets.
@handles = $mux->handles;
Enter the main loop and start processing IO events.
$mux->loop;
Prematurly terminate the loop. The loop will automatically terminate when there are no remaining descriptors to be watched.
$mux->endloop;
Get peer endpoint of where the last udp packet originated.
$saddr = $mux->udp_peer($fh);
Sometimes UDP packets require special attention. This method will tell if a file handle is of type UDP.
$is_udp = $mux->is_udp($fh);
Send output to a file handle.
$mux->write($fh, "'ere I am, JH!\n");
Shut down a socket for reading or writing or both. See the shutdown
Perl documentation for further details.
If the shutdown is for reading, it happens immediately. However, shutdowns for writing are delayed until any pending output has been successfully written to the socket.
$mux->shutdown($socket, 1);
Close a handle. Always use this method to close a handle that is being watched by the multiplexer.
$mux->close($fh);
Callback objects should support the following interface. You do not have to provide all of these methods, just provide the ones you are interested in.
All methods receive a reference to the callback object (or package) as
their first argument, in the traditional object oriented
way. References to the IO::Multiplex object and the relevant file
handle are also provided. This will be assumed in the method
descriptions.
Called when input is ready on a descriptor. It is passed a reference to the input buffer. It should remove any input that it has consumed, and leave any partially received data in the buffer.
sub mux_input {
my $self = shift;
my $mux = shift;
my $fh = shift;
my $data = shift;
# Process each line in the input, leaving partial lines
# in the input buffer
while ($$data =~ s/^(.*?\n)//) {
$self->process_command($1);
}
}
This is called when an end-of-file condition is present on the descriptor.
This is does not nessecarily mean that the descriptor has been closed, as
the other end of a socket could have used shutdown to close just half
of the socket, leaving us free to write data back down the still open
half. Like mux_input, it is also passed a reference to the input buffer.
It should consume the entire buffer or else it will just be lost.
In this example, we send a final reply to the other end of the socket, and then shut it down for writing. Since it is also shut down for reading (implicly by the EOF condition), it will be closed once the output has been sent, after which the mux_close callback will be called.
sub mux_eof {
my $self = shift;
my $mux = shift;
my $fh = shift;
print $fh "Well, goodbye then!\n";
$mux->shutdown($fh, 1);
}
Called when a handle has been completely closed. At the time that
mux_close is called, the handle will have been removed from the
multiplexer, and untied.
Called after all pending output has been written to the file descriptor.
Called upon a new connection being accepted on a listen socket.
Called when a timer expires.
Copyright 1999 Bruce J Keeler <bruce@gridpoint.com>
Copyright 2001-2003 Rob Brown <bbb@cpan.org>
Released under the terms of the Artistic License.
$Id: Multiplex.pm,v 1.33 2007/03/04 05:39:16 rob Exp $