NAME

       Net::SIP::Dispatcher::Eventloop - simple event loop for Net::SIP::Dispatcher

SYNOPSIS

         my $loop = Net::SIP::Dispatcher::Eventloop->new;
         $loop->addFD( $fd, $callback );
         $loop->add_timer( 10,$callback );
         $loop->loop;

DESCRIPTION

       The package implements a simple event loop. It's not optimized for speed but it is
       provided as a simple implementation in case the users application does not has an event
       loop yet.

       Because the eventloop object can be given in the constructor of Net::SIP::Dispatcher you
       might provide an alternative implementation, which implemented the described methods.

CONSTRUCTOR

       new Creates new event loop, returns created object

METHODS

       addFD ( HANDLE, CALLBACK, ?NAME )
           Adds file handle HANDLE to the event loop, so that CALLBACK gets triggered if HANDLE
           is readable. CALLBACK is a callback accepted by invoke_callback in Net::SIP::Util. The
           callback will be invoked with HANDLE as an additional argument.

           NAME can be used to aid debugging, it will be shown in the debug messages once the FD
           gets ready.

           If there was already a callback for HANDLE it gets replaced by the new one.

           IMPORTANT NOTE: CALLBACK gets triggered if HANDLE *is* readable inside the loop, not
           if HANDLE *gets* readable. Unlike with Event::Lib or similar the CALLBACK is not
           triggered by the edge, but by the level (like poll(2) or select(2)). So if 2 bytes
           come in at the handle and one reads only 1 byte in the callback the callback gets
           triggered again for more data.  You have to watch this, if you want to integrate
           Net::SIP with your existing event loop.

       delFD ( HANDLE )
           Removes HANDLE from loop, e.g. no more checking for readability will be done.

       add_timer( WHEN, CALLBACK, [ REPEAT ] )
           Adds timer which gets triggered at WHEN or "now + WHEN". Depending on the value of
           WHEN it gets interpreted as the number of seconds since 1970-01-01 (when it's really
           big) or as a relative time (when it's not that big).  WHEN can be floating point for
           subseconds resolution.

           CALLBACK is a callback accepted by invoke_callback in Net::SIP::Util.  It gets invoked
           with the timer object (see later) as an additional argument, which has a method cancel
           for canceling the (repeating) timer.

           REPEAT is the number of seconds between each invocation of the timer. If greater then
           0 (subsection resulution possible) the callback will be called each REPEAT seconds,
           after it was called the first time at WHEN.

           The method will return an object which has a method cancel which can be used to cancel
           the timer before it gets triggered (or gets triggered the next time in case of
           repeating timers).

       looptime
           Returns the current loop time in subseconds resolution (using gettimeofday from
           Time::HiRes). This is not the current time, but the time, when the last event in the
           loop occured (e.g. when the select(2) call returned)

       loop ( [ TIMEOUT, \@STOPVAR ] )
           The main loop, e.g. continuiosly checks timers and file handles for the events and
           calls callbacks.

           If TIMEOUT is given it will run the loop for at most TIMEOUT seconds, then the method
           will return. Undefined TIMEOUT means that it will never return because of timeout and
           TIMEOUT of 0 means that it will check all timers and handles only once and then
           return.

           @STOPVAR is a list of scalar references. These scalars are expected to be changed from
           the callbacks, so it will check after each loop cycle, e.g.  after all callbacks are
           called (timers and handles) if any of these scalars is TRUE, in which case it will end
           the loop.

           The behavior with STOPVAR cannot be found in most existing event loops.  If you want
           to integrate Net::SIP with your own event loop you migth simply wrap all callbacks
           given in addFD and add_timer in another callback which at the end checks the stopvars
           and terminates the 3rd-party loop in a loop-specific way.