.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::SIP::Dispatcher::Eventloop 3pm"
.TH Net::SIP::Dispatcher::Eventloop 3pm "2023-09-29" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::SIP::Dispatcher::Eventloop \- simple event loop for Net::SIP::Dispatcher
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  my $loop = Net::SIP::Dispatcher::Eventloop\->new;
\&  $loop\->addFD( $fd, $callback );
\&  $loop\->add_timer( 10,$callback );
\&  $loop\->loop;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new" 4
.IX Item "new"
Creates new event loop, returns created object
.SH "METHODS"
.IX Header "METHODS"
.IP "addFD (\s-1HANDLE, RW, CALLBACK,\s0 [\s-1NAME\s0])" 4
.IX Item "addFD (HANDLE, RW, CALLBACK, [NAME])"
Adds file handle \s-1HANDLE\s0 to the event loop, so that \s-1CALLBACK\s0 gets triggered
if \s-1HANDLE\s0 is readable (\fB\s-1RW\s0\fR 0) or writeable (\fB\s-1RW\s0\fR 1). Instead of \f(CW0\fR and \f(CW1\fR
one can also use the exported constants \f(CW\*(C`EV_READ\*(C'\fR and \f(CW\*(C`EV_WRITE\*(C'\fR.
\&\s-1CALLBACK\s0 is a callback accepted by \fBinvoke_callback\fR in Net::SIP::Util.
The callback will be invoked with \s-1HANDLE\s0 as an additional argument.
.Sp
\&\s-1NAME\s0 can be used to aid debugging, it will be shown in the debug messages
once the \s-1FD\s0 gets ready.
.Sp
If there was already a callback for \s-1HANDLE\s0 it gets replaced by the new one.
.Sp
\&\s-1IMPORTANT NOTE: CALLBACK\s0 gets triggered if \s-1HANDLE\s0 *is* readable inside the
loop, not if \s-1HANDLE\s0 *gets* readable. Unlike with Event::Lib or similar
the \s-1CALLBACK\s0 is not triggered by the edge, but by the level (like \fBpoll\fR\|(2)
or \fBselect\fR\|(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.
.IP "delFD (\s-1HANDLE,\s0 [\s-1RW\s0])" 4
.IX Item "delFD (HANDLE, [RW])"
If \fB\s-1RW\s0\fR is 0 (\s-1EV_READ\s0) no more checking for readability of \fB\s-1HANDLE\s0\fR will be
done. If \fB\s-1RW\s0\fR is 1 (\s-1EV_WRITE\s0) no more checking for writeability of \fB\s-1HANDLE\s0\fR
will be done.
If \fB\s-1RW\s0\fR is not given it will remove \fB\s-1HANDLE\s0\fR from the loop completely, i.e.
for both read and write.
.IP "add_timer( \s-1WHEN, CALLBACK,\s0 [ \s-1REPEAT\s0 ] )" 4
.IX Item "add_timer( WHEN, CALLBACK, [ REPEAT ] )"
Adds timer which gets triggered at \s-1WHEN\s0 or \f(CW\*(C`now + WHEN\*(C'\fR. Depending on
the value of \s-1WHEN\s0 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).
\&\s-1WHEN\s0 can be floating point for subseconds resolution.
.Sp
\&\s-1CALLBACK\s0 is a callback accepted by \fBinvoke_callback\fR in Net::SIP::Util.
It gets invoked with the timer object (see later) as an additional argument,
which has a method \fBcancel\fR for canceling the (repeating) timer.
.Sp
\&\s-1REPEAT\s0 is the number of seconds between each invocation of the timer. If greater
then 0 (subsection resolution possible) the callback will be called each
\&\s-1REPEAT\s0 seconds, after it was called the first time at \s-1WHEN.\s0
.Sp
The method will return an object which has a method \fBcancel\fR which can be
used to cancel the timer before it gets triggered (or gets triggered the next
time in case of repeating timers).
.IP "looptime" 4
.IX Item "looptime"
Returns the current loop time in subseconds resolution (using \fBgettimeofday\fR
from Time::HiRes). This is not the current time, but the time, when the
last event in the loop occurred (e.g. when the \fBselect\fR\|(2) call returned)
.ie n .IP "loop ( [ \s-1TIMEOUT,\s0 @STOPVAR ] )" 4
.el .IP "loop ( [ \s-1TIMEOUT,\s0 \f(CW@STOPVAR\fR ] )" 4
.IX Item "loop ( [ TIMEOUT, @STOPVAR ] )"
The main loop, e.g. continuiosly checks timers and file handles for the
events and calls callbacks.
.Sp
If \s-1TIMEOUT\s0 is given it will run the loop for at most \s-1TIMEOUT\s0 seconds,
then the method will return. Undefined \s-1TIMEOUT\s0 means that it will never
return because of timeout and \s-1TIMEOUT\s0 of 0 means that it will check all
timers and handles only once and then return.
.Sp
\&\f(CW@STOPVAR\fR 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 \s-1TRUE,\s0 in which case it will end the loop.
.Sp
The behavior with \s-1STOPVAR\s0 cannot be found in most existing event loops.
If you want to integrate Net::SIP with your own event loop you might
simply wrap all callbacks given in \fBaddFD\fR and \fBadd_timer\fR in another
callback which at the end checks the stopvars and terminates the 3rd\-party loop
in a loop-specific way.