NAME
    Event::Lib::UDPPump - Event::Lib event type for high performance UDP
    applications.

SYNOPSIS
      use Event::Lib::UDPPump;
      use IO::Socket::INET;

      my $numchildren = 10;

      my $s = IO::Socket::INET->new(Proto => 'udp', 
                                    LocalPort => 5000);

      fork() foreach (1..($numchildren - 1));

      my $pump = udppump_new($s, \&callback, @args);
      $pump->add();
      event_mainloop();

      sub callback {
        my ($results_href, @args) = @_;
        # Process results here.
      }

DESCRIPTION
    This module is intended for people writing high performance UDP
    applications. It is an extension of the Event::Lib module, and can
    provide better performance in several circumstances.

    When a UDPPump event is registered for a UDP socket, a pthreads thread
    is created in the background. All this thread does is block in
    "recvfrom" waiting for a packet to be received on the socket. When that
    happens, it will then pass a packet over to the main thread which will
    call the callback you have registered. This will be more efficent
    specifically in the case when you have several processes or threads all
    processing data on the same UDP port. This avoids the problem with
    multiple processes all blocking in select (or poll, etc) waiting for
    traffic on the same socket, and then all waiting up and trying to read
    from the socket at the same time when new data arrives.

    This can make it easier to implement daemons where each request may
    require significant processing. This is because while your callback is
    running, the recvfrom thread will be blocking waiting for you to
    complete. This means that you can run a number of child processes as
    workers, and as long as you have a few of them waiting in "recvfrom"
    then response times will not suffer.

    The other primary benefit is that it can allow you to take advantage of
    multi-processor/multi-core servers without having to resort to using
    threads. This is the primary reason that this module was implemented.

SUBROUTINES/METHODS
  udppump_new($socket, $callback, [@args])
    $socket should be a UDP socket.

    $callback should be a code reference. When a packet is received it will
    be called with a hash reference as it's first parameter, and @args as
    the rest of the parameters, if @args is provided.

    The hash reference will have the following keys:

    from
        This is a packed "sockaddr_in" that specifies where the packet was
        received from. You can use the "unpack_sockaddr_in" function in
        Socket to unpack this.

    buffer
        This will be the body of the packet received.

    len This is the length of the packet received. It is actually the return
        value of recvfrom, so it will be -1 if an error occured.

    errno
        This is the value of "errno" after recvfrom returns. This is
        probably only useful if "len" indicates there was an error.

  $event->add()
    This will do all the setup work for the UDPPump. This includes starting
    the backgroun thread, and registering some underlying Event::Lib events
    for the notification.

  $event->fh()
    Returns the file handle associated with the UDPPump event.

CAVEATS
    I can't think of any reason this module wouldn't work just fine on any
    type of datagram socket. In fact, I imagine it'll work great on anything
    that recvfrom works on.

    There is no way to remove a UDPPump event once it's created. This isn't
    implemented because I didn't care to get into the hairy mess that is
    required with thread cancellation, and I expect this will be used mostly
    in server applications where the socket is created at startup and only
    destroyed on exit. If you really need to be able to delete events, it'd
    probably not be too horrible to implement.

    This has only been tested on Solaris 10. If it doesn't work for you on
    another platform, I'm willing to take patches or reasonably helpful
    error reports.

EXPORT
    The "udppump_new" function is exported by default.

DEPENDENCIES
    This module requires the excellent Event::Lib module.

AUTHOR
    Clayton O'Neill, <udppump.20.coneill@xoxy.net>

    The above email address is a spamgourmet (http://www.spamgourmet.com)
    email address. It will stop working after it receives 20 pieces of mail.
    Given how badly CPAN authors get spammed, that will probably be pretty
    quickly. I'd recommend changing the "udppump" part above to anything
    else when sending me email.

LICENSE AND COPYRIGHT
    Copyright (C) 2006 by Clayton O'Neill

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.5 or, at
    your option, any later version of Perl 5 you may have available.