Debian Codegraph @

src/sys/aio.rs

raw
1 // vim: tw=80
2 //! POSIX Asynchronous I/O
3 //!
4 //! The POSIX AIO interface is used for asynchronous I/O on files and disk-like
5 //! devices. It supports [`read`](struct.AioRead.html#method.new),
6 //! [`write`](struct.AioWrite.html#method.new),
7 //! [`fsync`](struct.AioFsync.html#method.new),
8 //! [`readv`](struct.AioReadv.html#method.new), and
9 //! [`writev`](struct.AioWritev.html#method.new), operations, subject to
10 //! platform support. Completion
11 //! notifications can optionally be delivered via
12 //! [signals](../signal/enum.SigevNotify.html#variant.SigevSignal), via the
13 //! [`aio_suspend`](fn.aio_suspend.html) function, or via polling. Some
14 //! platforms support other completion
15 //! notifications, such as
16 //! [kevent](../signal/enum.SigevNotify.html#variant.SigevKevent).
17 //!
18 //! Multiple operations may be submitted in a batch with
19 //! [`lio_listio`](fn.lio_listio.html), though the standard does not guarantee
20 //! that they will be executed atomically.
21 //!
22 //! Outstanding operations may be cancelled with
23 //! [`cancel`](trait.Aio.html#method.cancel) or
24 //! [`aio_cancel_all`](fn.aio_cancel_all.html), though the operating system may
25 //! not support this for all filesystems and devices.
26 #[cfg(target_os = "freebsd")]
27 use std::io::{IoSlice, IoSliceMut};
28 use std::{
29 convert::TryFrom,
30 fmt::{self, Debug},
31 marker::{PhantomData, PhantomPinned},
32 mem,
33 os::unix::io::{AsFd, AsRawFd, BorrowedFd},
34 pin::Pin,
35 ptr, thread,
36 };
37
38 use libc::off_t;
39 use pin_utils::unsafe_pinned;
40
41 use crate::{
42 errno::Errno,
43 sys::{signal::*, time::TimeSpec},
44 Result,
45 };
46
47 libc_enum! {
48 /// Mode for `AioCb::fsync`. Controls whether only data or both data and
49 /// metadata are synced.
50 #[repr(i32)]
51 #[non_exhaustive]
52 pub enum AioFsyncMode {
53 /// do it like `fsync`
54 O_SYNC,
55 /// on supported operating systems only, do it like `fdatasync`
56 #[cfg(any(apple_targets,
57 target_os = "linux",
58 target_os = "freebsd",
59 netbsdlike))]
60 O_DSYNC
61 }
62 impl TryFrom<i32>
63 }
64
65 libc_enum! {
66 /// Mode for [`lio_listio`](fn.lio_listio.html)
67 #[repr(i32)]
68 pub enum LioMode {
69 /// Requests that [`lio_listio`](fn.lio_listio.html) block until all
70 /// requested operations have been completed
71 LIO_WAIT,
72 /// Requests that [`lio_listio`](fn.lio_listio.html) return immediately
73 LIO_NOWAIT,
74 }
75 }
76
77 /// Return values for [`AioCb::cancel`](struct.AioCb.html#method.cancel) and
78 /// [`aio_cancel_all`](fn.aio_cancel_all.html)
79 #[repr(i32)]
80 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
81 pub enum AioCancelStat {
82 /// All outstanding requests were canceled
83 AioCanceled = libc::AIO_CANCELED,
84 /// Some requests were not canceled. Their status should be checked with
85 /// `AioCb::error`
86 AioNotCanceled = libc::AIO_NOTCANCELED,
87 /// All of the requests have already finished
88 AioAllDone = libc::AIO_ALLDONE,
89 }
90
91 /// Newtype that adds Send and Sync to libc::aiocb, which contains raw pointers
92 #[repr(transparent)]
93 struct LibcAiocb(libc::aiocb);
94
95 unsafe impl Send for LibcAiocb {}
96 unsafe impl Sync for LibcAiocb {}
97
98 /// Base class for all AIO operations. Should only be used directly when
99 /// checking for completion.
100 // We could create some kind of AsPinnedMut trait, and implement it for all aio
101 // ops, allowing the crate's users to get pinned references to `AioCb`. That
102 // could save some code for things like polling methods. But IMHO it would
103 // provide polymorphism at the wrong level. Instead, the best place for
104 // polymorphism is at the level of `Futures`.
105 #[repr(C)]
106 struct AioCb<'a> {
107 aiocb: LibcAiocb,
108 /// Could this `AioCb` potentially have any in-kernel state?
109 // It would be really nice to perform the in-progress check entirely at
110 // compile time. But I can't figure out how, because:
111 // * Future::poll takes a `Pin<&mut self>` rather than `self`, and
112 // * Rust's lack of an equivalent of C++'s Guaranteed Copy Elision means
113 // that there's no way to write an AioCb constructor that neither boxes
114 // the object itself, nor moves it during return.
115 in_progress: bool,
116 _fd: PhantomData<BorrowedFd<'a>>,
117 }
118
119 impl<'a> AioCb<'a> {
120 pin_utils::unsafe_unpinned!(aiocb: LibcAiocb);
121
122 fn aio_return(mut self: Pin<&mut Self>) -> Result<usize> {
123 self.in_progress = false;
124 unsafe {
125 let p: *mut libc::aiocb = &mut self.aiocb.0;
126 Errno::result(libc::aio_return(p))
127 }
128 .map(|r| r as usize)
129 }
130
131 fn cancel(mut self: Pin<&mut Self>) -> Result<AioCancelStat> {
132 let r = unsafe {
133 libc::aio_cancel(self.aiocb.0.aio_fildes, &mut self.aiocb.0)
134 };
135 match r {
136 libc::AIO_CANCELED => Ok(AioCancelStat::AioCanceled),
137 libc::AIO_NOTCANCELED => Ok(AioCancelStat::AioNotCanceled),
138 libc::AIO_ALLDONE => Ok(AioCancelStat::AioAllDone),
139 -1 => Err(Errno::last()),
140 _ => panic!("unknown aio_cancel return value"),
141 }
142 }
143
144 fn common_init(
145 fd: BorrowedFd<'a>,
146 prio: i32,
147 sigev_notify: SigevNotify,
148 ) -> Self {
149 // Use mem::zeroed instead of explicitly zeroing each field, because the
150 // number and name of reserved fields is OS-dependent. On some OSes,
151 // some reserved fields are used the kernel for state, and must be
152 // explicitly zeroed when allocated.
153 let mut a = unsafe { mem::zeroed::<libc::aiocb>() };
154 a.aio_fildes = fd.as_raw_fd();
155 a.aio_reqprio = prio;
156 a.aio_sigevent = SigEvent::new(sigev_notify).sigevent();
157 AioCb {
158 aiocb: LibcAiocb(a),
159 in_progress: false,
160 _fd: PhantomData,
161 }
162 }
163
164 fn error(self: Pin<&mut Self>) -> Result<()> {
165 let r = unsafe { libc::aio_error(&self.aiocb().0) };
166 match r {
167 0 => Ok(()),
168 num if num > 0 => Err(Errno::from_raw(num)),
169 -1 => Err(Errno::last()),
170 num => panic!("unknown aio_error return value {num:?}"),
171 }
172 }
173
174 fn in_progress(&self) -> bool {
175 self.in_progress
176 }
177
178 fn set_in_progress(mut self: Pin<&mut Self>) {
179 self.as_mut().in_progress = true;
180 }
181
182 /// Update the notification settings for an existing AIO operation that has
183 /// not yet been submitted.
184 // Takes a normal reference rather than a pinned one because this method is
185 // normally called before the object needs to be pinned, that is, before
186 // it's been submitted to the kernel.
187 fn set_sigev_notify(&mut self, sigev_notify: SigevNotify) {
188 assert!(
189 !self.in_progress,
190 "Can't change notification settings for an in-progress operation"
191 );
192 self.aiocb.0.aio_sigevent = SigEvent::new(sigev_notify).sigevent();
193 }
194 }
195
196 impl Debug for AioCb<'_> {
197 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
198 fmt.debug_struct("AioCb")
199 .field("aiocb", &self.aiocb.0)
200 .field("in_progress", &self.in_progress)
201 .finish()
202 }
203 }
204
205 impl Drop for AioCb<'_> {
206 /// If the `AioCb` has no remaining state in the kernel, just drop it.
207 /// Otherwise, dropping constitutes a resource leak, which is an error
208 fn drop(&mut self) {
209 assert!(
210 thread::panicking() || !self.in_progress,
211 "Dropped an in-progress AioCb"
212 );
213 }
214 }
215
216 /// Methods common to all AIO operations
217 pub trait Aio {
218 /// The return type of [`Aio::aio_return`].
219 type Output;
220
221 /// Retrieve return status of an asynchronous operation.
222 ///
223 /// Should only be called once for each operation, after [`Aio::error`]
224 /// indicates that it has completed. The result is the same as for the
225 /// synchronous `read(2)`, `write(2)`, of `fsync(2)` functions.
226 ///
227 /// # References
228 ///
229 /// [aio_return](https://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_return.html)
230 fn aio_return(self: Pin<&mut Self>) -> Result<Self::Output>;
231
232 /// Cancels an outstanding AIO request.
233 ///
234 /// The operating system is not required to implement cancellation for all
235 /// file and device types. Even if it does, there is no guarantee that the
236 /// operation has not already completed. So the caller must check the
237 /// result and handle operations that were not canceled or that have already
238 /// completed.
239 ///
240 /// # Examples
241 ///
242 /// Cancel an outstanding aio operation. Note that we must still call
243 /// `aio_return` to free resources, even though we don't care about the
244 /// result.
245 ///
246 /// ```
247 /// # use nix::errno::Errno;
248 /// # use nix::Error;
249 /// # use nix::sys::aio::*;
250 /// # use nix::sys::signal::SigevNotify;
251 /// # use std::{thread, time};
252 /// # use std::io::Write;
253 /// # use std::os::unix::io::AsFd;
254 /// # use tempfile::tempfile;
255 /// let wbuf = b"CDEF";
256 /// let mut f = tempfile().unwrap();
257 /// let mut aiocb = Box::pin(AioWrite::new(f.as_fd(),
258 /// 2, //offset
259 /// &wbuf[..],
260 /// 0, //priority
261 /// SigevNotify::SigevNone));
262 /// aiocb.as_mut().submit().unwrap();
263 /// let cs = aiocb.as_mut().cancel().unwrap();
264 /// if cs == AioCancelStat::AioNotCanceled {
265 /// while (aiocb.as_mut().error() == Err(Errno::EINPROGRESS)) {
266 /// thread::sleep(time::Duration::from_millis(10));
267 /// }
268 /// }
269 /// // Must call `aio_return`, but ignore the result
270 /// let _ = aiocb.as_mut().aio_return();
271 /// ```
272 ///
273 /// # References
274 ///
275 /// [aio_cancel](https://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_cancel.html)
276 fn cancel(self: Pin<&mut Self>) -> Result<AioCancelStat>;
277
278 /// Retrieve error status of an asynchronous operation.
279 ///
280 /// If the request has not yet completed, returns `EINPROGRESS`. Otherwise,
281 /// returns `Ok` or any other error.
282 ///
283 /// # Examples
284 ///
285 /// Issue an aio operation and use `error` to poll for completion. Polling
286 /// is an alternative to `aio_suspend`, used by most of the other examples.
287 ///
288 /// ```
289 /// # use nix::errno::Errno;
290 /// # use nix::Error;
291 /// # use nix::sys::aio::*;
292 /// # use nix::sys::signal::SigevNotify;
293 /// # use std::{thread, time};
294 /// # use std::os::unix::io::AsFd;
295 /// # use tempfile::tempfile;
296 /// const WBUF: &[u8] = b"abcdef123456";
297 /// let mut f = tempfile().unwrap();
298 /// let mut aiocb = Box::pin(AioWrite::new(f.as_fd(),
299 /// 2, //offset
300 /// WBUF,
301 /// 0, //priority
302 /// SigevNotify::SigevNone));
303 /// aiocb.as_mut().submit().unwrap();
304 /// while (aiocb.as_mut().error() == Err(Errno::EINPROGRESS)) {
305 /// thread::sleep(time::Duration::from_millis(10));
306 /// }
307 /// assert_eq!(aiocb.as_mut().aio_return().unwrap(), WBUF.len());
308 /// ```
309 ///
310 /// # References
311 ///
312 /// [aio_error](https://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_error.html)
313 fn error(self: Pin<&mut Self>) -> Result<()>;
314
315 /// Returns the underlying file descriptor associated with the operation.
316 fn fd(&self) -> BorrowedFd;
317
318 /// Does this operation currently have any in-kernel state?
319 ///
320 /// Dropping an operation that does have in-kernel state constitutes a
321 /// resource leak.
322 ///
323 /// # Examples
324 ///
325 /// ```
326 /// # use nix::errno::Errno;
327 /// # use nix::Error;
328 /// # use nix::sys::aio::*;
329 /// # use nix::sys::signal::SigevNotify::SigevNone;
330 /// # use std::{thread, time};
331 /// # use std::os::unix::io::AsFd;
332 /// # use tempfile::tempfile;
333 /// let f = tempfile().unwrap();
334 /// let mut aiof = Box::pin(AioFsync::new(f.as_fd(), AioFsyncMode::O_SYNC,
335 /// 0, SigevNone));
336 /// assert!(!aiof.as_mut().in_progress());
337 /// aiof.as_mut().submit().expect("aio_fsync failed early");
338 /// assert!(aiof.as_mut().in_progress());
339 /// while (aiof.as_mut().error() == Err(Errno::EINPROGRESS)) {
340 /// thread::sleep(time::Duration::from_millis(10));
341 /// }
342 /// aiof.as_mut().aio_return().expect("aio_fsync failed late");
343 /// assert!(!aiof.as_mut().in_progress());
344 /// ```
345 fn in_progress(&self) -> bool;
346
347 /// Returns the priority of the `AioCb`
348 fn priority(&self) -> i32;
349
350 /// Update the notification settings for an existing AIO operation that has
351 /// not yet been submitted.
352 fn set_sigev_notify(&mut self, sev: SigevNotify);
353
354 /// Returns the `SigEvent` that will be used for notification.
355 fn sigevent(&self) -> SigEvent;
356
357 /// Actually start the I/O operation.
358 ///
359 /// After calling this method and until [`Aio::aio_return`] returns `Ok`,
360 /// the structure may not be moved in memory.
361 fn submit(self: Pin<&mut Self>) -> Result<()>;
362 }
363
364 macro_rules! aio_methods {
365 () => {
366 fn cancel(self: Pin<&mut Self>) -> Result<AioCancelStat> {
367 self.aiocb().cancel()
368 }
369
370 fn error(self: Pin<&mut Self>) -> Result<()> {
371 self.aiocb().error()
372 }
373
374 fn fd(&self) -> BorrowedFd<'a> {
375 // safe because self's lifetime is the same as the original file
376 // descriptor.
377 unsafe { BorrowedFd::borrow_raw(self.aiocb.aiocb.0.aio_fildes) }
378 }
379
380 fn in_progress(&self) -> bool {
381 self.aiocb.in_progress()
382 }
383
384 fn priority(&self) -> i32 {
385 self.aiocb.aiocb.0.aio_reqprio
386 }
387
388 fn set_sigev_notify(&mut self, sev: SigevNotify) {
389 self.aiocb.set_sigev_notify(sev)
390 }
391
392 fn sigevent(&self) -> SigEvent {
393 SigEvent::from(&self.aiocb.aiocb.0.aio_sigevent)
394 }
395 };
396 ($func:ident) => {
397 aio_methods!();
398
399 fn aio_return(self: Pin<&mut Self>) -> Result<<Self as Aio>::Output> {
400 self.aiocb().aio_return()
401 }
402
403 fn submit(mut self: Pin<&mut Self>) -> Result<()> {
404 let p: *mut libc::aiocb = &mut self.as_mut().aiocb().aiocb.0;
405 Errno::result({ unsafe { libc::$func(p) } }).map(|_| {
406 self.aiocb().set_in_progress();
407 })
408 }
409 };
410 }
411
412 /// An asynchronous version of `fsync(2)`.
413 ///
414 /// # References
415 ///
416 /// [aio_fsync](https://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_fsync.html)
417 /// # Examples
418 ///
419 /// ```
420 /// # use nix::errno::Errno;
421 /// # use nix::Error;
422 /// # use nix::sys::aio::*;
423 /// # use nix::sys::signal::SigevNotify::SigevNone;
424 /// # use std::{thread, time};
425 /// # use std::os::unix::io::AsFd;
426 /// # use tempfile::tempfile;
427 /// let f = tempfile().unwrap();
428 /// let mut aiof = Box::pin(AioFsync::new(f.as_fd(), AioFsyncMode::O_SYNC,
429 /// 0, SigevNone));
430 /// aiof.as_mut().submit().expect("aio_fsync failed early");
431 /// while (aiof.as_mut().error() == Err(Errno::EINPROGRESS)) {
432 /// thread::sleep(time::Duration::from_millis(10));
433 /// }
434 /// aiof.as_mut().aio_return().expect("aio_fsync failed late");
435 /// ```
436 #[derive(Debug)]
437 #[repr(transparent)]
438 pub struct AioFsync<'a> {
439 aiocb: AioCb<'a>,
440 _pin: PhantomPinned,
441 }
442
443 impl<'a> AioFsync<'a> {
444 unsafe_pinned!(aiocb: AioCb<'a>);
445
446 /// Returns the operation's fsync mode: data and metadata or data only?
447 pub fn mode(&self) -> AioFsyncMode {
448 AioFsyncMode::try_from(self.aiocb.aiocb.0.aio_lio_opcode).unwrap()
449 }
450
451 /// Create a new `AioFsync`.
452 ///
453 /// # Arguments
454 ///
455 /// * `fd`: File descriptor to sync.
456 /// * `mode`: Whether to sync file metadata too, or just data.
457 /// * `prio`: If POSIX Prioritized IO is supported, then the
458 /// operation will be prioritized at the process's priority level minus
459 /// `prio`.
460 /// * `sigev_notify`: Determines how you will be notified of event completion.
461 pub fn new(
462 fd: BorrowedFd<'a>,
463 mode: AioFsyncMode,
464 prio: i32,
465 sigev_notify: SigevNotify,
466 ) -> Self {
467 let mut aiocb = AioCb::common_init(fd, prio, sigev_notify);
468 // To save some memory, store mode in an unused field of the AioCb.
469 // True it isn't very much memory, but downstream creates will likely
470 // create an enum containing this and other AioCb variants and pack
471 // those enums into data structures like Vec, so it adds up.
472 aiocb.aiocb.0.aio_lio_opcode = mode as libc::c_int;
473 AioFsync {
474 aiocb,
475 _pin: PhantomPinned,
476 }
477 }
478 }
479
480 impl<'a> Aio for AioFsync<'a> {
481 type Output = ();
482
483 aio_methods!();
484
485 fn aio_return(self: Pin<&mut Self>) -> Result<()> {
486 self.aiocb().aio_return().map(drop)
487 }
488
489 fn submit(mut self: Pin<&mut Self>) -> Result<()> {
490 let aiocb = &mut self.as_mut().aiocb().aiocb.0;
491 let mode = mem::replace(&mut aiocb.aio_lio_opcode, 0);
492 let p: *mut libc::aiocb = aiocb;
493 Errno::result(unsafe { libc::aio_fsync(mode, p) }).map(|_| {
494 self.aiocb().set_in_progress();
495 })
496 }
497 }
498
499 // AioFsync does not need AsMut, since it can't be used with lio_listio
500
501 impl AsRef<libc::aiocb> for AioFsync<'_> {
502 fn as_ref(&self) -> &libc::aiocb {
503 &self.aiocb.aiocb.0
504 }
505 }
506
507 /// Asynchronously reads from a file descriptor into a buffer
508 ///
509 /// # References
510 ///
511 /// [aio_read](https://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_read.html)
512 ///
513 /// # Examples
514 ///
515 ///
516 /// ```
517 /// # use nix::errno::Errno;
518 /// # use nix::Error;
519 /// # use nix::sys::aio::*;
520 /// # use nix::sys::signal::SigevNotify;
521 /// # use std::{thread, time};
522 /// # use std::io::Write;
523 /// # use std::os::unix::io::AsFd;
524 /// # use tempfile::tempfile;
525 /// const INITIAL: &[u8] = b"abcdef123456";
526 /// const LEN: usize = 4;
527 /// let mut rbuf = vec![0; LEN];
528 /// let mut f = tempfile().unwrap();
529 /// f.write_all(INITIAL).unwrap();
530 /// {
531 /// let mut aior = Box::pin(
532 /// AioRead::new(
533 /// f.as_fd(),
534 /// 2, //offset
535 /// &mut rbuf,
536 /// 0, //priority
537 /// SigevNotify::SigevNone
538 /// )
539 /// );
540 /// aior.as_mut().submit().unwrap();
541 /// while (aior.as_mut().error() == Err(Errno::EINPROGRESS)) {
542 /// thread::sleep(time::Duration::from_millis(10));
543 /// }
544 /// assert_eq!(aior.as_mut().aio_return().unwrap(), LEN);
545 /// }
546 /// assert_eq!(rbuf, b"cdef");
547 /// ```
548 #[derive(Debug)]
549 #[repr(transparent)]
550 pub struct AioRead<'a> {
551 aiocb: AioCb<'a>,
552 _data: PhantomData<&'a [u8]>,
553 _pin: PhantomPinned,
554 }
555
556 impl<'a> AioRead<'a> {
557 unsafe_pinned!(aiocb: AioCb<'a>);
558
559 /// Returns the requested length of the aio operation in bytes
560 ///
561 /// This method returns the *requested* length of the operation. To get the
562 /// number of bytes actually read or written by a completed operation, use
563 /// `aio_return` instead.
564 pub fn nbytes(&self) -> usize {
565 self.aiocb.aiocb.0.aio_nbytes
566 }
567
568 /// Create a new `AioRead`, placing the data in a mutable slice.
569 ///
570 /// # Arguments
571 ///
572 /// * `fd`: File descriptor to read from
573 /// * `offs`: File offset
574 /// * `buf`: A memory buffer. It must outlive the `AioRead`.
575 /// * `prio`: If POSIX Prioritized IO is supported, then the operation
576 /// will be prioritized at the process's priority level minus `prio`
577 /// * `sigev_notify`: Determines how you will be notified of event completion.
578 pub fn new(
579 fd: BorrowedFd<'a>,
580 offs: off_t,
581 buf: &'a mut [u8],
582 prio: i32,
583 sigev_notify: SigevNotify,
584 ) -> Self {
585 let mut aiocb = AioCb::common_init(fd, prio, sigev_notify);
586 aiocb.aiocb.0.aio_nbytes = buf.len();
587 aiocb.aiocb.0.aio_buf = buf.as_mut_ptr().cast();
588 aiocb.aiocb.0.aio_lio_opcode = libc::LIO_READ;
589 aiocb.aiocb.0.aio_offset = offs;
590 AioRead {
591 aiocb,
592 _data: PhantomData,
593 _pin: PhantomPinned,
594 }
595 }
596
597 /// Returns the file offset of the operation.
598 pub fn offset(&self) -> off_t {
599 self.aiocb.aiocb.0.aio_offset
600 }
601 }
602
603 impl<'a> Aio for AioRead<'a> {
604 type Output = usize;
605
606 aio_methods!(aio_read);
607 }
608
609 impl AsMut<libc::aiocb> for AioRead<'_> {
610 fn as_mut(&mut self) -> &mut libc::aiocb {
611 &mut self.aiocb.aiocb.0
612 }
613 }
614
615 impl AsRef<libc::aiocb> for AioRead<'_> {
616 fn as_ref(&self) -> &libc::aiocb {
617 &self.aiocb.aiocb.0
618 }
619 }
620
621 /// Asynchronously reads from a file descriptor into a scatter/gather list of buffers.
622 ///
623 /// # References
624 ///
625 /// [aio_readv](https://www.freebsd.org/cgi/man.cgi?query=aio_readv)
626 ///
627 /// # Examples
628 ///
629 ///
630 #[cfg_attr(fbsd14, doc = " ```")]
631 #[cfg_attr(not(fbsd14), doc = " ```no_run")]
632 /// # use nix::errno::Errno;
633 /// # use nix::Error;
634 /// # use nix::sys::aio::*;
635 /// # use nix::sys::signal::SigevNotify;
636 /// # use std::{thread, time};
637 /// # use std::io::{IoSliceMut, Write};
638 /// # use std::os::unix::io::AsFd;
639 /// # use tempfile::tempfile;
640 /// const INITIAL: &[u8] = b"abcdef123456";
641 /// let mut rbuf0 = vec![0; 4];
642 /// let mut rbuf1 = vec![0; 2];
643 /// let expected_len = rbuf0.len() + rbuf1.len();
644 /// let mut rbufs = [IoSliceMut::new(&mut rbuf0), IoSliceMut::new(&mut rbuf1)];
645 /// let mut f = tempfile().unwrap();
646 /// f.write_all(INITIAL).unwrap();
647 /// {
648 /// let mut aior = Box::pin(
649 /// AioReadv::new(
650 /// f.as_fd(),
651 /// 2, //offset
652 /// &mut rbufs,
653 /// 0, //priority
654 /// SigevNotify::SigevNone
655 /// )
656 /// );
657 /// aior.as_mut().submit().unwrap();
658 /// while (aior.as_mut().error() == Err(Errno::EINPROGRESS)) {
659 /// thread::sleep(time::Duration::from_millis(10));
660 /// }
661 /// assert_eq!(aior.as_mut().aio_return().unwrap(), expected_len);
662 /// }
663 /// assert_eq!(rbuf0, b"cdef");
664 /// assert_eq!(rbuf1, b"12");
665 /// ```
666 #[cfg(target_os = "freebsd")]
667 #[derive(Debug)]
668 #[repr(transparent)]
669 pub struct AioReadv<'a> {
670 aiocb: AioCb<'a>,
671 _data: PhantomData<&'a [&'a [u8]]>,
672 _pin: PhantomPinned,
673 }
674
675 #[cfg(target_os = "freebsd")]
676 impl<'a> AioReadv<'a> {
677 unsafe_pinned!(aiocb: AioCb<'a>);
678
679 /// Returns the number of buffers the operation will read into.
680 pub fn iovlen(&self) -> usize {
681 self.aiocb.aiocb.0.aio_nbytes
682 }
683
684 /// Create a new `AioReadv`, placing the data in a list of mutable slices.
685 ///
686 /// # Arguments
687 ///
688 /// * `fd`: File descriptor to read from
689 /// * `offs`: File offset
690 /// * `bufs`: A scatter/gather list of memory buffers. They must
691 /// outlive the `AioReadv`.
692 /// * `prio`: If POSIX Prioritized IO is supported, then the
693 /// operation will be prioritized at the process's
694 /// priority level minus `prio`
695 /// * `sigev_notify`: Determines how you will be notified of event
696 /// completion.
697 pub fn new(
698 fd: BorrowedFd<'a>,
699 offs: off_t,
700 bufs: &mut [IoSliceMut<'a>],
701 prio: i32,
702 sigev_notify: SigevNotify,
703 ) -> Self {
704 let mut aiocb = AioCb::common_init(fd, prio, sigev_notify);
705 // In vectored mode, aio_nbytes stores the length of the iovec array,
706 // not the byte count.
707 aiocb.aiocb.0.aio_nbytes = bufs.len();
708 aiocb.aiocb.0.aio_buf = bufs.as_mut_ptr().cast();
709 aiocb.aiocb.0.aio_lio_opcode = libc::LIO_READV;
710 aiocb.aiocb.0.aio_offset = offs;
711 AioReadv {
712 aiocb,
713 _data: PhantomData,
714 _pin: PhantomPinned,
715 }
716 }
717
718 /// Returns the file offset of the operation.
719 pub fn offset(&self) -> off_t {
720 self.aiocb.aiocb.0.aio_offset
721 }
722 }
723
724 #[cfg(target_os = "freebsd")]
725 impl<'a> Aio for AioReadv<'a> {
726 type Output = usize;
727
728 aio_methods!(aio_readv);
729 }
730
731 #[cfg(target_os = "freebsd")]
732 impl AsMut<libc::aiocb> for AioReadv<'_> {
733 fn as_mut(&mut self) -> &mut libc::aiocb {
734 &mut self.aiocb.aiocb.0
735 }
736 }
737
738 #[cfg(target_os = "freebsd")]
739 impl AsRef<libc::aiocb> for AioReadv<'_> {
740 fn as_ref(&self) -> &libc::aiocb {
741 &self.aiocb.aiocb.0
742 }
743 }
744
745 /// Asynchronously writes from a buffer to a file descriptor
746 ///
747 /// # References
748 ///
749 /// [aio_write](https://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_write.html)
750 ///
751 /// # Examples
752 ///
753 /// ```
754 /// # use nix::errno::Errno;
755 /// # use nix::Error;
756 /// # use nix::sys::aio::*;
757 /// # use nix::sys::signal::SigevNotify;
758 /// # use std::{thread, time};
759 /// # use std::os::unix::io::AsFd;
760 /// # use tempfile::tempfile;
761 /// const WBUF: &[u8] = b"abcdef123456";
762 /// let mut f = tempfile().unwrap();
763 /// let mut aiow = Box::pin(
764 /// AioWrite::new(
765 /// f.as_fd(),
766 /// 2, //offset
767 /// WBUF,
768 /// 0, //priority
769 /// SigevNotify::SigevNone
770 /// )
771 /// );
772 /// aiow.as_mut().submit().unwrap();
773 /// while (aiow.as_mut().error() == Err(Errno::EINPROGRESS)) {
774 /// thread::sleep(time::Duration::from_millis(10));
775 /// }
776 /// assert_eq!(aiow.as_mut().aio_return().unwrap(), WBUF.len());
777 /// ```
778 #[derive(Debug)]
779 #[repr(transparent)]
780 pub struct AioWrite<'a> {
781 aiocb: AioCb<'a>,
782 _data: PhantomData<&'a [u8]>,
783 _pin: PhantomPinned,
784 }
785
786 impl<'a> AioWrite<'a> {
787 unsafe_pinned!(aiocb: AioCb<'a>);
788
789 /// Returns the requested length of the aio operation in bytes
790 ///
791 /// This method returns the *requested* length of the operation. To get the
792 /// number of bytes actually read or written by a completed operation, use
793 /// `aio_return` instead.
794 pub fn nbytes(&self) -> usize {
795 self.aiocb.aiocb.0.aio_nbytes
796 }
797
798 /// Construct a new `AioWrite`.
799 ///
800 /// # Arguments
801 ///
802 /// * `fd`: File descriptor to write to
803 /// * `offs`: File offset
804 /// * `buf`: A memory buffer. It must outlive the `AioWrite`.
805 /// * `prio`: If POSIX Prioritized IO is supported, then the operation
806 /// will be prioritized at the process's priority level minus `prio`
807 /// * `sigev_notify`: Determines how you will be notified of event completion.
808 pub fn new(
809 fd: BorrowedFd<'a>,
810 offs: off_t,
811 buf: &'a [u8],
812 prio: i32,
813 sigev_notify: SigevNotify,
814 ) -> Self {
815 let mut aiocb = AioCb::common_init(fd, prio, sigev_notify);
816 aiocb.aiocb.0.aio_nbytes = buf.len();
817 // casting an immutable buffer to a mutable pointer looks unsafe,
818 // but technically its only unsafe to dereference it, not to create
819 // it. Type Safety guarantees that we'll never pass aiocb to
820 // aio_read or aio_readv.
821 aiocb.aiocb.0.aio_buf = buf.as_ptr().cast_mut().cast();
822 aiocb.aiocb.0.aio_lio_opcode = libc::LIO_WRITE;
823 aiocb.aiocb.0.aio_offset = offs;
824 AioWrite {
825 aiocb,
826 _data: PhantomData,
827 _pin: PhantomPinned,
828 }
829 }
830
831 /// Returns the file offset of the operation.
832 pub fn offset(&self) -> off_t {
833 self.aiocb.aiocb.0.aio_offset
834 }
835 }
836
837 impl<'a> Aio for AioWrite<'a> {
838 type Output = usize;
839
840 aio_methods!(aio_write);
841 }
842
843 impl AsMut<libc::aiocb> for AioWrite<'_> {
844 fn as_mut(&mut self) -> &mut libc::aiocb {
845 &mut self.aiocb.aiocb.0
846 }
847 }
848
849 impl AsRef<libc::aiocb> for AioWrite<'_> {
850 fn as_ref(&self) -> &libc::aiocb {
851 &self.aiocb.aiocb.0
852 }
853 }
854
855 /// Asynchronously writes from a scatter/gather list of buffers to a file descriptor.
856 ///
857 /// # References
858 ///
859 /// [aio_writev](https://www.freebsd.org/cgi/man.cgi?query=aio_writev)
860 ///
861 /// # Examples
862 ///
863 #[cfg_attr(fbsd14, doc = " ```")]
864 #[cfg_attr(not(fbsd14), doc = " ```no_run")]
865 /// # use nix::errno::Errno;
866 /// # use nix::Error;
867 /// # use nix::sys::aio::*;
868 /// # use nix::sys::signal::SigevNotify;
869 /// # use std::{thread, time};
870 /// # use std::io::IoSlice;
871 /// # use std::os::unix::io::AsFd;
872 /// # use tempfile::tempfile;
873 /// const wbuf0: &[u8] = b"abcdef";
874 /// const wbuf1: &[u8] = b"123456";
875 /// let len = wbuf0.len() + wbuf1.len();
876 /// let wbufs = [IoSlice::new(wbuf0), IoSlice::new(wbuf1)];
877 /// let mut f = tempfile().unwrap();
878 /// let mut aiow = Box::pin(
879 /// AioWritev::new(
880 /// f.as_fd(),
881 /// 2, //offset
882 /// &wbufs,
883 /// 0, //priority
884 /// SigevNotify::SigevNone
885 /// )
886 /// );
887 /// aiow.as_mut().submit().unwrap();
888 /// while (aiow.as_mut().error() == Err(Errno::EINPROGRESS)) {
889 /// thread::sleep(time::Duration::from_millis(10));
890 /// }
891 /// assert_eq!(aiow.as_mut().aio_return().unwrap(), len);
892 /// ```
893 #[cfg(target_os = "freebsd")]
894 #[derive(Debug)]
895 #[repr(transparent)]
896 pub struct AioWritev<'a> {
897 aiocb: AioCb<'a>,
898 _data: PhantomData<&'a [&'a [u8]]>,
899 _pin: PhantomPinned,
900 }
901
902 #[cfg(target_os = "freebsd")]
903 impl<'a> AioWritev<'a> {
904 unsafe_pinned!(aiocb: AioCb<'a>);
905
906 /// Returns the number of buffers the operation will read into.
907 pub fn iovlen(&self) -> usize {
908 self.aiocb.aiocb.0.aio_nbytes
909 }
910
911 /// Construct a new `AioWritev`.
912 ///
913 /// # Arguments
914 ///
915 /// * `fd`: File descriptor to write to
916 /// * `offs`: File offset
917 /// * `bufs`: A scatter/gather list of memory buffers. They must
918 /// outlive the `AioWritev`.
919 /// * `prio`: If POSIX Prioritized IO is supported, then the
920 /// operation will be prioritized at the process's
921 /// priority level minus `prio`
922 /// * `sigev_notify`: Determines how you will be notified of event
923 /// completion.
924 pub fn new(
925 fd: BorrowedFd<'a>,
926 offs: off_t,
927 bufs: &[IoSlice<'a>],
928 prio: i32,
929 sigev_notify: SigevNotify,
930 ) -> Self {
931 let mut aiocb = AioCb::common_init(fd, prio, sigev_notify);
932 // In vectored mode, aio_nbytes stores the length of the iovec array,
933 // not the byte count.
934 aiocb.aiocb.0.aio_nbytes = bufs.len();
935 // casting an immutable buffer to a mutable pointer looks unsafe,
936 // but technically its only unsafe to dereference it, not to create
937 // it. Type Safety guarantees that we'll never pass aiocb to
938 // aio_read or aio_readv.
939 aiocb.aiocb.0.aio_buf = bufs.as_ptr().cast_mut().cast();
940 aiocb.aiocb.0.aio_lio_opcode = libc::LIO_WRITEV;
941 aiocb.aiocb.0.aio_offset = offs;
942 AioWritev {
943 aiocb,
944 _data: PhantomData,
945 _pin: PhantomPinned,
946 }
947 }
948
949 /// Returns the file offset of the operation.
950 pub fn offset(&self) -> off_t {
951 self.aiocb.aiocb.0.aio_offset
952 }
953 }
954
955 #[cfg(target_os = "freebsd")]
956 impl<'a> Aio for AioWritev<'a> {
957 type Output = usize;
958
959 aio_methods!(aio_writev);
960 }
961
962 #[cfg(target_os = "freebsd")]
963 impl AsMut<libc::aiocb> for AioWritev<'_> {
964 fn as_mut(&mut self) -> &mut libc::aiocb {
965 &mut self.aiocb.aiocb.0
966 }
967 }
968
969 #[cfg(target_os = "freebsd")]
970 impl AsRef<libc::aiocb> for AioWritev<'_> {
971 fn as_ref(&self) -> &libc::aiocb {
972 &self.aiocb.aiocb.0
973 }
974 }
975
976 /// Cancels outstanding AIO requests for a given file descriptor.
977 ///
978 /// # Examples
979 ///
980 /// Issue an aio operation, then cancel all outstanding operations on that file
981 /// descriptor.
982 ///
983 /// ```
984 /// # use nix::errno::Errno;
985 /// # use nix::Error;
986 /// # use nix::sys::aio::*;
987 /// # use nix::sys::signal::SigevNotify;
988 /// # use std::{thread, time};
989 /// # use std::io::Write;
990 /// # use std::os::unix::io::AsFd;
991 /// # use tempfile::tempfile;
992 /// let wbuf = b"CDEF";
993 /// let mut f = tempfile().unwrap();
994 /// let mut aiocb = Box::pin(AioWrite::new(f.as_fd(),
995 /// 2, //offset
996 /// &wbuf[..],
997 /// 0, //priority
998 /// SigevNotify::SigevNone));
999 /// aiocb.as_mut().submit().unwrap();
1000 /// let cs = aio_cancel_all(f.as_fd()).unwrap();
1001 /// if cs == AioCancelStat::AioNotCanceled {
1002 /// while (aiocb.as_mut().error() == Err(Errno::EINPROGRESS)) {
1003 /// thread::sleep(time::Duration::from_millis(10));
1004 /// }
1005 /// }
1006 /// // Must call `aio_return`, but ignore the result
1007 /// let _ = aiocb.as_mut().aio_return();
1008 /// ```
1009 ///
1010 /// # References
1011 ///
1012 /// [`aio_cancel`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_cancel.html)
1013 pub fn aio_cancel_all<F: AsFd>(fd: F) -> Result<AioCancelStat> {
1014 match unsafe { libc::aio_cancel(fd.as_fd().as_raw_fd(), ptr::null_mut()) } {
1015 libc::AIO_CANCELED => Ok(AioCancelStat::AioCanceled),
1016 libc::AIO_NOTCANCELED => Ok(AioCancelStat::AioNotCanceled),
1017 libc::AIO_ALLDONE => Ok(AioCancelStat::AioAllDone),
1018 -1 => Err(Errno::last()),
1019 _ => panic!("unknown aio_cancel return value"),
1020 }
1021 }
1022
1023 /// Suspends the calling process until at least one of the specified operations
1024 /// have completed, a signal is delivered, or the timeout has passed.
1025 ///
1026 /// If `timeout` is `None`, `aio_suspend` will block indefinitely.
1027 ///
1028 /// # Examples
1029 ///
1030 /// Use `aio_suspend` to block until an aio operation completes.
1031 ///
1032 /// ```
1033 /// # use nix::sys::aio::*;
1034 /// # use nix::sys::signal::SigevNotify;
1035 /// # use std::os::unix::io::AsFd;
1036 /// # use tempfile::tempfile;
1037 /// const WBUF: &[u8] = b"abcdef123456";
1038 /// let mut f = tempfile().unwrap();
1039 /// let mut aiocb = Box::pin(AioWrite::new(f.as_fd(),
1040 /// 2, //offset
1041 /// WBUF,
1042 /// 0, //priority
1043 /// SigevNotify::SigevNone));
1044 /// aiocb.as_mut().submit().unwrap();
1045 /// aio_suspend(&[&*aiocb], None).expect("aio_suspend failed");
1046 /// assert_eq!(aiocb.as_mut().aio_return().unwrap(), WBUF.len());
1047 /// ```
1048 /// # References
1049 ///
1050 /// [`aio_suspend`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/aio_suspend.html)
1051 pub fn aio_suspend(
1052 list: &[&dyn AsRef<libc::aiocb>],
1053 timeout: Option<TimeSpec>,
1054 ) -> Result<()> {
1055 // Note that this allocation could be eliminated by making the argument
1056 // generic, and accepting arguments like &[AioWrite]. But that would
1057 // prevent using aio_suspend to wait on a heterogeneous list of mixed
1058 // operations.
1059 let v = list
1060 .iter()
1061 .map(|x| x.as_ref() as *const libc::aiocb)
1062 .collect::<Vec<*const libc::aiocb>>();
1063 let p = v.as_ptr();
1064 let timep = match timeout {
1065 None => ptr::null::<libc::timespec>(),
1066 Some(x) => x.as_ref() as *const libc::timespec,
1067 };
1068 Errno::result(unsafe { libc::aio_suspend(p, list.len() as i32, timep) })
1069 .map(drop)
1070 }
1071
1072 /// Submits multiple asynchronous I/O requests with a single system call.
1073 ///
1074 /// They are not guaranteed to complete atomically, and the order in which the
1075 /// requests are carried out is not specified. Reads, and writes may be freely
1076 /// mixed.
1077 ///
1078 /// # Examples
1079 ///
1080 /// Use `lio_listio` to submit an aio operation and wait for its completion. In
1081 /// this case, there is no need to use aio_suspend to wait or `error` to poll.
1082 /// This mode is useful for otherwise-synchronous programs that want to execute
1083 /// a handful of I/O operations in parallel.
1084 /// ```
1085 /// # use std::os::unix::io::AsFd;
1086 /// # use nix::sys::aio::*;
1087 /// # use nix::sys::signal::SigevNotify;
1088 /// # use tempfile::tempfile;
1089 /// const WBUF: &[u8] = b"abcdef123456";
1090 /// let mut f = tempfile().unwrap();
1091 /// let mut aiow = Box::pin(AioWrite::new(
1092 /// f.as_fd(),
1093 /// 2, // offset
1094 /// WBUF,
1095 /// 0, // priority
1096 /// SigevNotify::SigevNone
1097 /// ));
1098 /// lio_listio(LioMode::LIO_WAIT, &mut[aiow.as_mut()], SigevNotify::SigevNone)
1099 /// .unwrap();
1100 /// // At this point, we are guaranteed that aiow is complete.
1101 /// assert_eq!(aiow.as_mut().aio_return().unwrap(), WBUF.len());
1102 /// ```
1103 ///
1104 /// Use `lio_listio` to submit multiple asynchronous operations with a single
1105 /// syscall, but receive notification individually. This is an efficient
1106 /// technique for reducing overall context-switch overhead, especially when
1107 /// combined with kqueue.
1108 /// ```
1109 /// # use std::os::unix::io::AsFd;
1110 /// # use std::thread;
1111 /// # use std::time;
1112 /// # use nix::errno::Errno;
1113 /// # use nix::sys::aio::*;
1114 /// # use nix::sys::signal::SigevNotify;
1115 /// # use tempfile::tempfile;
1116 /// const WBUF: &[u8] = b"abcdef123456";
1117 /// let mut f = tempfile().unwrap();
1118 /// let mut aiow = Box::pin(AioWrite::new(
1119 /// f.as_fd(),
1120 /// 2, // offset
1121 /// WBUF,
1122 /// 0, // priority
1123 /// SigevNotify::SigevNone
1124 /// ));
1125 /// lio_listio(LioMode::LIO_NOWAIT, &mut[aiow.as_mut()], SigevNotify::SigevNone)
1126 /// .unwrap();
1127 /// // We must wait for the completion of each individual operation
1128 /// while (aiow.as_mut().error() == Err(Errno::EINPROGRESS)) {
1129 /// thread::sleep(time::Duration::from_millis(10));
1130 /// }
1131 /// assert_eq!(aiow.as_mut().aio_return().unwrap(), WBUF.len());
1132 /// ```
1133 ///
1134 /// Use `lio_listio` to submit multiple operations, and receive notification
1135 /// only when all of them are complete. This can be useful when there is some
1136 /// logical relationship between the operations. But beware! Errors or system
1137 /// resource limitations may cause `lio_listio` to return `EIO`, `EAGAIN`, or
1138 /// `EINTR`, in which case some but not all operations may have been submitted.
1139 /// In that case, you must check the status of each individual operation, and
1140 /// possibly resubmit some.
1141 /// ```
1142 /// # use libc::c_int;
1143 /// # use std::os::unix::io::AsFd;
1144 /// # use std::sync::atomic::{AtomicBool, Ordering};
1145 /// # use std::thread;
1146 /// # use std::time;
1147 /// # use nix::errno::Errno;
1148 /// # use nix::sys::aio::*;
1149 /// # use nix::sys::signal::*;
1150 /// # use tempfile::tempfile;
1151 /// pub static SIGNALED: AtomicBool = AtomicBool::new(false);
1152 ///
1153 /// extern fn sigfunc(_: c_int) {
1154 /// SIGNALED.store(true, Ordering::Relaxed);
1155 /// }
1156 /// let sa = SigAction::new(SigHandler::Handler(sigfunc),
1157 /// SaFlags::SA_RESETHAND,
1158 /// SigSet::empty());
1159 /// SIGNALED.store(false, Ordering::Relaxed);
1160 /// unsafe { sigaction(Signal::SIGUSR2, &sa) }.unwrap();
1161 ///
1162 /// const WBUF: &[u8] = b"abcdef123456";
1163 /// let mut f = tempfile().unwrap();
1164 /// let mut aiow = Box::pin(AioWrite::new(
1165 /// f.as_fd(),
1166 /// 2, // offset
1167 /// WBUF,
1168 /// 0, // priority
1169 /// SigevNotify::SigevNone
1170 /// ));
1171 /// let sev = SigevNotify::SigevSignal { signal: Signal::SIGUSR2, si_value: 0 };
1172 /// lio_listio(LioMode::LIO_NOWAIT, &mut[aiow.as_mut()], sev).unwrap();
1173 /// while !SIGNALED.load(Ordering::Relaxed) {
1174 /// thread::sleep(time::Duration::from_millis(10));
1175 /// }
1176 /// // At this point, since `lio_listio` returned success and delivered its
1177 /// // notification, we know that all operations are complete.
1178 /// assert_eq!(aiow.as_mut().aio_return().unwrap(), WBUF.len());
1179 /// ```
1180 #[deprecated(
1181 since = "0.27.0",
1182 note = "https://github.com/nix-rust/nix/issues/2017"
1183 )]
1184 pub fn lio_listio(
1185 mode: LioMode,
1186 list: &mut [Pin<&mut dyn AsMut<libc::aiocb>>],
1187 sigev_notify: SigevNotify,
1188 ) -> Result<()> {
1189 let p = list as *mut [Pin<&mut dyn AsMut<libc::aiocb>>]
1190 as *mut [*mut libc::aiocb] as *mut *mut libc::aiocb;
1191 let sigev = SigEvent::new(sigev_notify);
1192 let sigevp = &mut sigev.sigevent() as *mut libc::sigevent;
1193 Errno::result(unsafe {
1194 libc::lio_listio(mode as i32, p, list.len() as i32, sigevp)
1195 })
1196 .map(drop)
1197 }