pub trait Driver:
'static
+ Send
+ Sync {
// Required methods
fn new_dyn_timer(&self) -> PollImpl<dyn PollTimer>;
fn new_dyn_fd_ready(&self, fd: RawFd) -> Result<PollImpl<dyn PollFdReady>>;
fn new_dyn_socket_ready(
&self,
socket: RawFd,
) -> Result<PollImpl<dyn PollSocketReady>>;
fn new_dyn_wait(
&self,
fd: RawFd,
read_size: usize,
) -> Result<PollImpl<dyn PollWait>>;
fn io_uring_probe(&self, opcode: u8) -> bool;
unsafe fn io_uring_submit(
&self,
sqe: Entry,
) -> Pin<Box<dyn Future<Output = Result<i32>> + Send + '_>>;
}Expand description
A driver that supports polled IO.
Required Methods§
Sourcefn new_dyn_timer(&self) -> PollImpl<dyn PollTimer>
fn new_dyn_timer(&self) -> PollImpl<dyn PollTimer>
Returns a new timer.
Sourcefn new_dyn_fd_ready(&self, fd: RawFd) -> Result<PollImpl<dyn PollFdReady>>
fn new_dyn_fd_ready(&self, fd: RawFd) -> Result<PollImpl<dyn PollFdReady>>
Returns a new object for polling file descriptor readiness.
Sourcefn new_dyn_socket_ready(
&self,
socket: RawFd,
) -> Result<PollImpl<dyn PollSocketReady>>
fn new_dyn_socket_ready( &self, socket: RawFd, ) -> Result<PollImpl<dyn PollSocketReady>>
Creates a new object for polling socket readiness.
Sourcefn new_dyn_wait(
&self,
fd: RawFd,
read_size: usize,
) -> Result<PollImpl<dyn PollWait>>
fn new_dyn_wait( &self, fd: RawFd, read_size: usize, ) -> Result<PollImpl<dyn PollWait>>
Creates a new wait.
Signals will be consumed using reads of read_size bytes, with 8-byte
buffer alignment. read_size must be at most
MAXIMUM_WAIT_READ_SIZE bytes.
Sourcefn io_uring_probe(&self, opcode: u8) -> bool
fn io_uring_probe(&self, opcode: u8) -> bool
Returns whether the given opcode is supported by the ring.
Sourceunsafe fn io_uring_submit(
&self,
sqe: Entry,
) -> Pin<Box<dyn Future<Output = Result<i32>> + Send + '_>>
unsafe fn io_uring_submit( &self, sqe: Entry, ) -> Pin<Box<dyn Future<Output = Result<i32>> + Send + '_>>
Submits an io-uring SQE for asynchronous execution.
Returns a future that completes with the IO result. The future aborts the process if dropped while the IO is in flight, since there is no way to synchronously cancel an in-flight io-uring operation.
§Safety
All memory referenced by the SQE must remain valid for the lifetime of the returned future.
This can be hard to do safely; in particular, if this future can be
leaked (via std::mem::forget or otherwise) then the caller must
ensure that any referenced memory also leaks. The easiest way to do that
is to ensure that the future is awaited in an async function or block
that owns the underlying memory. So, this is safe:
async fn write(driver: &impl Driver, file: &File, buf: Vec<u8>) -> io::Result<usize> {
let sqe = opcode::Write::new(
types::Fd(file.as_raw_fd()), buf.as_ptr(), buf.len() as u32,
).build();
// SAFETY: `buf` is owned by this async function's state machine.
// If the outer future is leaked, `buf` leaks with it, so the
// memory remains valid for the io-uring operation.
unsafe { driver.io_uring_submit(sqe).await? };
Ok(buf.len())
}But this is not:
async fn write(driver: &impl Driver, file: &File, buf: &[u8]) -> io::Result<usize> {
let sqe = opcode::Write::new(
types::Fd(file.as_raw_fd()), buf.as_ptr(), buf.len() as u32,
).build();
// NOT SAFE: `buf` is a borrow. If the outer future is leaked,
// the referent can be freed while the io-uring operation is
// still in flight.
unsafe { driver.io_uring_submit(sqe).await? };
Ok(buf.len())
}