NAME
IO::URing - Access the io_uring interface from Raku
SYNOPSIS
Sample NOP call
use IO::URing;
my IO::URing $ring .= new(:8entries, :0flags);
my $data = await $ring.nop(1);
# or
react whenever $ring.nop(1) -> $data {
say "data: {$data.raku}";
}
}
$ring.close; # free the ring
DESCRIPTION
IO::URing is a binding to the new io_uring interface in the Linux kernel.
It will only work on Linux 5.6 and above. Use 5.10 or higher for best results. See the io_uring documentation for which operations are supported on your kernel version.
See the included IO::URing::Socket libraries for an example of IO::URing in action.
Some knowledge of io_uring and liburing is a pre-requisite for using this library. This code uses liburing to set up and submit requests to the ring.
IO::URing internal classes
class IO::URing::Completion
A Completion is returned from an awaited Handle. The completion contains the result of the operation.
has Mu $.data
The user data passed into the submission.
has io_uring_sqe $.request
The request passed into the IO::URing.
has int $.result
The result of the operation.
class IO::URing::Handle
A Handle is a Promise that can be used to cancel an IO::URing operation. Every call to submit or any non-prep operation will return a Handle.
IO::URing
IO::URing methods
method close
method close() returns Mu
Close the IO::URing object and shut down event processing.
method features
method features() returns Mu
Get the enabled features on this IO::URing.
method prep-nop
method prep-nop(
Int :$ioprio = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a no-op operation.
method nop
method nop(
|c
) returns IO::URing::Handle
Prepare and submit a no-op operation.
multi method prep-readv
multi method prep-readv(
Int $fd,
@bufs,
Int :$offset = 0,
:$data,
Int :$ioprio = 0,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a readv operation. A multi will handle a non-Int $fd by calling native-descriptor. A multi with a @bufs slurpy is provided.
method readv
method readv(
|c
) returns IO::URing::Handle
Prepare and submit a readv operation. See prep-readv for details.
multi method prep-writev
multi method prep-writev(
Int $fd,
@bufs,
Int :$offset = 0,
Int :$ioprio = 0,
:$data,
:$enc = "utf-8",
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a writev operation. A multi will handle a non-Int $fd by calling native-descriptor. A multi with a @bufs slurpy is provided.
method writev
method writev(
|c
) returns IO::URing::Handle
Prepare and submit a writev operation. See prep-writev for details.
multi method prep-fsync
multi method prep-fsync(
Int $fd,
Int $fsync-flags where { ... } = 0,
Int :$ioprio = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare an fsync operation. fsync-flags can be set to IORING_FSYNC_DATASYNC to use fdatasync(2) instead. Defaults to fsync(2).
method fsync
method fsync(
$fd,
Int $fsync-flags where { ... } = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit an fsync operation. See prep-fsync for details.
multi method prep-poll-add
multi method prep-poll-add(
Int $fd,
Int $poll-mask where { ... },
Int :$ioprio = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a poll-add operation. A multi will handle a non-Int $fd by calling native-descriptor.
method poll-add
method poll-add(
$fd,
Int $poll-mask where { ... },
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a poll-add operation. See prep-poll-add for details.
method prep-poll-remove
method prep-poll-remove(
IO::URing::Handle $slot,
Int :$ioprio = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a poll-remove operation. The provided Handle must be the Handle returned by the poll-add operation that should be cancelled.
method poll-remove
method poll-remove(
IO::URing::Handle $slot,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a poll-remove operation.
multi method prep-sendto
multi method prep-sendto(
Int $fd,
Str $str,
Int $union-flags,
sockaddr_role $addr,
Int $len,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async,
:$enc = "utf-8"
) returns IO::URing::Handle
Prepare a sendmsg operation, mimicking sendto(2). A multi is provided that takes Blobs. A multi will handle a non-Int $fd by calling native-descriptor.
multi method sendto
multi method sendto(
Int $fd,
Blob $blob,
Int $union-flags,
sockaddr_role $addr,
Int $len,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a sendmsg operation, mimicking sendto(2).
multi method prep-sendmsg
multi method prep-sendmsg(
Int $fd,
msghdr:D $msg,
$union-flags,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a sendmsg operation. A multi will handle a non-Int $fd by calling native-descriptor.
method sendmsg
method sendmsg(
$fd,
msghdr:D $msg,
$flags,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a sendmsg operation.
multi method prep-recvfrom
multi method prep-recvfrom(
Int $fd,
Blob $buf,
$flags,
Blob $addr,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a recvmsg operation, mimicking recvfrom(2). A multi is provided that takes Blobs. A multi will handle a non-Int $fd by calling native-descriptor.
method recvfrom
method recvfrom(
$fd,
Blob $buf,
$flags,
Blob $addr,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a recvmsg operation, mimicking recvfrom(2).
multi method prep-recvmsg
multi method prep-recvmsg(
Int $fd,
msghdr:D $msg is rw,
$union-flags,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a recvmsg operation. A multi will handle a non-Int $fd by calling native-descriptor.
multi method recvmsg
multi method recvmsg(
Int $fd,
msghdr:D $msg is rw,
$flags,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a recvmsg operation
method prep-cancel
method prep-cancel(
IO::URing::Handle $slot,
Int $union-flags where { ... } = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a cancel operation to cancel a previously submitted operation. Note that this chases an in-flight operation, meaning it may or maybe not be successful in cancelling the operation. This means that both cases must be handled.
method cancel
method cancel(
IO::URing::Handle $slot,
Int :$flags where { ... } = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a cancel operation
multi method prep-accept
multi method prep-accept(
Int $fd,
$sockaddr = Str,
Int $union-flags = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare an accept operation. A multi will handle a non-Int $fd by calling native-descriptor.
method accept
method accept(
$fd,
$sockaddr?,
Int $union-flags = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit an accept operation.
multi method prep-connect
multi method prep-connect(
Int $fd,
sockaddr_role $sockaddr,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a connect operation. A multi will handle a non-Int $fd by calling native-descriptor.
method connect
method connect(
$fd,
sockaddr_role $sockaddr,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a connect operation.
multi method prep-send
multi method prep-send(
Int $fd,
Blob $buf,
$union-flags = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a send operation. A multi will handle a Str submission., which takes a named parameter :$enc = 'utf-8'. A multi will handle a non-Int $fd by calling native-descriptor.
multi method send
multi method send(
$fd,
$buf,
Int $flags = 0,
:$enc = "utf-8",
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a send operation.
multi method prep-recv
multi method prep-recv(
Int $fd,
Blob $buf,
Int $union-flags = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a recv operation. A multi will handle a non-Int $fd by calling native-descriptor.
multi method recv
multi method recv(
$fd,
Blob $buf,
Int $union-flags = 0,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a recv operation.
multi method prep-close-fd
multi method prep-close-fd(
Int $fd,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare a close operation. A multi will handle a non-Int $fd by calling native-descriptor.
method close-fd
method close-fd(
Int $fd,
:$data,
:$drain,
:$link,
:$hard-link,
:$force-async
) returns IO::URing::Handle
Prepare and submit a close operation.
multi method supported-ops
multi method supported-ops() returns Hash
Get the supported operations on an IO::URing instance.
multi method supported-ops
multi method supported-ops() returns Hash
Get the supported operations without an IO::URing instance.
AUTHOR
Travis Gibson TGib.Travis@protonmail.com
COPYRIGHT AND LICENSE
Copyright 2021 Travis Gibson
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
Some of the subs in this library were translated from liburing into Raku. Liburing is licensed under a dual LGPL and MIT license. Thank you Axboe for this library and interface.