Struct nix::sys::aio::AioCb

pub struct AioCb<'a> { /* fields hidden */ }

Documentation

AIO Control Block.

The basic structure used by all aio functions. Each AioCb represents one I/O request.

Implementations

impl<'a> AioCb<'a>

pub fn fd(&Self) -> RawFd

Returns the underlying file descriptor associated with the AioCb

pub fn from_fd(
    fd: RawFd,
    prio: libc::c_int,
    sigev_notify: SigevNotify
) -> Pin<Box<AioCb<'a>>>

Constructs a new AioCb with no associated buffer.

The resulting AioCb structure is suitable for use with AioCb::fsync.

Parameters

fd: File descriptor. Required for all aio functions.
prio: If POSIX Prioritized IO is supported, then the operation will be prioritized at the process’s priority level minus prio.
sigev_notify: Determines how you will be notified of event completion.

Examples

Create an AioCb from a raw file descriptor and use it for an fsync operation.

let f = tempfile().unwrap();
let mut aiocb = AioCb::from_fd( f.as_raw_fd(), 0, SigevNone);
aiocb.fsync(AioFsyncMode::O_SYNC).expect("aio_fsync failed early");
while (aiocb.error() == Err(Errno::EINPROGRESS)) {
    thread::sleep(time::Duration::from_millis(10));
}
aiocb.aio_return().expect("aio_fsync failed late");

pub fn from_mut_slice(
    fd: RawFd,
    offs: off_t,
    buf: &'a mut [u8],
    prio: libc::c_int,
    sigev_notify: SigevNotify,
    opcode: LioOpcode
) -> Pin<Box<AioCb<'a>>>

Constructs a new AioCb from a mutable slice.

The resulting AioCb will be suitable for both read and write operations, but only if the borrow checker can guarantee that the slice will outlive the AioCb. That will usually be the case if the AioCb is stack-allocated.

Parameters

fd: File descriptor. Required for all aio functions.
offs: File offset
buf: A memory buffer
prio: If POSIX Prioritized IO is supported, then the operation will be prioritized at the process’s priority level minus prio
sigev_notify: Determines how you will be notified of event completion.
opcode: This field is only used for lio_listio. It determines which operation to use for this individual aiocb

Examples

Create an AioCb from a mutable slice and read into it.

const INITIAL: &[u8] = b"abcdef123456";
const LEN: usize = 4;
let mut rbuf = vec![0; LEN];
let mut f = tempfile().unwrap();
f.write_all(INITIAL).unwrap();
{
    let mut aiocb = AioCb::from_mut_slice( f.as_raw_fd(),
        2,   //offset
        &mut rbuf,
        0,   //priority
        SigevNotify::SigevNone,
        LioOpcode::LIO_NOP);
    aiocb.read().unwrap();
    while (aiocb.error() == Err(Errno::EINPROGRESS)) {
        thread::sleep(time::Duration::from_millis(10));
    }
    assert_eq!(aiocb.aio_return().unwrap() as usize, LEN);
}
assert_eq!(rbuf, b"cdef");

pub unsafe fn from_mut_ptr(
    fd: RawFd,
    offs: off_t,
    buf: *mut c_void,
    len: usize,
    prio: libc::c_int,
    sigev_notify: SigevNotify,
    opcode: LioOpcode
) -> Pin<Box<AioCb<'a>>>

Constructs a new AioCb from a mutable raw pointer

Unlike from_mut_slice, this method returns a structure suitable for placement on the heap. It may be used for both reads and writes. Due to its unsafety, this method is not recommended. It is most useful when heap allocation is required.

Parameters

fd: File descriptor. Required for all aio functions.
offs: File offset
buf: Pointer to the memory buffer
len: Length of the buffer pointed to by buf
prio: If POSIX Prioritized IO is supported, then the operation will be prioritized at the process’s priority level minus prio
sigev_notify: Determines how you will be notified of event completion.
opcode: This field is only used for lio_listio. It determines which operation to use for this individual aiocb

Safety

The caller must ensure that the storage pointed to by buf outlives the AioCb. The lifetime checker can’t help here.

pub unsafe fn from_ptr(
    fd: RawFd,
    offs: off_t,
    buf: *const c_void,
    len: usize,
    prio: libc::c_int,
    sigev_notify: SigevNotify,
    opcode: LioOpcode
) -> Pin<Box<AioCb<'a>>>

Constructs a new AioCb from a raw pointer.

Unlike from_slice, this method returns a structure suitable for placement on the heap. Due to its unsafety, this method is not recommended. It is most useful when heap allocation is required.

Parameters

fd: File descriptor. Required for all aio functions.
offs: File offset
buf: Pointer to the memory buffer
len: Length of the buffer pointed to by buf
prio: If POSIX Prioritized IO is supported, then the operation will be prioritized at the process’s priority level minus prio
sigev_notify: Determines how you will be notified of event completion.
opcode: This field is only used for lio_listio. It determines which operation to use for this individual aiocb

Safety

The caller must ensure that the storage pointed to by buf outlives the AioCb. The lifetime checker can’t help here.

pub fn from_slice(
    fd: RawFd,
    offs: off_t,
    buf: &'a [u8],
    prio: libc::c_int,
    sigev_notify: SigevNotify,
    opcode: LioOpcode
) -> Pin<Box<AioCb<'_>>>

Like AioCb::from_mut_slice, but works on constant slices rather than mutable slices.

An AioCb created this way cannot be used with read, and its LioOpcode cannot be set to LIO_READ. This method is useful when writing a const buffer with AioCb::write, since from_mut_slice can’t work with const buffers.

