/ 
Linux-Perl-0.16-TRIAL3
River stage zero No dependents
/ Linux::Perl::aio

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.