liburing-rs 0.2.0

//! Rust bindings and idiomatic wrapper for liburing (Linux io_uring)
//!
//! This crate provides safe, ergonomic Rust bindings to liburing, the userspace
//! library for interacting with the Linux kernel's io_uring interface.
//!
//! # Architecture
//!
//! The crate is organized into three layers:
//!
//! 1. **`sys` module**: Raw FFI bindings generated by bindgen (unsafe)
//! 2. **Safe wrapper layer**: RAII-based safe wrappers around the C API
//! 3. **High-level API**: Idiomatic Rust builders and abstractions
//!
//! # Example
//!
//! ```no_run
//! use liburing_rs::IoUring;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Create an io_uring instance with 32 entries
//! let mut ring = IoUring::new(32)?;
//!
//! // Submit operations and wait for completions...
//! # Ok(())
//! # }
//! ```

#![warn(missing_docs)]
#![cfg(target_os = "linux")]

pub mod sys;

mod error;
pub mod ops;
mod queue;
mod uring;

#[cfg(any(feature = "async-tokio", feature = "async-async-std"))]
pub mod async_io;

pub use error::{Error, Result};
pub use queue::{CompletionQueue, Cqe, SubmissionQueue};
pub use uring::IoUring;

// Re-export key types that users might need
pub use sys::{io_uring_cqe, io_uring_sqe};

/// io_uring setup flags
pub mod flags {
    use bitflags::bitflags;

    bitflags! {
        /// Flags for io_uring_setup
        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
        pub struct SetupFlags: u32 {
            /// Perform busy-waiting for I/O completion
            const IOPOLL = crate::sys::IORING_SETUP_IOPOLL;
            /// Use a kernel thread to perform submission queue polling
            const SQPOLL = crate::sys::IORING_SETUP_SQPOLL;
            /// Set CPU affinity for SQPOLL thread
            const SQ_AFF = crate::sys::IORING_SETUP_SQ_AFF;
            /// Create CQ with specified size (via params)
            const CQSIZE = crate::sys::IORING_SETUP_CQSIZE;
            /// Clamp SQ/CQ sizes
            const CLAMP = crate::sys::IORING_SETUP_CLAMP;
            /// Attach to existing workqueue
            const ATTACH_WQ = crate::sys::IORING_SETUP_ATTACH_WQ;
            /// Start ring disabled
            const R_DISABLED = crate::sys::IORING_SETUP_R_DISABLED;
            /// Continue submitting on error
            const SUBMIT_ALL = crate::sys::IORING_SETUP_SUBMIT_ALL;
            /// Cooperative task running
            const COOP_TASKRUN = crate::sys::IORING_SETUP_COOP_TASKRUN;
            /// Get notified when task work is available
            const TASKRUN_FLAG = crate::sys::IORING_SETUP_TASKRUN_FLAG;
            /// Use 128-byte SQEs
            const SQE128 = crate::sys::IORING_SETUP_SQE128;
            /// Use 32-byte CQEs
            const CQE32 = crate::sys::IORING_SETUP_CQE32;
            /// Only one task submits requests
            const SINGLE_ISSUER = crate::sys::IORING_SETUP_SINGLE_ISSUER;
            /// Defer running task work
            const DEFER_TASKRUN = crate::sys::IORING_SETUP_DEFER_TASKRUN;
        }
    }

    bitflags! {
        /// Flags for submission queue entries
        #[derive(Debug, Clone, Copy, PartialEq, Eq)]
        pub struct SqeFlags: u8 {
            /// Use fixed file descriptor
            const FIXED_FILE = 1 << 0;
            /// Issue after inflight I/O completes
            const IO_DRAIN = 1 << 1;
            /// Links next SQE
            const IO_LINK = 1 << 2;
            /// Stronger link (fails if this fails)
            const IO_HARDLINK = 1 << 3;
            /// Always go async
            const ASYNC = 1 << 4;
            /// Select buffer from group
            const BUFFER_SELECT = 1 << 5;
            /// Don't post CQE on success
            const CQE_SKIP_SUCCESS = 1 << 6;
        }
    }
}

/// io_uring operation codes
pub mod opcode {
    pub use crate::sys::io_uring_op;
}