diff options
Diffstat (limited to 'src/sys')
| -rw-r--r-- | src/sys/aio.rs | 643 |
1 files changed, 552 insertions, 91 deletions
diff --git a/src/sys/aio.rs b/src/sys/aio.rs index 687458e5..d5561e9c 100644 --- a/src/sys/aio.rs +++ b/src/sys/aio.rs @@ -1,3 +1,25 @@ +//! POSIX Asynchronous I/O +//! +//! The POSIX AIO interface is used for asynchronous I/O on files and disk-like +//! devices. It supports [`read`](struct.AioCb.html#method.read), +//! [`write`](struct.AioCb.html#method.write), and +//! [`fsync`](struct.AioCb.html#method.fsync) operations. Completion +//! notifications can optionally be delivered via +//! [signals](../signal/enum.SigevNotify.html#variant.SigevSignal), via the +//! [`aio_suspend`](fn.aio_suspend.html) function, or via polling. Some +//! platforms support other completion +//! notifications, such as +//! [kevent](../signal/enum.SigevNotify.html#variant.SigevKevent). +//! +//! Multiple operations may be submitted in a batch with +//! [`lio_listio`](fn.lio_listio.html), though the standard does not guarantee +//! that they will be executed atomically. +//! +//! Outstanding operations may be cancelled with +//! [`cancel`](struct.AioCb.html#method.cancel) or +//! [`aio_cancel_all`](fn.aio_cancel_all.html), though the operating system may +//! not support this for all filesystems and devices. + use {Error, Result}; use bytes::{Bytes, BytesMut}; use errno::Errno; @@ -13,9 +35,9 @@ use std::ptr::{null, null_mut}; use sys::signal::*; use sys::time::TimeSpec; -/// Mode for `AioCb::fsync`. Controls whether only data or both data and -/// metadata are synced. libc_enum! { + /// Mode for `AioCb::fsync`. Controls whether only data or both data and + /// metadata are synced. #[repr(i32)] pub enum AioFsyncMode { /// do it like `fsync` @@ -31,9 +53,9 @@ libc_enum! { } libc_enum! { - /// When used with `lio_listio`, determines whether a given `aiocb` should be - /// used for a read operation, a write operation, or ignored. Has no effect for - /// any other aio functions. + /// When used with [`lio_listio`](fn.lio_listio.html), determines whether a + /// given `aiocb` should be used for a read operation, a write operation, or + /// ignored. Has no effect for any other aio functions. #[repr(i32)] pub enum LioOpcode { LIO_NOP, @@ -43,18 +65,19 @@ libc_enum! { } libc_enum! { - /// Mode for `lio_listio`. + /// Mode for [`lio_listio`](fn.lio_listio.html) #[repr(i32)] pub enum LioMode { - /// Requests that `lio_listio` block until all requested operations have - /// been completed + /// Requests that [`lio_listio`](fn.lio_listio.html) block until all + /// requested operations have been completed LIO_WAIT, - /// Requests that `lio_listio` return immediately + /// Requests that [`lio_listio`](fn.lio_listio.html) return immediately LIO_NOWAIT, } } -/// Return values for `AioCb::cancel and aio_cancel_all` +/// Return values for [`AioCb::cancel`](struct.AioCb.html#method.cancel) and +/// [`aio_cancel_all`](fn.aio_cancel_all.html) #[repr(i32)] #[derive(Clone, Copy, Debug, PartialEq)] pub enum AioCancelStat { @@ -113,15 +136,20 @@ impl<'a> Buffer<'a> { } } -/// The basic structure used by all aio functions. Each `aiocb` represents one +/// AIO Control Block. +/// +/// The basic structure used by all aio functions. Each `AioCb` represents one /// I/O request. pub struct AioCb<'a> { aiocb: libc::aiocb, - /// Tracks whether the buffer pointed to by aiocb.aio_buf is mutable + /// Tracks whether the buffer pointed to by `libc::aiocb.aio_buf` is mutable mutable: bool, /// Could this `AioCb` potentially have any in-kernel state? in_progress: bool, - /// Used to keep buffers from Drop'ing + /// Optionally keeps a reference to the data. + /// + /// Used to keep buffers from `Drop`'ing, and may be returned once the + /// `AioCb` is completed by `into_buffer`. buffer: Buffer<'a> } @@ -146,11 +174,40 @@ impl<'a> AioCb<'a> { /// /// The resulting `AioCb` structure is suitable for use with `AioCb::fsync`. /// - /// * `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. + /// # 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`](#method.from_bytes_mut) operation. + /// + /// ``` + /// # extern crate tempfile; + /// # extern crate nix; + /// # use nix::errno::Errno; + /// # use nix::Error; + /// # use nix::sys::aio::*; + /// # use nix::sys::signal::SigevNotify::SigevNone; + /// # use std::{thread, time}; + /// # use std::os::unix::io::AsRawFd; + /// # use tempfile::tempfile; + /// # fn main() { + /// 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_fd(fd: RawFd, prio: libc::c_int, sigev_notify: SigevNotify) -> AioCb<'a> { let mut a = AioCb::common_init(fd, prio, sigev_notify); @@ -166,17 +223,65 @@ impl<'a> AioCb<'a> { } } - /// Constructs a new `AioCb`. + /// 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_bytes_mut`](#method.from_bytes_mut) instead. /// - /// * `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 + /// # 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. + /// + /// ``` + /// # extern crate tempfile; + /// # extern crate nix; + /// # use nix::errno::Errno; + /// # use nix::Error; + /// # use nix::sys::aio::*; + /// # use nix::sys::signal::SigevNotify; + /// # use std::{thread, time}; + /// # use std::io::Write; + /// # use std::os::unix::io::AsRawFd; + /// # use tempfile::tempfile; + /// # fn main() { + /// 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_mut_slice(fd: RawFd, offs: off_t, buf: &'a mut [u8], prio: libc::c_int, sigev_notify: SigevNotify, opcode: LioOpcode) -> AioCb<'a> { @@ -194,24 +299,62 @@ impl<'a> AioCb<'a> { } } - /// Constructs a new `AioCb`. + /// Constructs a new `AioCb` from a `Bytes` object. /// - /// Unlike `from_mut_slice`, this method returns a structure suitable for + /// 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. /// - /// * `fd` File descriptor. Required for all aio functions. - /// * `offs` File offset - /// * `buf` A shared 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 + /// # Parameters + /// + /// * `fd`: File descriptor. Required for all aio functions. + /// * `offs`: File offset + /// * `buf`: A shared 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 `Bytes` object and use it for writing. + /// + /// ``` + /// # extern crate bytes; + /// # extern crate tempfile; + /// # extern crate nix; + /// # use nix::errno::Errno; + /// # use nix::Error; + /// # use bytes::Bytes; + /// # use nix::sys::aio::*; + /// # use nix::sys::signal::SigevNotify; + /// # use std::{thread, time}; + /// # use std::io::Write; + /// # use std::os::unix::io::AsRawFd; + /// # use tempfile::tempfile; + /// # fn main() { + /// let wbuf = Bytes::from(&b"CDEF"[..]); + /// let mut f = tempfile().unwrap(); + /// let mut aiocb = AioCb::from_bytes( f.as_raw_fd(), + /// 2, //offset + /// wbuf.clone(), + /// 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 from_bytes(fd: RawFd, offs: off_t, buf: Bytes, prio: libc::c_int, sigev_notify: SigevNotify, - opcode: LioOpcode) -> AioCb<'a> { + opcode: LioOpcode) -> AioCb<'a> { // Small BytesMuts are stored inline. Inline storage is a no-no, // because we store a pointer to the buffer in the AioCb before // returning the Buffer by move. If the buffer is too small, reallocate @@ -240,20 +383,66 @@ impl<'a> AioCb<'a> { } } - /// Constructs a new `AioCb`. + /// Constructs a new `AioCb` from a `BytesMut` object. /// /// Unlike `from_mut_slice`, this method returns a structure suitable for /// placement on the heap. It may be used for both reads and writes. /// - /// * `fd` File descriptor. Required for all aio functions. - /// * `offs` File offset - /// * `buf` A shared 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 + /// # Parameters + /// + /// * `fd`: File descriptor. Required for all aio functions. + /// * `offs`: File offset + /// * `buf`: An owned 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 `BytesMut` and use it for reading. In this + /// example the `AioCb` is stack-allocated, so we could've used + /// `from_mut_slice` instead. + /// + /// ``` + /// # extern crate bytes; + /// # extern crate tempfile; + /// # extern crate nix; + /// # use nix::errno::Errno; + /// # use nix::Error; + /// # use bytes::BytesMut; + /// # use nix::sys::aio::*; + /// # use nix::sys::signal::SigevNotify; + /// # use std::{thread, time}; + /// # use std::io::Write; + /// # use std::os::unix::io::AsRawFd; + /// # use tempfile::tempfile; + /// # fn main() { + /// const INITIAL: &[u8] = b"abcdef123456"; + /// const LEN: usize = 4; + /// let rbuf = BytesMut::from(vec![0; LEN]); + /// let mut f = tempfile().unwrap(); + /// f.write_all(INITIAL).unwrap(); + /// let mut aiocb = AioCb::from_bytes_mut( 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 buffer = aiocb.into_buffer(); + /// const EXPECT: &[u8] = b"cdef"; + /// assert_eq!(buffer.bytes_mut().unwrap(), EXPECT); + /// # } + /// ``` pub fn from_bytes_mut(fd: RawFd, offs: off_t, buf: BytesMut, prio: libc::c_int, sigev_notify: SigevNotify, opcode: LioOpcode) -> AioCb<'a> { @@ -281,22 +470,31 @@ impl<'a> AioCb<'a> { /// Constructs a new `AioCb` from a mutable raw pointer /// - /// * `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 + /// 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 + /// converted to a `BytesMut`. + /// + /// # 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 /// - /// Unsafe because using this `AioCb` will cause `libc::aio_read` or - /// `libc::aio_write` to dereference a raw pointer, without type, bounds, or - /// lifetime checking. + /// 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_mut_ptr(fd: RawFd, offs: off_t, buf: *mut c_void, len: usize, prio: libc::c_int, sigev_notify: SigevNotify, @@ -315,23 +513,32 @@ impl<'a> AioCb<'a> { } } - /// Constructs a new `AioCb` from a raw pointer + /// 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 converted to a `Bytes`. /// - /// * `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 + /// # 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 /// - /// Unsafe because using this `AioCb` will cause `libc::aio_write` to - /// dereference a raw pointer, without type, bounds, or lifetime checking. + /// 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, @@ -357,14 +564,44 @@ impl<'a> AioCb<'a> { /// /// 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 + /// 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. + /// + /// ``` + /// # extern crate tempfile; + /// # extern crate nix; + /// # use nix::errno::Errno; + /// # use nix::Error; + /// # use nix::sys::aio::*; + /// # use nix::sys::signal::SigevNotify; + /// # use std::{thread, time}; + /// # use std::os::unix::io::AsRawFd; + /// # use tempfile::tempfile; + /// # fn main() { + /// 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()); + /// # } + /// ``` // Note: another solution to the problem of writing const buffers would be // to genericize AioCb for both &mut [u8] and &[u8] buffers. AioCb::read // could take the former and AioCb::write could take the latter. However, // then lio_listio wouldn't work, because that function needs a slice of - // AioCb, and they must all be the same type. We're basically stuck with - // using an unsafe function, since aio (as designed in C) is an unsafe API. + // AioCb, and they must all be of the same type. pub fn from_slice(fd: RawFd, offs: off_t, buf: &'a [u8], prio: libc::c_int, sigev_notify: SigevNotify, opcode: LioOpcode) -> AioCb { @@ -418,6 +655,56 @@ impl<'a> AioCb<'a> { } /// 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. + /// + /// ``` + /// # extern crate bytes; + /// # extern crate tempfile; + /// # extern crate nix; + /// # use nix::errno::Errno; + /// # use nix::Error; + /// # use bytes::Bytes; + /// # use nix::sys::aio::*; + /// # use nix::sys::signal::SigevNotify; + /// # use std::{thread, time}; + /// # use std::io::Write; + /// # use std::os::unix::io::AsRawFd; + /// # use tempfile::tempfile; + /// # fn main() { + /// let wbuf = Bytes::from(&b"CDEF"[..]); + /// let mut f = tempfile().unwrap(); + /// let mut aiocb = AioCb::from_bytes( f.as_raw_fd(), + /// 2, //offset + /// wbuf.clone(), + /// 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](http://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_cancel.html) pub fn cancel(&mut self) -> Result<AioCancelStat> { match unsafe { libc::aio_cancel(self.aiocb.aio_fildes, &mut self.aiocb) } { libc::AIO_CANCELED => Ok(AioCancelStat::AioCanceled), @@ -428,9 +715,46 @@ impl<'a> AioCb<'a> { } } - /// Retrieve error status of an asynchronous operation. If the request has - /// not yet completed, returns `EINPROGRESS`. Otherwise, returns `Ok` or - /// any other error. + /// 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. + /// + /// ``` + /// # extern crate tempfile; + /// # extern crate nix; + /// # use nix::errno::Errno; + /// # use nix::Error; + /// # use nix::sys::aio::*; + /// # use nix::sys::signal::SigevNotify; + /// # use std::{thread, time}; + /// # use std::os::unix::io::AsRawFd; + /// # use tempfile::tempfile; + /// # fn main() { + /// 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](http://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_error.html) pub fn error(&mut self) -> Result<()> { match unsafe { libc::aio_error(&mut self.aiocb as *mut libc::aiocb) } { 0 => Ok(()), @@ -440,7 +764,11 @@ impl<'a> AioCb<'a> { } } - /// An asynchronous version of `fsync`. + /// An asynchronous version of `fsync(2)`. + /// + /// # References + /// + /// [aio_fsync](http://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_fsync.html) pub fn fsync(&mut self, mode: AioFsyncMode) -> Result<()> { let p: *mut libc::aiocb = &mut self.aiocb; Errno::result(unsafe { @@ -483,6 +811,10 @@ impl<'a> AioCb<'a> { } /// Asynchronously reads from a file descriptor into a buffer + /// + /// # References + /// + /// [aio_read](http://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_read.html) pub fn read(&mut self) -> Result<()> { assert!(self.mutable, "Can't read into an immutable buffer"); let p: *mut libc::aiocb = &mut self.aiocb; @@ -498,9 +830,15 @@ impl<'a> AioCb<'a> { SigEvent::from(&self.aiocb.aio_sigevent) } - /// 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 `read`, `write`, of `fsync`. + /// 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](http://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_return.html) // Note: this should be just `return`, but that's a reserved word pub fn aio_return(&mut self) -> Result<isize> { let p: *mut libc::aiocb = &mut self.aiocb; @@ -509,6 +847,10 @@ impl<'a> AioCb<'a> { } /// Asynchronously writes from a buffer to a file descriptor + /// + /// # References + /// + /// [aio_write](http://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_write.html) pub fn write(&mut self) -> Result<()> { let p: *mut libc::aiocb = &mut self.aiocb; Errno::result(unsafe { @@ -520,7 +862,50 @@ impl<'a> AioCb<'a> { } -/// Cancels outstanding AIO requests. All requests for `fd` will be cancelled. +/// Cancels outstanding AIO requests for a given file descriptor. +/// +/// # Examples +/// +/// Issue an aio operation, then cancel all outstanding operations on that file +/// descriptor. +/// +/// ``` +/// # extern crate bytes; +/// # extern crate tempfile; +/// # extern crate nix; +/// # use nix::errno::Errno; +/// # use nix::Error; +/// # use bytes::Bytes; +/// # use nix::sys::aio::*; +/// # use nix::sys::signal::SigevNotify; +/// # use std::{thread, time}; +/// # use std::io::Write; +/// # use std::os::unix::io::AsRawFd; +/// # use tempfile::tempfile; +/// # fn main() { +/// let wbuf = Bytes::from(&b"CDEF"[..]); +/// let mut f = tempfile().unwrap(); +/// let mut aiocb = AioCb::from_bytes( f.as_raw_fd(), +/// 2, //offset +/// wbuf.clone(), +/// 0, //priority +/// SigevNotify::SigevNone, +/// LioOpcode::LIO_NOP); +/// aiocb.write().unwrap(); +/// let cs = aio_cancel_all(f.as_raw_fd()).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`](http://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_cancel.html) pub fn aio_cancel_all(fd: RawFd) -> Result<AioCancelStat> { match unsafe { libc::aio_cancel(fd, null_mut()) } { libc::AIO_CANCELED => Ok(AioCancelStat::AioCanceled), @@ -532,8 +917,42 @@ pub fn aio_cancel_all(fd: RawFd) -> Result<AioCancelStat> { } /// Suspends the calling process until at least one of the specified `AioCb`s -/// has completed, a signal is delivered, or the timeout has passed. If -/// `timeout` is `None`, `aio_suspend` will block indefinitely. +/// has completed, a signal is delivered, or the timeout has passed. +/// +/// If `timeout` is `None`, `aio_suspend` will block indefinitely. +/// +/// # Examples +/// +/// Use `aio_suspend` to block until an aio operation completes. +/// +// Disable doctest due to a known bug in FreeBSD's 32-bit emulation. The fix +// will be included in release 11.2. +// FIXME reenable the doc test when the CI machine gets upgraded to that release. +// https://svnweb.freebsd.org/base?view=revision&revision=325018 +/// ```no_run +/// # extern crate tempfile; +/// # extern crate nix; +/// # use nix::sys::aio::*; +/// # use nix::sys::signal::SigevNotify; +/// # use std::os::unix::io::AsRawFd; +/// # use tempfile::tempfile; +/// # fn main() { +/// 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(); +/// aio_suspend(&[&aiocb], None).expect("aio_suspend failed"); +/// assert_eq!(aiocb.aio_return().unwrap() as usize, WBUF.len()); +/// # } +/// ``` +/// # References +/// +/// [`aio_suspend`](http://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_suspend.html) pub fn aio_suspend(list: &[&AioCb], timeout: Option<TimeSpec>) -> Result<()> { let plist = list as *const [&AioCb] as *const [*const libc::aiocb]; let p = plist as *const *const libc::aiocb; @@ -547,8 +966,50 @@ pub fn aio_suspend(list: &[&AioCb], timeout: Option<TimeSpec>) -> Result<()> { } -/// Submits multiple asynchronous I/O requests with a single system call. The -/// order in which the requests are carried out is not specified. +/// Submits multiple asynchronous I/O requests with a single system call. +/// +/// They are not guaranteed to complete atomically, and the order in which the +/// requests are carried out is not specified. Reads, writes, and fsyncs may be +/// freely mixed. +/// +/// This function is useful for reducing the context-switch overhead of +/// submitting many AIO operations. It can also be used with +/// `LioMode::LIO_WAIT` to block on the result of several independent +/// operations. Used that way, it is often useful in programs that otherwise +/// make little use of AIO. +/// +/// # Examples +/// +/// Use `lio_listio` to submit an aio operation and wait for its completion. In +/// this case, there is no need to use `aio_suspend` to wait or `AioCb#error` to +/// poll. +/// +/// ``` +/// # extern crate tempfile; +/// # extern crate nix; +/// # use nix::sys::aio::*; +/// # use nix::sys::signal::SigevNotify; +/// # use std::os::unix::io::AsRawFd; +/// # use tempfile::tempfile; +/// # fn main() { +/// 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_WRITE); +/// lio_listio(LioMode::LIO_WAIT, +/// &[&mut aiocb], +/// SigevNotify::SigevNone).unwrap(); +/// assert_eq!(aiocb.aio_return().unwrap() as usize, WBUF.len()); +/// # } +/// ``` +/// +/// # References +/// +/// [`lio_listio`](http://pubs.opengroup.org/onlinepubs/9699919799/functions/lio_listio.html) #[cfg(not(any(target_os = "ios", target_os = "macos")))] pub fn lio_listio(mode: LioMode, list: &[&mut AioCb], sigev_notify: SigevNotify) -> Result<()> { |