.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "IO::Async::Loop::Select 3pm"
.TH IO::Async::Loop::Select 3pm 2024-02-04 "perl v5.38.2" "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
"IO::Async::Loop::Select" \- use IO::Async with "select(2)"
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Normally an instance of this class would not be directly constructed by a
program. It may however, be useful for runinng IO::Async with an existing
program already using a \f(CW\*(C`select\*(C'\fR call.
.PP
.Vb 1
\&   use IO::Async::Loop::Select;
\&
\&   my $loop = IO::Async::Loop::Select\->new;
\&
\&   $loop\->add( ... );
\&
\&   while(1) {
\&      my ( $rvec, $wvec, $evec ) = (\*(Aq\*(Aq) x 3;
\&      my $timeout;
\&
\&      $loop\->pre_select( \e$rvec, \e$wvec, \e$evec, \e$timeout );
\&      ...
\&      my $ret = select( $rvec, $wvec, $evec, $timeout );
\&      ...
\&      $loop\->post_select( $rvec, $evec, $wvec );
\&   }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This subclass of IO::Async::Loop uses the \f(CWselect(2)\fR syscall to perform
read-ready and write-ready tests.
.PP
To integrate with an existing \f(CW\*(C`select\*(C'\fR\-based event loop, a pair of methods
\&\f(CW\*(C`pre_select\*(C'\fR and \f(CW\*(C`post_select\*(C'\fR can be called immediately before and
after a \f(CW\*(C`select\*(C'\fR call. The relevant bits in the read-ready, write-ready and
exceptional-state bitvectors are set by the \f(CW\*(C`pre_select\*(C'\fR method, and tested
by the \f(CW\*(C`post_select\*(C'\fR method to pick which event callbacks to invoke.
.SH CONSTRUCTOR
.IX Header "CONSTRUCTOR"
.SS new
.IX Subsection "new"
.Vb 1
\&   $loop = IO::Async::Loop::Select\->new;
.Ve
.PP
This function returns a new instance of a \f(CW\*(C`IO::Async::Loop::Select\*(C'\fR object.
It takes no special arguments.
.SH METHODS
.IX Header "METHODS"
.SS pre_select
.IX Subsection "pre_select"
.Vb 1
\&   $loop\->pre_select( \e$readvec, \e$writevec, \e$exceptvec, \e$timeout );
.Ve
.PP
This method prepares the bitvectors for a \f(CW\*(C`select\*(C'\fR call, setting the bits
that the Loop is interested in. It will also adjust the \f(CW$timeout\fR value if
appropriate, reducing it if the next event timeout the Loop requires is sooner
than the current value.
.IP \e$readvec 8
.IX Item "$readvec"
.PD 0
.IP \e$writevec 8
.IX Item "$writevec"
.IP \e$exceptvec 8
.IX Item "$exceptvec"
.PD
Scalar references to the reading, writing and exception bitvectors
.IP \e$timeout 8
.IX Item "$timeout"
Scalar reference to the timeout value
.SS post_select
.IX Subsection "post_select"
.Vb 1
\&   $loop\->post_select( $readvec, $writevec, $exceptvec );
.Ve
.PP
This method checks the returned bitvectors from a \f(CW\*(C`select\*(C'\fR call, and calls
any of the callbacks that are appropriate.
.ie n .IP $readvec 8
.el .IP \f(CW$readvec\fR 8
.IX Item "$readvec"
.PD 0
.ie n .IP $writevec 8
.el .IP \f(CW$writevec\fR 8
.IX Item "$writevec"
.ie n .IP $exceptvec 8
.el .IP \f(CW$exceptvec\fR 8
.IX Item "$exceptvec"
.PD
Scalars containing the read-ready, write-ready and exception bitvectors
.SS loop_once
.IX Subsection "loop_once"
.Vb 1
\&   $count = $loop\->loop_once( $timeout );
.Ve
.PP
This method calls the \f(CW\*(C`pre_select\*(C'\fR method to prepare the bitvectors for a
\&\f(CW\*(C`select\*(C'\fR syscall, performs it, then calls \f(CW\*(C`post_select\*(C'\fR to process the
result. It returns the total number of callbacks invoked by the
\&\f(CW\*(C`post_select\*(C'\fR method, or \f(CW\*(C`undef\*(C'\fR if the underlying \f(CWselect(2)\fR syscall
returned an error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
IO::Select \- OO interface to select system call
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>