Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IO::Multiplex(3)      User Contributed Perl Documentation     IO::Multiplex(3)

NAME
       IO::Multiplex - Manage IO on many file handles

SYNOPSIS
	 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.

DESCRIPTION
       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.

   Handling input on descriptors
       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):

       1.  a reference to the mux,

       2.  A reference to the file handle, and

       3.  a reference to the input buffer for the file	handle.

       The method should remove	the data that it has consumed from the
       reference supplied.  It may leave unconsumed data in the	input buffer.

   Handling output to descriptors
       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	"add"ed	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.

EXAMPLES
   Simple Example
       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;
	   }

   A server example
       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 = '';
	   }

   A more complex server example
       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);
	   }

METHODS
   new
       Construct a new "IO::Multiplex" object.

	   $mux	= new IO::Multiplex;

   listen
       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 "add"ed to the multiplex
       object.	"The mux_connection" callback method will also be called.

   add
       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.

   remove
       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_callback_object
       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.

   kill_output
       Remove any pending output on a file descriptor.

	   $mux->kill_output($fh);

   outbuffer
       Return or set the output	buffer for a descriptor

	   $output = $mux->outbuffer($fh);
	   $mux->outbuffer($fh,	$output);

   inbuffer
       Return or set the input buffer for a descriptor

	   $input = $mux->inbuffer($fh);
	   $mux->inbuffer($fh, $input);

   set_timeout
       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.

   handles
       Returns a list of handles that the "IO::Multiplex" object knows about,
       excluding listen	sockets.

	   @handles = $mux->handles;

   loop
       Enter the main loop and start processing	IO events.

	   $mux->loop;

   endloop
       Prematurly terminate the	loop.  The loop	will automatically terminate
       when there are no remaining descriptors to be watched.

	   $mux->endloop;

   udp_peer
       Get peer	endpoint of where the last udp packet originated.

	   $saddr = $mux->udp_peer($fh);

   is_udp
       Sometimes UDP packets require special attention.	 This method will tell
       if a file handle	is of type UDP.

	   $is_udp = $mux->is_udp($fh);

   write
       Send output to a	file handle.

	   $mux->write($fh, "'ere I am,	JH!\n");

   shutdown
       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
       Close a handle.	Always use this	method to close	a handle that is being
       watched by the multiplexer.

	   $mux->close($fh);

CALLBACK INTERFACE
       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.

   mux_input
       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);
	       }
	   }

   mux_eof
       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);
	   }

   mux_close
       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.

   mux_outbuffer_empty
       Called after all	pending	output has been	written	to the file
       descriptor.

   mux_connection
       Called upon a new connection being accepted on a	listen socket.

   mux_timeout
       Called when a timer expires.

AUTHOR
       Copyright 1999 Bruce J Keeler <bruce@gridpoint.com>

       Copyright 2001-2008 Rob Brown <bbb@cpan.org>

       Released	under the same terms as	Perl itself.

       $Id: Multiplex.pm,v 1.36	2008/09/15 08:17:50 rob	Exp $

perl v5.24.1			  2011-04-15		      IO::Multiplex(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | METHODS | CALLBACK INTERFACE | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::Multiplex&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help