view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    Defines what mechanism to use for the event loop, currently only two
    build in are available; IO::Epoll and IO::Select. IO::Select being the
    default.

      my $mux = new IO::EventMux(EventLoop => [$mechanism, $args]);

    IO::Epoll example for holding 1024 file handles:

      my $mux = new IO::EventMux(EventLoop => ["IO::Epoll", 1024]);

    It's also possible to define your own, this is done by creating a hash
    that implements the following structure:

      my $mux = new IO::EventMux(EventLoop => {
          Add => sub { 
            my($self, $list, $fh) = @_;
            ...
          },
          Wait => sub {
            my($self, $timeout) = @_;
            ...
            return {
                can_read => [$fh, ...],
                can_write => [$fh, ...],
            };
            
      },
          Remove => sub {
            my($self, $list, $fh) = @_;
            ...
          },
          Handles => sub {
            my($self) = @_;
            ...
          },
      });

  mux([$timeout])
    This method will block until ether an event occurs on one of the file
    handles or the $timeout (floating point seconds) expires. If the
    $timeout argument is not present, it waits forever. If $timeout is 0, it
    returns immediately.

    The return value is always a hash, which always has the key 'type',
    indicating what kind it is. It will also usually carry the 'fh' key,
    indicating what file handle the event happened on.

    The 'type' key can have the following values:

    timeout
        Nothing happened and timeout occurred.

    error
        An error occurred in connection with the file handle, such as
        "connection refused", etc.

    accepted
        A new client connected to a listening socket and the connection was
        accepted by EventMux. The listening socket file handle is in the
        'parent_fh' key. If the file handle is a unix domain socket the
        credentials of the user connection will be available in the keys;
        'pid', 'uid' and 'gid'.

    ready
        A file handle is ready to be written to, this can be use full when
        working with nonblocking connects so you know when the remote
        connection accepted the connection.

    accepting
        A new client is trying to connect to a listening socket, but the
        user code must call accept manually. This only happens when the
        ManualAccept option is set.

    read
        A socket has incoming data. If the socket's Buffered option is set,
        this will be what the buffering rule define.

        The data is contained in the 'data' key of the event hash. If recv()
        returned a sender address, it is contained in the 'sender' key and
        must be manually unpacked according to the socket domain, e.g. with
        "Socket::unpack_sockaddr_in()".

    read_last
        A socket last data before it was closed did not match the buffering
        rules, as defined by the IO::Buffered type given. he read_last type
        contains the result of a call to "read_last()" on the chosen buffer
        type.

        The default is not to return read_last and if no buffer is set read
        will contain this information.

    sent
        A socket has sent all the data in it's queue with the send call.
        This however does not indicate that the data has reached the other
        end, normally only that the data has reached the local buffer of the
        kernel.

    closing
        A file handle was detected to be have been closed by the other end
        or the file handle was set to be closed by the user. So EventMux
        stooped listening for events on this file handle. Event data like
        'Meta' is still accessible.

        The 'missing' key indicates the amount of data or packets left in
        the user space buffer when the file handle was closed. This does not
        indicate the amount of data received by the other end, only that the
        user space buffer left.

    closed
        A socket/pipe was disconnected/closed, the file descriptor, all
        internal references, and data store with the file handle was
        removed.

    can_write
        The ManualWrite option is set for the file handle, and "select()"
        has indicated that the handle can be written to.

    can_read
        The ManualRead option is set for the file handle, and "select()" has
        indicated that the handle can be read from.

README  view on Meta::CPAN

  remove($fh)
    Make EventMux forget about a file handle. The caller will then take over
    the responsibility of closing it.

  close($fh)
    Close a file handle. IO::EventMux will stop listing to both reads and
    writes on the file handle and return a "closing" event and on next "mux"
    call kill will be called, returning "closed" for the file handle.

    Note: All 'Meta' data associated with the file handle will be kept until
    the final 'closed' event is returned.

  kill($fh)
    Closes a file handle without giving time to finish any outstanding
    operations. Returns a 'closed' event, deletes all buffers and does not
    keep 'Meta' data.

    Note: Does not return the 'read_last' event.

  buflen($fh)
    Queries the length of the output buffer for this file handle. This only
    applies if ManualWrite is turned off, which is the default. For
    Type="dgram" sockets, it returns the number of datagrams in the queue.

    An application can use this method to see whether it should send more
    data or wait until the buffer queue is a bit shorter.

  recvdata($fh, $length)
    TODO: Queues @data to be written to the file handle $fh. Can only be
    used when ManualWrite is off (default).

  send($fh, @data)
    Queues @data to be written to the file handle $fh. Can only be used when
    ManualWrite is off (default).

    If the socket is of Type="stream"
        Returns true on success, undef on error. The data is sent when the
        socket becomes unblocked and a 'sent' event is posted when all data
        is sent and the buffer is empty. Therefore the socket should not be
        closed until "buflen($fh)" returns 0 or a sent request has been
        posted.

    If the socket is of Type="dgram"
        Each item in @data will be sent as a separate packet. Returns true
        on success and undef on error.

  sendto($fh, $to, @data)
    Like "send()", but with the recepient $to as a packed sockaddr
    structure, such as the one returned by "Socket::pack_sockaddr_in()".
    Only for Type="dgram" sockets.

      $mux->sendto($my_fh, pack_sockaddr_in($port, inet_aton($ip)), $data);

  push_event($event)
    Push event on queue

  nonblock($fh)
    Puts socket into nonblocking mode.

  socket_creds($fh)
    Return credentials on UNIX domain sockets.

  socket_type($fh)
    Return socket type.

  socket_listening($fh)
    Check if the socket is set to listening mode

  recroak()
    Helper function to rethrow croaks

  socket_errors
    Dummy sub that casts an error if the IO::EventMux::Socket::MsgHdr is not
    installed and the Errors option is used

  NOTES
    Working with PIPE's: When the other end of a pipe closes it's end,
    signals can get thrown. To handle this a signal handler needs to be
    defined:

      # Needed when writing to a broken pipe 
      $SIG{PIPE} = sub { # SIGPIPE
         croak "Broken pipe";
     };

    Getting rid of 'Filehandle ... opened only for output'

      # Needed as sysread() throws warnings when STDIN gets closed by the child
      $SIG{__WARN__} = sub {
         croak @_;    
      };

AUTHOR
    Jonas Jensen <jonas@infopro.dk>, Troels Liebe Bentsen
    <troels@infopro.dk>

COPYRIGHT AND LICENCE
    Copyright 2006-2008: Troels Liebe Bentsen Copyright 2006-2007: Jonas
    Jensen

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.