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, <[email protected]>

   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.