NAME
Mojo::IOLoop - Minimalistic Reactor For TCP Clients And Servers
SYNOPSIS
use Mojo::IOLoop;
# Create loop
my $loop = Mojo::IOLoop->new;
# Listen on port 3000
$loop->listen(
port => 3000,
cb => sub {
my ($self, $id) = @_;
# Start read only when accepting a new connection
$self->not_writing($id);
# Incoming data
$self->read_cb($id => sub {
my ($self, $id, $chunk) = @_;
# Got some data, time to write
$self->writing($id);
});
# Ready to write
$self->write_cb($id => sub {
my ($self, $id) = @_;
# Back to reading only
$self->not_writing($id);
# The loop will take care of buffering for us
return 'HTTP/1.1 200 OK';
});
}
);
# Connect to port 3000 with TLS activated
my $id = $loop->connect(address => 'localhost', port => 3000, tls => 1);
# Loop starts writing
$loop->writing($id);
# Writing request
$loop->write_cb($id => sub {
my ($self, $id) = @_;
# Back to reading only
$self->not_writing($id);
# The loop will take care of buffering for us
return "GET / HTTP/1.1\r\n\r\n";
});
# Reading response
$loop->read_cb($id => sub {
my ($self, $id, $chunk) = @_;
# Time to write more
$self->writing($id);
});
# Add a timer
$loop->timer(5 => sub {
my $self = shift;
$self->drop($id);
});
# Start and stop loop
$loop->start;
$loop->stop;DESCRIPTION
Mojo::IOLoop is a very minimalistic reactor that has been reduced to the absolute minimal feature set required to build solid and scalable TCP clients and servers.
Optional modules IO::KQueue, IO::Epoll, IO::Socket::INET6 and IO::Socket::SSL are supported transparently and used if installed.
ATTRIBUTES
Mojo::IOLoop implements the following attributes.
accept_timeout
my $timeout = $loop->accept_timeout;
$loop = $loop->accept_timeout(5);Maximum time in seconds a connection can take to be accepted before being dropped, defaults to 5.
connect_timeout
my $timeout = $loop->connect_timeout;
$loop = $loop->connect_timeout(5);Maximum time in seconds a conenction can take to be connected before being dropped, defaults to 5.
lock_cb
my $cb = $loop->lock_cb;
$loop = $loop->lock_cb(sub {...});A locking callback that decides if this loop is allowed to listen for new incoming connections, used to sync multiple server processes. The callback should return true or false.
$loop->lock_cb(sub {
my ($loop, $blocking) = @_;
# Got the lock, listen for new connections
return 1;
});max_connections
my $max = $loop->max_connections;
$loop = $loop->max_connections(1000);The maximum number of connections this loop is allowed to handle before stopping to accept new incoming connections, defaults to 1000. Setting the value to 0 will make this loop stop accepting new connections and allow it to shutdown gracefully without interrupting existing connections.
tick_cb
my $cb = $loop->tick_cb;
$loop = $loop->tick_cb(sub {...});Callback to be invoked on every reactor tick, this for example allows you to run multiple reactors next to each other.
timeout
my $timeout = $loop->timeout;
$loop = $loop->timeout(5);Maximum time in seconds our loop waits for new events to happen, defaults to 0.25.
unlock_cb
my $cb = $loop->unlock_cb;
$loop = $loop->unlock_cb(sub {...});A callback to free the listen lock, called after accepting a new connection and used to sync multiple server processes.
METHODS
Mojo::IOLoop inherits all methods from Mojo::Base and implements the following new ones.
new
my $loop = Mojo::IOLoop->new;Construct a new Mojo::IOLoop object. Multiple of these will block each other, so use singleton instead if possible.
connect
my $id = $loop->connect(
address => '127.0.0.1',
port => 3000,
cb => sub {...}
);
my $id = $loop->connect({
address => '127.0.0.1',
port => 3000,
cb => sub {...}
});
my $id = $loop->connect({
address => '[::1]',
port => 443,
tls => 1,
cb => sub {...}
});Open a TCP connection to a remote host, IPv6 will be used automatically if available. Note that IPv6 support depends on IO::Socket::INET6 and TLS support on IO::Socket::SSL.
These options are currently available.
address-
Address or host name of the peer to connect to.
cb-
Callback to be invoked once the connection is established.
port-
Port to connect to.
tls-
Enable TLS.
tls_ca_file-
CA file to use for TLS.
tls_verify_cb-
Callback to invoke for TLS verification.
connection_timeout
my $timeout = $loop->connection_timeout($id);
$loop = $loop->connection_timeout($id => 45);Maximum amount of time in seconds a connection can be inactive before being dropped.
drop
$loop = $loop->drop($id);Drop a connection, listen socket or timer. Connections will be dropped gracefully by allowing them to finish writing all data in it's write buffer.
error_cb
$loop = $loop->error_cb($id => sub {...});Callback to be invoked if an error event happens on the connection.
generate_port
my $port = $loop->generate_port;Find a free TCP port, this is a utility function primarily used for tests.
hup_cb
$loop = $loop->hup_cb($id => sub {...});Callback to be invoked if the connection gets closed.
is_running
my $running = $loop->is_running;Check if loop is running.
exit unless Mojo::IOLoop->singleton->is_running;listen
my $id = $loop->listen(port => 3000);
my $id = $loop->listen({port => 3000});
my $id = $loop->listen(file => '/foo/myapp.sock');
my $id = $loop->listen(
port => 443,
tls => 1,
tls_cert => '/foo/server.cert',
tls_key => '/foo/server.key'
);Create a new listen socket, IPv6 will be used automatically if available. Note that IPv6 support depends on IO::Socket::INET6 and TLS support on IO::Socket::SSL.
These options are currently available.
address-
Local address to listen on, defaults to all.
cb-
Callback to invoke for each accepted connection.
file-
A unix domain socket to listen on.
port-
Port to listen on.
queue_size-
Maximum queue size, defaults to
SOMAXCONN. tls-
Enable TLS.
tls_cert-
Path to the TLS cert file.
tls_key-
Path to the TLS key file.
local_info
my $info = $loop->local_info($id);Get local information about a connection.
my $address = $info->{address};These values are to be expected in the returned hash reference.
address-
The local address.
port-
The local port.
not_writing
$loop->not_writing($id);Activate read only mode for a connection. Note that connections have no mode after they are created.
one_tick
$loop->one_tick;Run reactor for exactly one tick.
read_cb
$loop = $loop->read_cb($id => sub {...});Callback to be invoked if new data arrives on the connection.
$loop->read_cb($id => sub {
my ($loop, $id, $chunk) = @_;
# Process chunk
});remote_info
my $info = $loop->remote_info($id);Get remote information about a connection.
my $address = $info->{address};These values are to be expected in the returned hash reference.
address-
The remote address.
port-
The remote port.
singleton
my $loop = Mojo::IOLoop->singleton;The global loop object, used to access a single shared loop instance from everywhere inside the process.
start
$loop->start;Start the loop, this will block until the loop is finished or return immediately if the loop is already running.
start_tls
my $id = $loop->start_tls($id);
my $id = $loop->start_tls($id => {tls_ca_file => '/etc/tls/cacerts.pem'});Start new TLS connection inside old connection. Note that TLS support depends on IO::Socket::SSL.
These options are currently available.
tls_ca_file-
CA file to use for TLS.
tls_verify_cb-
Callback to invoke for TLS verification.
stop
$loop->stop;Stop the loop immediately, this will not interrupt any existing connections and the loop can be restarted by running start again.
timer
my $id = $loop->timer(5 => sub {...});Create a new timer, invoking the callback afer a given amount of seconds.
write_cb
$loop = $loop->write_cb($id => sub {...});Callback to be invoked if new data can be written to the connection. The callback should return a chunk of data which will be buffered inside the loop to guarantee safe writing.
$loop->write_cb($id => sub {
my ($loop, $id) = @_;
return 'Data to be buffered by the loop!';
});writing
$loop->writing($id);Activate read/write mode for a connection. Note that connections have no mode after they are created.