lio 0.4.1

A platform-independent async I/O library with native support for io_uring (Linux), IOCP (Windows), and kqueue (macOS)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

use std::task::Waker;

use crate::{op::Op, registration::notifier::Notifier, typed_op::TypedOp};

/// Type-safe stored operation with compile-time result type guarantees.
///
/// This stores an operation along with its complete type information, allowing
/// for zero-cost, type-safe result extraction without any unsafe code.
pub struct StoredOp {
  op: Option<Op>,
  /// Cached result after completion, before extraction
  result: Option<OpResult>,
  notifier: Option<Notifier>,
}

impl std::fmt::Display for ResultNotMatching {
  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    write!(
      f,
      "Result type mismatch: expected to extract {} but got {}",
      self.expected, self.actual
    )
  }
}

impl std::error::Error for ResultNotMatching {
  fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
    None
  }

  fn description(&self) -> &str {
    &self.to_string()
  }
}

impl StoredOp {
  /// Create a new StoredOp for async operations with waker.
  ///
  /// # Type Safety
  ///
  /// The type marker is determined from the operation type T, ensuring
  /// that result extraction can only return the correct type.
  pub fn new_waker<T: TypedOp>(op: Op, waker: Waker) -> Self {
    Self {
      op: Some(op),
      result: None,
      notifier: Some(Notifier::new_waker(waker)),
    }
  }

  /// Create a new StoredOp for callback-based operations.
  ///
  /// # Type Safety
  ///
  /// The type marker ensures that the callback receives the correct result type.
  pub fn new_callback<T: TypedOp, F: FnOnce(T::Result) + Send>(
    op: Op,
    f: F,
  ) -> Self {
    Self {
      op: Some(op),
      result: None,
      notifier: Some(Notifier::new_callback::<T, F>(f)),
    }
  }

  pub fn op_ref(&self) -> &Op {
    self.op.as_ref().expect("Operation already consumed")
  }

  pub fn set_waker(&mut self, waker: Waker) -> bool {
    match self {
      Self { ref mut notifier, .. } => notifier.set_waker(waker),
      Self::Result(_) => panic!(),
    }
  }

  pub(crate) fn take_notifier(&mut self) -> Notifier {
    self.notifier.take().unwrap()
  }

  /// Type-safe result extraction using TypedOp.
  ///
  /// This method provides complete compile-time type safety by ensuring
  /// that the stored operation type matches the expected extraction type.
  pub fn get_op_result(&mut self, res: isize) -> OpResult {
    let op = self.op.take().expect("Operation result already extracted");
    op.result(res)
  }

  /// Type-safe result extraction for a specific operation type.
  ///
  /// # Type Safety
  ///
  /// This method validates that the stored operation type matches the
  /// expected result type T, then performs type-safe extraction.
  /// The compiler prevents calling this with wrong operation type.
  pub fn get_typed_result<T: TypedOp>(
    &mut self,
    res: isize,
  ) -> Option<T::Result> {
    // Validate that stored operation type matches expected type
    if Self::type_marker_for::<T>() != self.type_marker {
      return None;
    }

    // Compute OpResult if not already cached
    if self.result.is_none() {
      let op_result = self.get_op_result(res);
      self.result = Some(op_result);
    }

    // Extract using operation's type-safe method
    let op_result = self.result.as_mut().unwrap();
    op_result.into_typed()
  }
}

impl StoredOp {
  pub fn op_ref(&self) -> &Op {
    match self {
      Self::Pending { ref op, .. } => op,
      Self::Result(_) => panic!(),
    }
  }

  /// Create a new StoredOp for async operations with waker.
  ///
  /// # Type Safety
  ///
  /// The type marker is determined from the operation type T, ensuring
  /// that result extraction can only return the correct type.
  pub fn new_waker<T: TypedOp>(op: Op, waker: Waker) -> Self {
    Self::Pending { op, notifier: Notifier::new_waker(waker) }
  }

  /// Create a new StoredOp for callback-based operations.
  ///
  /// # Type Safety
  ///
  /// The type marker ensures that the callback receives the correct result type.
  pub fn new_callback<T: TypedOp, F: FnOnce(T::Result) + Send>(
    op: Op,
    f: F,
  ) -> Self {
    Self::Pending { op, notifier: Notifier::new_callback::<T, F>(f) }
  }

  pub fn set_waker(&mut self, waker: Waker) -> bool {
    match self {
      Self::Pending { ref mut notifier, .. } => notifier.set_waker(waker),
      Self::Result(_) => panic!(),
    }
  }

  pub fn result(&mut self) -> Option<isize> {
    match self {
      Self::Pending { .. } => None,
      Self::Result(result) => Some(*result),
    }
  }
}