NAME

Linux:Perl::aio - asynchronous I/O

SYNOPSIS

    #Platform-specific invocation uses e.g.:
    #   Linux::Perl::aio::x86_64->new(...)
    #   Linux::Perl::aio::Control::x86_64->new(...)

    my $aio = Linux::Perl::aio->new(16);

    my $ctrl = Linux::Perl::aio::Control->new(
        $filehandle,
        \$buffer,
        lio_opcode => 'PREAD',
    );

    #Multiple $ctrl objects can be submitted in a list.
    $aio->submit($ctrl);

    my @events = $aio->getevents( $min, $max, $timeout );

DESCRIPTION

This module provides support for the kernel-level AIO interface.

DESTROY handlers are provided for automatic reaping of unused instances/contexts.

This module is EXPERIMENTAL. For now only the x86_64 architecture is supported; others may follow, though 32-bit architectures would take a bit more work.

METHODS

CLASS->new( NR_EVENTS )

Calls io_setup with the referred number of events to create an AIO context. An object of CLASS is returned.

CLASS->create_control( FILEHANDLE, BUFFER_SR, %OPTS )

Returns an instance of the relevant Linux::Perl::aio::Control subclass for your architecture.

FILEHANDLE is a Perl filehandle object, and BUFFER_SR is a reference to the buffer string. This buffer must be pre-initialized to at least the needed/desired length.

%OPTS is:

• lio_opcode: Required, one of: PREAD, PWRITE, FSYNC, FDSYNC, NOOP, PREADV, PWRITEV.

• buffer_offset: The byte offset in BUFFER_SR at which to start the I/O operation. Defaults to 0.

• nbytes: The number of bytes on which to operate. This value plus buffer_offset must be less than the length of BUFFER_SR. Defaults to length(BUFFER_SR) minus buffer_offset.

• rw_flags: Optional, an array reference of any or all of: HIPRI, DSYNC, SYNC, NOWAIT, APPEND. Not supported in all kernel versions; in fact, support seems more the exception than the rule! See the kernel documentation (e.g., RWF_HIPRI) for details on what these flags mean and whether your system supports them.

• reqprio: Optional. See the kernel’s documentation.

• eventfd: Optional, an eventfd file descriptor (i.e., unsigned integer) to receive updates when aio events are finished. (See Linux::Perl::eventfd for one way of making this work.)

For more information, consult the definition and documentation for struct iocb. (cf. include/linux/aio_abi.h)

$num = OBJ->submit( CTRL1, CTRL2, .. )

Calls io_submit. Each CTRL* is an instance of Linux::Perl::aio::Control and represets an I/O request.

The return value is the number of control objects submitted.

@events = OBJ->getevents( MIN, MAX, TIMEOUT )

Calls io_getevents with the relevant minimum, maximum, and timeout values. (TIMEOUT can be a float.)

If more than one event is requested (i.e., MAX > 1), then list context is required.

The return is a list of hash references; each hash reference has the following values as in the kernel io_event struct:

• data

• obj (corresponds to the Control instance id())

• res

• res2

NAME

Linux::Perl::aio::Control

SYNOPSIS

    my $ctrl = Linux::Perl::aio::Control->new(
        $filehandle,
        \$buffer,
        lio_opcode => 'PREAD',
        buffer_offset => 4,
        nbytes => 2,
    );

DESCRIPTION

This class encapsulates a kernel iocb struct, i.e., an I/O request.

You should not instantiate it directly; instead, use Linux::Perl::aio’s create_control() method.

METHODS

CLASS->new( FILEHANDLE, BUFFER_SR, %OPTS )

$sref = OBJ->buffer_sr()

Returns the string buffer reference given originally to new().

$sref = OBJ->pointer()

Returns the internal iocb’s memory address as an octet string.

$sref = OBJ->id()

Returns the internal iocb’s ID.

cpanm Linux::Perl

perl -MCPAN -e shell
install Linux::Perl