NAME

Future::Uring::Handle - A Uring filehandle

VERSION

version 0.001

SYNOPSIS

while (1) {
  my $buffer = await $input->recv(512, timeout => 60);
  my $result = await $output->send($buffer, timeout => 10);
}

DESCRIPTION

This is a Future::Uring handle. It offers fully asynchronous IO on a filehandle. Generally speaking its methods are the same as their well known symmetric counterparts (e.g. send, listen), though some have subtly different semantics (e.g. poll taking only one filehandle).

METHODS

new

my $handle = Future::Uring::Handle->new($fh)

This will create a new Uring handle based on a Perl handle $fh.

inner

my $fh = $handle->inner;

This will return the Perl filehandle inside the Uring handle.

accept

my $conn = await $handle->accept(%options);

This will accept a new connection on a listening socket.

allocate

await $handle->allocate($offset, $length, %options)

This will allocate space in the file.

bind

await $handle->bind($sockaddr, %options)

Bind the socket to $sockaddr.

connect

await $handle->connect($sockaddr, %options)

Connect the socket to $sockaddr.

listen

await $handle->listen(%options);

Make the socket listen for new connections.

poll

my $mask = await $handle->poll(%options);

This will poll the filehandle, it takes the following additional options.

mask

The polling mask, defaulting to 0.
read

If true, it will add readability to the poll mask.
write

If true, it will add writeability to the poll mask.

You probably need either mask, or read/write. In any case, it will poll for hangup and other errors.

read

my $data = await $handle->read($size, %options)

This will read up to $size bytes from the handle.

It takes one additional named parameter, offset, for the optional offset in the file.

recv

my $data = await $handle->recv($size, %options)

Receive $size bytes of data from a socket.

This takes two additional named arguments.

poll_first.

If set io_uring will assume the socket is currently empty and attempting to receive data will be unsuccessful. For this case, io_uring will arm internal poll and trigger a receive of the data when the socket has data to be read. This initial receive attempt can be wasteful for the case where the socket is expected to be empty, setting this flag will bypass the initial receive attempt and go straight to arming poll. If poll does indicate that data is ready to be received, the operation will proceed.
flags

This is the standard recv flags argument (e.g. MSG_WAITALL, MSG_TRUNC).

send / sendto

await $handle->send($data, %options)
await $handle->sendto($data, $address, %options)

Send $data over a socket.

This takes two additional named arguments.

poll_first.

If set io_uring will assume the socket is currently full and attempting to send data will be unsuccessful. For this case, io_uring will arm internal poll and trigger a send of the data when the socket has space available. If poll does indicate that space is available in the socket, the operation will proceed immediately.
flags

This is the standard recv flags argument (e.g. MSG_WAITALL, MSG_TRUNC).

shutdown

await $handle->shutdown($how, %options)

This shuts down one half of a connection. It's $how argument takes the same values as the shutdown builtin.

splice

await $handle->splice($out, $nbytes, %options)

Splice data from the current handle to $out. Either the input or the output must be a pipe. It optionally takes two additional named parameters:

off_in

The offset in the input file
off_out

The offset in the output file

sync

await $handle->sync(%options)

This synchronizes a file to disk much like the fsync system call does.

This takes one additional named argument, datasync that makes it behave like fdatasync instead.

tee($out_fh, $nbytes, %options)

await $handle->tee($out, $nbytes, %options)

This copies $nbytes bytes from the current handle to $out.

truncate

await $handle->truncate($length, %options)

This truncates a file to $length bytes.

write

await $handle->write($data, %options)

This writes $data to $handle.