# IO::Multiplex - phpMan

## 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.45 2015/04/09 21:27:54 rob Exp $