Struct nix::sys::aio::AioCb

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

AIO Control Block.

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

Methods

impl<'a> AioCb<'a>

pub fn buffer(&mut self) -> Buffer<'a>

Remove the inner Buffer and return it

It is an error to call this method while the AioCb is still in progress.

pub fn boxed_slice(&mut self) -> Option<Box<dyn Borrow<[u8]>>>

Remove the inner boxed slice, if any, and return it.

The returned value will be the argument that was passed to from_boxed_slice when this AioCb was created.

It is an error to call this method while the AioCb is still in progress.

pub fn boxed_mut_slice(
    self: &mut Pin<Box<Self>>
) -> Option<Box<dyn BorrowMut<[u8]>>>

Remove the inner boxed mutable slice, if any, and return it.

The returned value will be the argument that was passed to from_boxed_mut_slice when this AioCb was created.

It is an error to call this method while the AioCb is still in progress.

pub fn fd(&self) -> RawFd

Returns the underlying file descriptor associated with the AioCb

pub fn from_fd(
    fd: RawFd,
    prio: 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(Error::from(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: 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. If the borrow checker gives you trouble, try using from_boxed_mut_slice instead.

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(Error::from(Errno::EINPROGRESS))) {
        thread::sleep(time::Duration::from_millis(10));
    }
    assert_eq!(aiocb.aio_return().unwrap() as usize, LEN);
}
assert_eq!(rbuf, b"cdef");

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

The safest and most flexible way to create an AioCb.

Unlike from_slice, this method returns a structure suitable for placement on the heap. It may be used for write operations, but not read operations. Unlike from_ptr, this method will ensure that the buffer doesn't drop while the kernel is still processing it. Any object that can be borrowed as a boxed slice will work.

Parameters

• fd: File descriptor. Required for all aio functions.
• offs: File offset
• buf: A boxed slice-like object
• 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 Vector and use it for writing

let wbuf = Box::new(Vec::from("CDEF"));
let expected_len = wbuf.len();
let mut f = tempfile().unwrap();
let mut aiocb = AioCb::from_boxed_slice( f.as_raw_fd(),
    2,   //offset
    wbuf,
    0,   //priority
    SigevNotify::SigevNone,
    LioOpcode::LIO_NOP);
aiocb.write().unwrap();
while (aiocb.error() == Err(Error::from(Errno::EINPROGRESS))) {
    thread::sleep(time::Duration::from_millis(10));
}
assert_eq!(aiocb.aio_return().unwrap() as usize, expected_len);

Create an AioCb from a Bytes object

let wbuf = Box::new(Bytes::from(&b"CDEF"[..]));
let mut f = tempfile().unwrap();
let mut aiocb = AioCb::from_boxed_slice( f.as_raw_fd(),
    2,   //offset
    wbuf,
    0,   //priority
    SigevNotify::SigevNone,
    LioOpcode::LIO_NOP);

If a library needs to work with buffers that aren't Boxed, it can create a Boxed container for use with this method. Here's an example using an unBoxed Bytes object.

struct BytesContainer(Bytes);
impl Borrow<[u8]> for BytesContainer {
    fn borrow(&self) -> &[u8] {
        self.0.as_ref()
    }
}
fn main() {
    let wbuf = Bytes::from(&b"CDEF"[..]);
    let boxed_wbuf = Box::new(BytesContainer(wbuf));
    let mut f = tempfile().unwrap();
    let mut aiocb = AioCb::from_boxed_slice( f.as_raw_fd(),
        2,   //offset
        boxed_wbuf,
        0,   //priority
        SigevNotify::SigevNone,
        LioOpcode::LIO_NOP);
}

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

The safest and most flexible way to create an AioCb for reading.

Like from_boxed_slice, but the slice is a mutable one. More flexible than from_mut_slice, because a wide range of objects can be used.

Examples

Create an AioCb from a Vector and use it for reading

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

pub unsafe fn from_mut_ptr(
    fd: RawFd,
    offs: off_t,
    buf: *mut c_void,
    len: usize,
    prio: 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 but for some reason the data cannot be wrapped in a struct that implements BorrowMut<[u8]>

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: 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 but for some reason the data cannot be wrapped in a struct that implements Borrow<[u8]>

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: c_int,
    sigev_notify: SigevNotify,
    opcode: LioOpcode
) -> Pin<Box<AioCb>>

Like 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(Error::from(Errno::EINPROGRESS))) {
    thread::sleep(time::Duration::from_millis(10));
}
assert_eq!(aiocb.aio_return().unwrap() as usize, WBUF.len());

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

Update the notification settings for an existing aiocb

pub fn cancel(self: &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(Error::from(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(self: &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(Error::from(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(self: &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) -> c_int

Returns the priority of the AioCb

pub fn read(self: &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(self: &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(self: &mut Pin<Box<Self>>) -> Result<()>

Asynchronously writes from a buffer to a file descriptor

References

aio_write

Trait Implementations

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

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

fn fmt(&self, fmt: &mut Formatter) -> Result

Formats the value using the given formatter.