Examples

Construct an AioCb from a slice and use it for writing.

const WBUF: &[u8] = b"abcdef123456";
let mut f = tempfile().unwrap();
let mut aiocb = AioCb::from_slice( f.as_raw_fd(),
    2,   //offset
    WBUF,
    0,   //priority
    SigevNotify::SigevNone,
    LioOpcode::LIO_NOP);
aiocb.write().unwrap();
while (aiocb.error() == Err(Errno::EINPROGRESS)) {
    thread::sleep(time::Duration::from_millis(10));
}
assert_eq!(aiocb.aio_return().unwrap() as usize, WBUF.len());

pub fn set_sigev_notify(&mut Pin<Box<Self>>, sigev_notify: SigevNotify)

Update the notification settings for an existing aiocb

pub fn cancel(&mut Pin<Box<Self>>) -> Result<AioCancelStat>

Cancels an outstanding AIO request.

The operating system is not required to implement cancellation for all file and device types. Even if it does, there is no guarantee that the operation has not already completed. So the caller must check the result and handle operations that were not canceled or that have already completed.

Examples

Cancel an outstanding aio operation. Note that we must still call aio_return to free resources, even though we don’t care about the result.

let wbuf = b"CDEF";
let mut f = tempfile().unwrap();
let mut aiocb = AioCb::from_slice( f.as_raw_fd(),
    2,   //offset
    &wbuf[..],
    0,   //priority
    SigevNotify::SigevNone,
    LioOpcode::LIO_NOP);
aiocb.write().unwrap();
let cs = aiocb.cancel().unwrap();
if cs == AioCancelStat::AioNotCanceled {
    while (aiocb.error() == Err(Errno::EINPROGRESS)) {
        thread::sleep(time::Duration::from_millis(10));
    }
}
// Must call `aio_return`, but ignore the result
let _ = aiocb.aio_return();

References

aio_cancel

pub fn error(&mut Pin<Box<Self>>) -> Result<()>

Retrieve error status of an asynchronous operation.

If the request has not yet completed, returns EINPROGRESS. Otherwise, returns Ok or any other error.

Examples

Issue an aio operation and use error to poll for completion. Polling is an alternative to aio_suspend, used by most of the other examples.

const WBUF: &[u8] = b"abcdef123456";
let mut f = tempfile().unwrap();
let mut aiocb = AioCb::from_slice( f.as_raw_fd(),
    2,   //offset
    WBUF,
    0,   //priority
    SigevNotify::SigevNone,
    LioOpcode::LIO_NOP);
aiocb.write().unwrap();
while (aiocb.error() == Err(Errno::EINPROGRESS)) {
    thread::sleep(time::Duration::from_millis(10));
}
assert_eq!(aiocb.aio_return().unwrap() as usize, WBUF.len());

References

aio_error

pub fn fsync(&mut Pin<Box<Self>>, mode: AioFsyncMode) -> Result<()>

An asynchronous version of fsync(2).

References

aio_fsync

pub fn lio_opcode(&Self) -> Option<LioOpcode>

Returns the aiocb’s LioOpcode field

If the value cannot be represented as an LioOpcode, returns None instead.

pub fn nbytes(&Self) -> usize

Returns the requested length of the aio operation in bytes

This method returns the requested length of the operation. To get the number of bytes actually read or written by a completed operation, use aio_return instead.

pub fn offset(&Self) -> off_t

Returns the file offset stored in the AioCb

pub fn priority(&Self) -> libc::c_int

Returns the priority of the AioCb

pub fn read(&mut Pin<Box<Self>>) -> Result<()>

Asynchronously reads from a file descriptor into a buffer

References

aio_read

pub fn sigevent(&Self) -> SigEvent

Returns the SigEvent stored in the AioCb

pub fn aio_return(&mut Pin<Box<Self>>) -> Result<isize>

Retrieve return status of an asynchronous operation.

Should only be called once for each AioCb, after AioCb::error indicates that it has completed. The result is the same as for the synchronous read(2), write(2), of fsync(2) functions.

References

aio_return

pub fn write(&mut Pin<Box<Self>>) -> Result<()>

Asynchronously writes from a buffer to a file descriptor

References

aio_write

Trait Implementations

impl<'a> Debug for AioCb<'a>

fn fmt(&Self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result

impl<'a> Drop for AioCb<'a>

fn drop(&mut Self)

If the AioCb has no remaining state in the kernel, just drop it. Otherwise, dropping constitutes a resource leak, which is an error

Auto Trait Implementations

impl<'a> !Unpin for AioCb<'a>

impl<'a> RefUnwindSafe for AioCb<'a>

impl<'a> Send for AioCb<'a>

impl<'a> Sync for AioCb<'a>

impl<'a> UnwindSafe for AioCb<'a>

Blanket Implementations

impl<T> Any for T
where
    T: 'static + ?Sized,

fn type_id(&Self) -> TypeId

impl<T> Borrow<T> for T
where
    T: ?Sized,

fn borrow(&Self) -> &T

impl<T> BorrowMut<T> for T
where
    T: ?Sized,

fn borrow_mut(&mut Self) -> &mut T

impl<T> From<T> for T

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into<U> for T
where
    U: From<T>,

fn into(Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl<T, U> TryFrom<U> for T
where
    U: Into<T>,

type Error = Infallible

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for T
where
    U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

fn try_into(Self) -> Result<U, <U as TryFrom<T>>::Error>