.\" -*- 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 "Mojo::IOLoop 3pm"
.TH Mojo::IOLoop 3pm 2024-05-15 "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
Mojo::IOLoop \- Minimalistic event loop
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mojo::IOLoop;
\&
\&  # Listen on port 3000
\&  Mojo::IOLoop\->server({port => 3000} => sub ($loop, $stream, $id) {
\&    $stream\->on(read => sub ($stream, $bytes) {
\&      # Process input chunk
\&      say $bytes;
\&
\&      # Write response
\&      $stream\->write(\*(AqHTTP/1.1 200 OK\*(Aq);
\&    });
\&  });
\&
\&  # Connect to port 3000
\&  my $id = Mojo::IOLoop\->client({port => 3000} => sub ($loop, $err, $stream) {
\&    $stream\->on(read => sub ($stream, $bytes) {
\&      # Process input
\&      say "Input: $bytes";
\&    });
\&
\&    # Write request
\&    $stream\->write("GET / HTTP/1.1\ex0d\ex0a\ex0d\ex0a");
\&  });
\&
\&  # Add a timer
\&  Mojo::IOLoop\->timer(5 => sub ($loop) { $loop\->remove($id) });
\&
\&  # Start event loop if necessary
\&  Mojo::IOLoop\->start unless Mojo::IOLoop\->is_running;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Mojo::IOLoop is a very minimalistic event loop based on Mojo::Reactor, it has been reduced to the absolute
minimal feature set required to build solid and scalable non-blocking clients and servers.
.PP
Depending on operating system, the default per-process and system-wide file descriptor limits are often very low and
need to be tuned for better scalability. The \f(CW\*(C`LIBEV_FLAGS\*(C'\fR environment variable should also be used to select the best
possible EV backend, which usually defaults to the not very scalable \f(CW\*(C`select\*(C'\fR.
.PP
.Vb 5
\&  LIBEV_FLAGS=1    # select
\&  LIBEV_FLAGS=2    # poll
\&  LIBEV_FLAGS=4    # epoll (Linux)
\&  LIBEV_FLAGS=8    # kqueue (*BSD, OS X)
\&  LIBEV_FLAGS=64   # Linux AIO
.Ve
.PP
The event loop will be resilient to time jumps if a monotonic clock is available through Time::HiRes. A TLS
certificate and key are also built right in, to make writing test servers as easy as possible. Also note that for
convenience the \f(CW\*(C`PIPE\*(C'\fR signal will be set to \f(CW\*(C`IGNORE\*(C'\fR when Mojo::IOLoop is loaded.
.PP
For better scalability (epoll, kqueue) and to provide non-blocking name resolution, SOCKS5 as well as TLS support, the
optional modules EV (4.32+), Net::DNS::Native (0.15+), IO::Socket::Socks (0.64+) and IO::Socket::SSL
(2.009+) will be used automatically if possible. Individual features can also be disabled with the \f(CW\*(C`MOJO_NO_NNR\*(C'\fR,
\&\f(CW\*(C`MOJO_NO_SOCKS\*(C'\fR and \f(CW\*(C`MOJO_NO_TLS\*(C'\fR environment variables.
.PP
See "REAL-TIME WEB" in Mojolicious::Guides::Cookbook for more.
.SH EVENTS
.IX Header "EVENTS"
Mojo::IOLoop inherits all events from Mojo::EventEmitter and can emit the following new ones.
.SS finish
.IX Subsection "finish"
.Vb 1
\&  $loop\->on(finish => sub ($loop) {...});
.Ve
.PP
Emitted when the event loop wants to shut down gracefully and is just waiting for all existing connections to be
closed.
.SS reset
.IX Subsection "reset"
.Vb 1
\&  $loop\->on(reset => sub ($loop) {...});
.Ve
.PP
Emitted when the event loop is reset, this usually happens after the process is forked to clean up resources that
cannot be shared.
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
Mojo::IOLoop implements the following attributes.
.SS max_accepts
.IX Subsection "max_accepts"
.Vb 2
\&  my $max = $loop\->max_accepts;
\&  $loop   = $loop\->max_accepts(1000);
.Ve
.PP
The maximum number of connections this event loop is allowed to accept, before shutting down gracefully without
interrupting existing connections, defaults to \f(CW0\fR. Setting the value to \f(CW0\fR will allow this event loop to accept new
connections indefinitely. Note that up to half of this value can be subtracted randomly to improve load balancing
between multiple server processes, and to make sure that not all of them restart at the same time.
.SS max_connections
.IX Subsection "max_connections"
.Vb 2
\&  my $max = $loop\->max_connections;
\&  $loop   = $loop\->max_connections(100);
.Ve
.PP
The maximum number of accepted connections this event loop is allowed to handle concurrently, before stopping to accept
new incoming connections, defaults to \f(CW1000\fR.
.SS reactor
.IX Subsection "reactor"
.Vb 2
\&  my $reactor = $loop\->reactor;
\&  $loop       = $loop\->reactor(Mojo::Reactor\->new);
.Ve
.PP
Low-level event reactor, usually a Mojo::Reactor::Poll or Mojo::Reactor::EV object with a default subscriber to
the event "error" in Mojo::Reactor.
.PP
.Vb 4
\&  # Watch if handle becomes readable or writable
\&  Mojo::IOLoop\->singleton\->reactor\->io($handle => sub ($reactor, $writable) {
\&    say $writable ? \*(AqHandle is writable\*(Aq : \*(AqHandle is readable\*(Aq;
\&  });
\&
\&  # Change to watching only if handle becomes writable
\&  Mojo::IOLoop\->singleton\->reactor\->watch($handle, 0, 1);
\&
\&  # Remove handle again
\&  Mojo::IOLoop\->singleton\->reactor\->remove($handle);
.Ve
.SH METHODS
.IX Header "METHODS"
Mojo::IOLoop inherits all methods from Mojo::EventEmitter and implements the following new ones.
.SS acceptor
.IX Subsection "acceptor"
.Vb 3
\&  my $server = Mojo::IOLoop\->acceptor($id);
\&  my $server = $loop\->acceptor($id);
\&  my $id     = $loop\->acceptor(Mojo::IOLoop::Server\->new);
.Ve
.PP
Get Mojo::IOLoop::Server object for id or turn object into an acceptor.
.SS client
.IX Subsection "client"
.Vb 3
\&  my $id = Mojo::IOLoop\->client(address => \*(Aq127.0.0.1\*(Aq, port => 3000, sub {...});
\&  my $id = $loop\->client(address => \*(Aq127.0.0.1\*(Aq, port => 3000, sub {...});
\&  my $id = $loop\->client({address => \*(Aq127.0.0.1\*(Aq, port => 3000} => sub {...});
.Ve
.PP
Open a TCP/IP or UNIX domain socket connection with Mojo::IOLoop::Client and create a stream object (usually
Mojo::IOLoop::Stream), takes the same arguments as "connect" in Mojo::IOLoop::Client.
.SS is_running
.IX Subsection "is_running"
.Vb 2
\&  my $bool = Mojo::IOLoop\->is_running;
\&  my $bool = $loop\->is_running;
.Ve
.PP
Check if event loop is running.
.SS next_tick
.IX Subsection "next_tick"
.Vb 2
\&  my $undef = Mojo::IOLoop\->next_tick(sub ($loop) {...});
\&  my $undef = $loop\->next_tick(sub ($loop) {...});
.Ve
.PP
Execute callback as soon as possible, but not before returning or other callbacks that have been registered with this
method, always returns \f(CW\*(C`undef\*(C'\fR.
.PP
.Vb 2
\&  # Perform operation on next reactor tick
\&  Mojo::IOLoop\->next_tick(sub ($loop) {...});
.Ve
.SS one_tick
.IX Subsection "one_tick"
.Vb 2
\&  Mojo::IOLoop\->one_tick;
\&  $loop\->one_tick;
.Ve
.PP
Run event loop until an event occurs.
.PP
.Vb 4
\&  # Don\*(Aqt block longer than 0.5 seconds
\&  my $id = Mojo::IOLoop\->timer(0.5 => sub ($loop) {});
\&  Mojo::IOLoop\->one_tick;
\&  Mojo::IOLoop\->remove($id);
.Ve
.SS recurring
.IX Subsection "recurring"
.Vb 3
\&  my $id = Mojo::IOLoop\->recurring(3 => sub ($loop) {...});
\&  my $id = $loop\->recurring(0 => sub ($loop) {...});
\&  my $id = $loop\->recurring(0.25 => sub ($loop) {...});
.Ve
.PP
Create a new recurring timer, invoking the callback repeatedly after a given amount of time in seconds.
.PP
.Vb 2
\&  # Perform operation every 5 seconds
\&  Mojo::IOLoop\->recurring(5 => sub ($loop) {...});
.Ve
.SS remove
.IX Subsection "remove"
.Vb 2
\&  Mojo::IOLoop\->remove($id);
\&  $loop\->remove($id);
.Ve
.PP
Remove anything with an id, connections will be dropped gracefully by allowing them to finish writing all data in their
write buffers.
.SS reset
.IX Subsection "reset"
.Vb 3
\&  Mojo::IOLoop\->reset;
\&  $loop\->reset;
\&  $loop\->reset({freeze => 1});
.Ve
.PP
Remove everything and stop the event loop.
.PP
These options are currently available:
.IP freeze 2
.IX Item "freeze"
.Vb 1
\&  freeze => 1
.Ve
.Sp
Freeze the current state of the event loop in time before resetting it. This will prevent active connections from
getting closed immediately, which can help with many unintended side effects when processes are forked. Note that this
option is \fBEXPERIMENTAL\fR and might change without warning!
.SS server
.IX Subsection "server"
.Vb 3
\&  my $id = Mojo::IOLoop\->server(port => 3000, sub {...});
\&  my $id = $loop\->server(port => 3000, sub {...});
\&  my $id = $loop\->server({port => 3000} => sub {...});
.Ve
.PP
Accept TCP/IP and UNIX domain socket connections with Mojo::IOLoop::Server and create stream objects (usually
Mojo::IOLoop::Stream, takes the same arguments as "listen" in Mojo::IOLoop::Server.
.PP
.Vb 3
\&  # Listen on random port
\&  my $id = Mojo::IOLoop\->server({address => \*(Aq127.0.0.1\*(Aq} => sub ($loop, $stream, $id) {...});
\&  my $port = Mojo::IOLoop\->acceptor($id)\->port;
.Ve
.SS singleton
.IX Subsection "singleton"
.Vb 1
\&  my $loop = Mojo::IOLoop\->singleton;
.Ve
.PP
The global Mojo::IOLoop singleton, used to access a single shared event loop object from everywhere inside the
process.
.PP
.Vb 3
\&  # Many methods also allow you to take shortcuts
\&  Mojo::IOLoop\->timer(2 => sub { Mojo::IOLoop\->stop });
\&  Mojo::IOLoop\->start;
\&
\&  # Restart active timer
\&  my $id = Mojo::IOLoop\->timer(3 => sub { say \*(AqTimeout!\*(Aq });
\&  Mojo::IOLoop\->singleton\->reactor\->again($id);
\&
\&  # Turn file descriptor into handle and watch if it becomes readable
\&  my $handle = IO::Handle\->new_from_fd($fd, \*(Aqr\*(Aq);
\&  Mojo::IOLoop\->singleton\->reactor\->io($handle => sub ($reactor, $writable) {
\&    say $writable ? \*(AqHandle is writable\*(Aq : \*(AqHandle is readable\*(Aq;
\&  })\->watch($handle, 1, 0);
.Ve
.SS start
.IX Subsection "start"
.Vb 2
\&  Mojo::IOLoop\->start;
\&  $loop\->start;
.Ve
.PP
Start the event loop, this will block until "stop" is called. Note that some reactors stop automatically if there
are no events being watched anymore.
.PP
.Vb 2
\&  # Start event loop only if it is not running already
\&  Mojo::IOLoop\->start unless Mojo::IOLoop\->is_running;
.Ve
.SS stop
.IX Subsection "stop"
.Vb 2
\&  Mojo::IOLoop\->stop;
\&  $loop\->stop;
.Ve
.PP
Stop the event loop, this will not interrupt any existing connections and the event loop can be restarted by running
"start" again.
.SS stop_gracefully
.IX Subsection "stop_gracefully"
.Vb 2
\&  Mojo::IOLoop\->stop_gracefully;
\&  $loop\->stop_gracefully;
.Ve
.PP
Stop accepting new connections and wait for already accepted connections to be closed, before stopping the event loop.
.SS stream
.IX Subsection "stream"
.Vb 3
\&  my $stream = Mojo::IOLoop\->stream($id);
\&  my $stream = $loop\->stream($id);
\&  my $id     = $loop\->stream(Mojo::IOLoop::Stream\->new);
.Ve
.PP
Get Mojo::IOLoop::Stream object for id or turn object into a connection.
.PP
.Vb 2
\&  # Increase inactivity timeout for connection to 300 seconds
\&  Mojo::IOLoop\->stream($id)\->timeout(300);
.Ve
.SS subprocess
.IX Subsection "subprocess"
.Vb 3
\&  my $subprocess = Mojo::IOLoop\->subprocess;
\&  my $subprocess = $loop\->subprocess;
\&  my $subprocess = $loop\->subprocess(sub ($subprocess) {...}, sub ($subprocess, $err, @results) {...});
.Ve
.PP
Build Mojo::IOLoop::Subprocess object to perform computationally expensive operations in subprocesses, without
blocking the event loop. Callbacks will be passed along to "run" in Mojo::IOLoop::Subprocess.
.PP
.Vb 9
\&  # Operation that would block the event loop for 5 seconds
\&  Mojo::IOLoop\->subprocess\->run_p(sub {
\&    sleep 5;
\&    return \*(Aq♥\*(Aq, \*(AqMojolicious\*(Aq;
\&  })\->then(sub (@results) {
\&    say "I $results[0] $results[1]!";
\&  })\->catch(sub ($err) {
\&    say "Subprocess error: $err";
\&  });
.Ve
.SS timer
.IX Subsection "timer"
.Vb 3
\&  my $id = Mojo::IOLoop\->timer(3 => sub ($loop) {...});
\&  my $id = $loop\->timer(0 => sub ($loop) {...});
\&  my $id = $loop\->timer(0.25 => sub ($loop) {...});
.Ve
.PP
Create a new timer, invoking the callback after a given amount of time in seconds.
.PP
.Vb 2
\&  # Perform operation in 5 seconds
\&  Mojo::IOLoop\->timer(5 => sub ($loop) {...});
.Ve
.SH DEBUGGING
.IX Header "DEBUGGING"
You can set the \f(CW\*(C`MOJO_IOLOOP_DEBUG\*(C'\fR environment variable to get some advanced diagnostics information printed to
\&\f(CW\*(C`STDERR\*(C'\fR.
.PP
.Vb 1
\&  MOJO_IOLOOP_DEBUG=1
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <https://mojolicious.org>.