3 //! This module provides a wrapper for the C `struct request` type.
20 /// A wrapper around a blk-mq [`struct request`]. This represents an IO request.
24 /// There are four states for a request that the Rust bindings care about:
26 /// 1. Request is owned by block layer (refcount 0).
27 /// 2. Request is owned by driver but with zero [`ARef`]s in existence
29 /// 3. Request is owned by driver with exactly one [`ARef`] in existence
31 /// 4. Request is owned by driver with more than one [`ARef`] in existence
35 /// We need to track 1 and 2 to ensure we fail tag to request conversions for
38 /// We need to track 3 and 4 to ensure that it is safe to end the request and hand
46 /// [`struct request`].
50 /// * `self.0` is a valid [`struct request`] created by the C portion of the
52 /// * The private data area associated with this request must be an initialized
57 /// [`struct request`]: srctree/include/linux/blk-mq.h
60 pub struct Request<T>(Opaque<bindings::request>, PhantomData<T>);  struct
62 impl<T: Operations> Request<T> {  impl
63     /// Create an [`ARef<Request>`] from a [`struct request`] pointer.
69     /// * The type invariants for [`Request`] must hold for the pointee of `ptr`.
71     /// [`struct request`]: srctree/include/linux/blk-mq.h
72     pub(crate) unsafe fn aref_from_raw(ptr: *mut bindings::request) -> ARef<Self> {  in aref_from_raw()
79     /// Notify the block layer that a request is going to be processed now.
83     /// drivers call this function when starting to process a request.
90         // SAFETY: By type invariant, `self.0` is a valid `struct request` and  in start_unchecked()
97     /// [`Request`].
100     /// C [`struct request`]. If the operation fails, `this` is returned in the
103     /// [`struct request`]: srctree/include/linux/blk-mq.h
104     fn try_set_end(this: ARef<Self>) -> Result<*mut bindings::request, ARef<Self>> {  in try_set_end()  argument
124     /// Notify the block layer that the request has been completed without errors.
127     /// referencing the request.
131         // SAFETY: By type invariant, `this.0` was a valid `struct request`. The  in end_ok()
133         // `ARef`s pointing to this request. Therefore it is safe to hand it  in end_ok()
145     /// Complete the request by scheduling `Operations::complete` for
153         let ptr = ARef::into_raw(this).cast::<bindings::request>().as_ptr();  in complete()
154         // SAFETY: By type invariant, `self.0` is a valid `struct request`  in complete()
157             let this = unsafe { Request::aref_from_raw(ptr) };  in complete()
163     /// of the request structure.
170         let request_ptr = this.cast::<bindings::request>();  in wrapper_ptr()
181     /// area of the request structure.
184         // the private data associated with this request is initialized and  in wrapper_ref()
191 /// A wrapper around data stored in the private area of the C [`struct request`].
193 /// [`struct request`]: srctree/include/linux/blk-mq.h
195     /// The Rust request refcount has the following states:
197     /// - 0: The request is owned by C block layer.
198     /// - 1: The request is owned by Rust abstractions but there are no [`ARef`] references to it.
199     /// - 2+: There are [`ARef`] references to the request.
204     /// Return a reference to the refcount of the request that is embedding
210     /// Return a pointer to the refcount of the request that is embedding the
223 // SAFETY: Exclusive access is thread-safe for `Request`. `Request` has no `&mut
226 unsafe impl<T: Operations> Send for Request<T> {}  implementation
228 // SAFETY: Shared access is thread-safe for `Request`. `&self` methods that
230 unsafe impl<T: Operations> Sync for Request<T> {}  implementation
232 // SAFETY: All instances of `Request<T>` are reference counted. This
236 unsafe impl<T: Operations> AlwaysRefCounted for Request<T> {  implementation
245         // SAFETY: The type invariant of `Request` guarantees that the private  in dec_ref()
254             panic!("Request reached refcount zero in Rust abstractions");  in dec_ref()