air_sys_syscall/io_uring/

provided.rs

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.

//! **Buffers fournis ring-mapped** (Temps 3b, `IORING_REGISTER_PBUF_RING`) :
//! l'application enregistre un **groupe de buffers** ([`ProvidedBufferRing`]) ;
//! elle soumet un `recv`/`read` avec `IOSQE_BUFFER_SELECT` **sans** buffer
//! attaché ; le kernel **choisit un buffer du groupe** au moment où les données
//! arrivent et rend son **id** dans le CQE (`CQE_F_BUFFER`, 16 bits hauts de
//! `cqe->flags`). Les buffers ne sont consommés que par les connexions actives.
//!
//! Référence normative : `docs/specs/layer-0/io-uring-3b-provided.md`.
//!
//! **Mécanisme.** Un groupe possède deux mémoires : l'**anneau de descripteurs**
//! (`io_uring_buf[count]`, partagé avec le kernel — le `tail` `u16` à l'offset 14
//! du premier descripteur est avancé par **store-release**) et la **mémoire de
//! données** (`count × buf_size`, possédée). L'anneau de descripteurs est soit
//! alloué par la façade (mmap anonyme page-aligné), soit par le kernel
//! (`kernel_mmap`) puis mmappé à `IORING_OFF_PBUF_RING | (group_id << SHIFT)`.
//!
//! **Cycle checkout → traitement → return** rendu sûr par RAII
//! ([`ProvidedBuffer`]) : la libération du guard **réapprovisionne** le groupe
//! (réécrit le descripteur, avance le `tail`). En mode **incrémental**
//! (`IOU_PBUF_RING_INC`), un `CQE_F_BUF_MORE` signale que **le même buffer**
//! recevra d'autres complétions → le guard **ne réapprovisionne pas** (réappro
//! seulement à la complétion finale, sans `BUF_MORE`).
//!
//! **Legacy évacués** : `PROVIDE_BUFFERS` (31) / `REMOVE_BUFFERS` (32) — cf.
//! `docs/UNSUPPORTED.md`.

use super::{Completion, IoUring, SubmissionToken, raw, syscall};
use crate::mem::{Mapping, MmapRegion, mmap_file};
use air_sys_types::Errno;
use air_sys_types::fd::{AsRawFd, BorrowedFd};
use air_sys_types::io_uring::CompletionFlags;
use air_sys_types::mem::{MapFlags, ProtectionFlags};
use air_sys_types::net::MessageFlags;
use alloc::vec::Vec;
use core::num::{NonZeroU16, NonZeroU32};
use core::sync::atomic::{AtomicU16, Ordering};

// ───────────────────────────────────────────────────────────────────────────
// Options & status
// ───────────────────────────────────────────────────────────────────────────

/// Options de création d'un [`ProvidedBufferRing`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct ProvidedBufferRingOptions {
    /// Mémoire de l'anneau de **descripteurs** allouée par le **kernel**
    /// (`IOU_PBUF_RING_MMAP`) puis mmappée par la façade, au lieu d'être fournie
    /// par l'application.
    pub kernel_mmap: bool,
    /// Consommation **incrémentale** (`IOU_PBUF_RING_INC`) : un buffer peut servir
    /// plusieurs complétions, consommé au fur et à mesure (cf. module §5).
    pub incremental: bool,
}

/// État d'un groupe rendu par [`ProvidedBufferRing::status`] (`PBUF_STATUS`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct ProvidedBufferRingStatus {
    /// Tête courante du groupe (index de consommation côté kernel).
    pub head: u32,
}

// ───────────────────────────────────────────────────────────────────────────
// ProvidedBufferRing
// ───────────────────────────────────────────────────────────────────────────

/// Origine de la mémoire de l'**anneau de descripteurs** (page-alignée).
#[derive(Debug)]
enum RingMemory {
    /// Anneau alloué par la façade (mmap anonyme).
    App(MmapRegion),
    /// Anneau alloué par le kernel (`IOU_PBUF_RING_MMAP`) puis mmappé.
    Kernel(Mapping),
}

impl RingMemory {
    /// Base de l'anneau (`struct io_uring_buf_ring`). `*mut` : la façade écrit
    /// les descripteurs et le `tail` ; le kernel lit les descripteurs/`tail` et
    /// écrit le `head` (champs **disjoints**, pas d'écriture aliasée).
    fn base(&self) -> *mut u8 {
        match self {
            Self::App(region) => region.as_ptr().cast_mut(),
            Self::Kernel(mapping) => mapping.as_ptr().cast_mut(),
        }
    }
}

/// Groupe de **buffers fournis** *ring-mapped* (`IORING_REGISTER_PBUF_RING`, 22).
///
/// Possède l'anneau de descripteurs **et** la mémoire de données tant que le
/// groupe est enregistré ; [`ProvidedBufferRing::unregister`] les restitue
/// (désenregistre puis libère). Les buffers consommés sont **rendus** au groupe
/// par la libération du guard [`ProvidedBuffer`].
#[derive(Debug)]
pub struct ProvidedBufferRing {
    /// Identifiant de groupe (`bgid`).
    bgid: u16,
    /// Nombre de buffers (puissance de 2).
    count: u16,
    /// `count - 1` (masque d'indexation de l'anneau).
    mask: u16,
    /// Taille d'un buffer en octets.
    buf_size: u32,
    /// Mémoire de l'anneau de descripteurs (partagée avec le kernel).
    ring_mem: RingMemory,
    /// Mémoire de données possédée (`count × buf_size` octets). Le kernel y écrit
    /// les données reçues ; reste vivante tant que le groupe est enregistré.
    data: Vec<u8>,
    /// `tail` local (prochain slot où écrire un descripteur ; wrappe).
    provide_tail: u16,
    /// Nombre de buffers actuellement disponibles côté groupe (non checkout).
    available: u16,
    /// Buffer `bid` actuellement **sorti** (checkout non encore rendu). Indexé par
    /// `bid` ; rend l'accounting d'`available` **idempotent** vis-à-vis des
    /// complétions multiples d'un même buffer (mode incrémental, `BUF_MORE`).
    out_flags: Vec<bool>,
}

impl ProvidedBufferRing {
    /// `IORING_REGISTER_PBUF_RING` (22) : enregistre un groupe `group_id` de
    /// `count` buffers de `buf_size` octets (`count` **puissance de 2**), puis
    /// approvisionne les `count` buffers.
    ///
    /// # Errors
    ///
    /// [`Errno::EINVAL`] si `count` n'est pas une puissance de 2 ou si
    /// `count × buf_size` déborde ; erreurs de `mmap`/`io_uring_register`
    /// ([`Errno::ENOMEM`], [`Errno::EEXIST`] si `group_id` déjà pris).
    pub fn register(
        ring: &mut IoUring,
        group_id: u16,
        count: NonZeroU16,
        buf_size: NonZeroU32,
        opts: ProvidedBufferRingOptions,
    ) -> Result<Self, Errno> {
        let count = count.get();
        if !count.is_power_of_two() {
            return Err(Errno::EINVAL);
        }
        let buf_size = buf_size.get();
        let count_usize = usize::from(count);
        let total = count_usize
            .checked_mul(usize::try_from(buf_size).expect("u32 ⊆ usize sur cible LP64"))
            .ok_or(Errno::EINVAL)?;
        let ring_bytes = count_usize
            .checked_mul(raw::IO_URING_BUF_SIZE)
            .ok_or(Errno::EINVAL)?;
        let data = vec![0u8; total];

        let mut flags = if opts.incremental {
            raw::IOU_PBUF_RING_INC
        } else {
            0
        };
        // Mode app : anneau alloué ici (mmap anonyme page-aligné).
        let app_region = if opts.kernel_mmap {
            flags |= raw::IOU_PBUF_RING_MMAP;
            None
        } else {
            let region = MmapRegion::new_anonymous(
                ring_bytes,
                ProtectionFlags::READ | ProtectionFlags::WRITE,
                MapFlags::PRIVATE,
            )?;
            // Anneau de contrôle **pinné par le kernel** (il y écrit hors de tout
            // syscall du process) : le retirer de l'héritage au `fork` évite la
            // fenêtre COW/GUP classique des régions pinnées (ADR-132).
            super::deny_fork_inheritance(region.as_ptr(), region.len())?;
            Some(region)
        };
        let ring_addr = app_region.as_ref().map_or(0, |r| r.as_ptr() as u64);

        let reg = raw::IoUringBufReg {
            ring_addr,
            ring_entries: u32::from(count),
            bgid: group_id,
            flags,
            resv: [0; 3],
        };
        // SAFETY: PBUF_RING attend une `io_uring_buf_reg` (nr_args == 1) ; `reg`
        // vit pendant l'appel ; `ring_addr` pointe l'anneau page-aligné (mode app)
        // ou 0 (mode kernel).
        let ret = unsafe {
            syscall::register(
                ring.fd_raw(),
                raw::IORING_REGISTER_PBUF_RING,
                core::ptr::from_ref(&reg) as u64,
                1,
            )
        };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }

        // Mode kernel : mmap l'anneau alloué par le kernel.
        let ring_mem = match app_region {
            Some(region) => RingMemory::App(region),
            None => {
                let offset =
                    raw::IORING_OFF_PBUF_RING | (u64::from(group_id) << raw::IORING_OFF_PBUF_SHIFT);
                // SAFETY: `ring.fd_raw()` est un ring fd valide possédé, emprunté
                // le temps de l'appel mmap.
                let fd = unsafe { BorrowedFd::borrow_raw(ring.fd_raw()) };
                let mapping = mmap_file(
                    fd,
                    ring_bytes,
                    offset,
                    ProtectionFlags::READ | ProtectionFlags::WRITE,
                    MapFlags::SHARED,
                )?;
                // `MAP_SHARED` sur le ring fd : exactement la faille des anneaux
                // SQ/CQ/SQE (ADR-132) — un enfant forké écrirait dans les *mêmes*
                // pages que le parent (adresses de buffers, `tail`).
                super::deny_fork_inheritance(mapping.as_ptr(), mapping.len())?;
                RingMemory::Kernel(mapping)
            }
        };

        let mut this = Self {
            bgid: group_id,
            count,
            mask: count.wrapping_sub(1),
            buf_size,
            ring_mem,
            data,
            provide_tail: 0,
            available: 0,
            out_flags: vec![false; usize::from(count)],
        };
        this.provide_initial();
        Ok(this)
    }

    /// Approvisionne les `count` buffers à l'enregistrement (descripteurs
    /// `0..count`, `tail = count`).
    fn provide_initial(&mut self) {
        for bid in 0..self.count {
            // Slot == bid à l'initialisation (tail part de 0).
            self.write_descriptor(bid, bid);
        }
        self.provide_tail = self.count;
        self.available = self.count;
        self.publish_tail();
    }

    /// Écrit un descripteur `io_uring_buf` (`addr`/`len`/`bid`) dans `slot`, sans
    /// toucher l'offset 14 (`resv`/`tail`).
    fn write_descriptor(&self, slot: u16, bid: u16) {
        let base = self.ring_mem.base();
        let slot_off = usize::from(slot & self.mask)
            .checked_mul(raw::IO_URING_BUF_SIZE)
            .expect("slot borné par le masque");
        let data_off = usize::from(bid)
            .checked_mul(usize::try_from(self.buf_size).expect("u32 ⊆ usize"))
            .expect("bid × buf_size ≤ total (borné par construction)");
        let addr = self.data.as_ptr().wrapping_add(data_off) as u64;
        // SAFETY: `base` pointe l'anneau page-aligné vivant ; `slot_off` est dans
        // `count × 16` octets (slot masqué) ; les écritures `u64`/`u32`/`u16` sont
        // alignées (base page-alignée, offsets multiples de 8/4/2). On n'écrit pas
        // l'offset 14 (`tail`). `addr` désigne le buffer `bid` dans `data` (vivant).
        unsafe {
            let buf = base.add(slot_off);
            buf.cast::<u64>().write(addr);
            buf.add(8).cast::<u32>().write(self.buf_size);
            buf.add(12).cast::<u16>().write(bid);
        }
    }

    /// Publie le `tail` local par un **store-release** (rend les descripteurs
    /// écrits visibles au kernel avant l'avancée de la queue).
    fn publish_tail(&self) {
        let base = self.ring_mem.base();
        // SAFETY: `base + 14` est le mot `tail` (`u16`, 2-aligné) de l'anneau
        // vivant ; `AtomicU16` a le même layout qu'un `u16`. Store-release apparié
        // au load-acquire du kernel (protocole d'anneau de buffers).
        unsafe {
            let tail = base
                .add(raw::IO_URING_BUF_RING_TAIL_OFFSET)
                .cast::<AtomicU16>();
            (*tail).store(self.provide_tail, Ordering::Release);
        }
    }

    /// Comptabilise un **checkout** du buffer `bid` (le kernel l'a sorti pour une
    /// complétion). Idempotent : une complétion supplémentaire sur un buffer
    /// **déjà** sorti (incrémental, `BUF_MORE`) ne re-décrémente pas `available`.
    fn checkout(&mut self, bid: u16) {
        let newly_out = self
            .out_flags
            .get_mut(usize::from(bid))
            .is_some_and(|flag| {
                if *flag {
                    false
                } else {
                    *flag = true;
                    true
                }
            });
        if newly_out {
            self.available = self.available.saturating_sub(1);
        }
    }

    /// **Rend** le buffer `bid` au groupe : réécrit son descripteur au `tail`,
    /// avance et publie le `tail`, et — s'il était sorti — incrémente `available`.
    fn return_buffer(&mut self, bid: u16) {
        self.write_descriptor(self.provide_tail, bid);
        self.provide_tail = self.provide_tail.wrapping_add(1);
        self.publish_tail();
        let was_out = self
            .out_flags
            .get_mut(usize::from(bid))
            .is_some_and(|flag| {
                let prev = *flag;
                *flag = false;
                prev
            });
        if was_out {
            self.available = self.available.saturating_add(1).min(self.count);
        }
    }

    /// Tranche d'octets du buffer `bid`, longueur `len` (bornée par construction :
    /// `len ≤ buf_size` et `bid < count`).
    fn buffer_bytes(&self, bid: u16, len: usize) -> &[u8] {
        let bufsz = usize::try_from(self.buf_size).expect("u32 ⊆ usize");
        let start = usize::from(bid)
            .checked_mul(bufsz)
            .expect("bid × buf_size borné");
        let end = start.checked_add(len).expect("start + len borné");
        self.data
            .get(start..end)
            .expect("buffer borné (len ≤ buf_size, bid < count)")
    }

    /// Variante mutable de [`Self::buffer_bytes`].
    fn buffer_bytes_mut(&mut self, bid: u16, len: usize) -> &mut [u8] {
        let bufsz = usize::try_from(self.buf_size).expect("u32 ⊆ usize");
        let start = usize::from(bid)
            .checked_mul(bufsz)
            .expect("bid × buf_size borné");
        let end = start.checked_add(len).expect("start + len borné");
        self.data
            .get_mut(start..end)
            .expect("buffer borné (len ≤ buf_size, bid < count)")
    }

    /// `IORING_UNREGISTER_PBUF_RING` (23) : désenregistre le groupe et **libère**
    /// l'anneau et la mémoire de données (à la consommation de `self`).
    ///
    /// **Sûreté par construction** : un [`ProvidedBuffer`] en cours de traitement
    /// emprunte le groupe `&mut` — impossible de désenregistrer tant qu'il vit.
    /// Le code suivant **ne compile pas** :
    ///
    /// ```compile_fail
    /// # use air_sys_syscall::io_uring::{IoUring, ProvidedBufferRing, ProvidedBufferRingOptions};
    /// # use core::num::{NonZeroU16, NonZeroU32};
    /// # fn demo(ring: &mut IoUring, completion: air_sys_syscall::io_uring::Completion) {
    /// let mut group = ProvidedBufferRing::register(
    ///     ring, 0, NonZeroU16::new(4).unwrap(), NonZeroU32::new(64).unwrap(),
    ///     ProvidedBufferRingOptions::default()).unwrap();
    /// let buf = completion.into_provided_buffer(&mut group).unwrap(); // emprunte `group`
    /// let _ = group.unregister(ring).unwrap();  // déplace `group`…
    /// let _ = buf.id();                          // …emprunt encore vivant ⇒ ERREUR
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register` ([`Errno::EINVAL`] si le groupe n'est pas
    /// enregistré). En cas d'erreur, la mémoire est tout de même libérée.
    pub fn unregister(self, ring: &mut IoUring) -> Result<(), Errno> {
        let reg = raw::IoUringBufReg {
            ring_addr: 0,
            ring_entries: 0,
            bgid: self.bgid,
            flags: 0,
            resv: [0; 3],
        };
        // SAFETY: UNREGISTER_PBUF_RING attend une `io_uring_buf_reg` (bgid,
        // nr_args == 1) ; `reg` vit pendant l'appel.
        let ret = unsafe {
            syscall::register(
                ring.fd_raw(),
                raw::IORING_UNREGISTER_PBUF_RING,
                core::ptr::from_ref(&reg) as u64,
                1,
            )
        };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        Ok(())
    }

    /// `IORING_REGISTER_PBUF_STATUS` (26) : tête courante du groupe (diagnostic /
    /// régulation).
    ///
    /// # Errors
    ///
    /// Erreurs de `io_uring_register`.
    pub fn status(&self, ring: &IoUring) -> Result<ProvidedBufferRingStatus, Errno> {
        let mut st = raw::IoUringBufStatus {
            buf_group: u32::from(self.bgid),
            head: 0,
            resv: [0; 8],
        };
        // SAFETY: PBUF_STATUS attend une `io_uring_buf_status` (nr_args == 1) ; le
        // kernel y réécrit `head`. `st` vit pendant l'appel.
        let ret = unsafe {
            syscall::register(
                ring.fd_raw(),
                raw::IORING_REGISTER_PBUF_STATUS,
                core::ptr::from_mut(&mut st) as u64,
                1,
            )
        };
        if ret < 0 {
            return Err(raw::errno_from_negative_syscall_ret(ret));
        }
        Ok(ProvidedBufferRingStatus { head: st.head })
    }

    /// Identifiant de groupe (`bgid`).
    #[must_use]
    pub fn group_id(&self) -> u16 {
        self.bgid
    }

    /// Nombre de buffers actuellement disponibles (non checkout).
    #[must_use]
    pub fn available(&self) -> u16 {
        self.available
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Soumission avec sélection automatique
// ───────────────────────────────────────────────────────────────────────────

impl IoUring {
    /// `IORING_OP_RECV` (27) avec **sélection automatique** de buffer dans
    /// `group` (`IOSQE_BUFFER_SELECT`). Aucun buffer n'est attaché au slot S1.
    /// `bundle` active `IORING_RECVSEND_BUNDLE` (plusieurs buffers en un recv).
    /// Pénurie ⇒ complétion `-ENOBUFS`.
    ///
    /// # Errors
    ///
    /// [`Errno::EBUSY`] si la SQ ou le slab sont pleins ; à la complétion,
    /// `-ENOBUFS` si le groupe est vide.
    pub fn submit_receive_provided(
        &mut self,
        sock: BorrowedFd<'_>,
        group: &ProvidedBufferRing,
        flags: MessageFlags,
        bundle: bool,
    ) -> Result<SubmissionToken, Errno> {
        let fd = sock.as_raw_fd();
        let bgid = group.group_id();
        let msg_flags = flags.bits().cast_unsigned();
        self.pending_options = self.pending_options.buffer_select();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_RECV;
            sqe.fd = fd;
            sqe.len = 0; // le kernel borne par la taille du buffer choisi
            sqe.op_flags = msg_flags;
            sqe.buf_index_or_group = bgid;
            if bundle {
                sqe.ioprio |= raw::IORING_RECVSEND_BUNDLE;
            }
        })
    }

    /// `IORING_OP_READ` (22) avec sélection automatique de buffer. `length`
    /// borne le nombre d'octets lus (≤ taille du buffer). `bundle` active
    /// `IORING_RECVSEND_BUNDLE`.
    ///
    /// # Errors
    ///
    /// Voir [`IoUring::submit_receive_provided`].
    pub fn submit_read_provided(
        &mut self,
        fd: BorrowedFd<'_>,
        group: &ProvidedBufferRing,
        length: u32,
        offset: Option<u64>,
        bundle: bool,
    ) -> Result<SubmissionToken, Errno> {
        let fd = fd.as_raw_fd();
        let bgid = group.group_id();
        let off = offset.unwrap_or(u64::MAX);
        self.pending_options = self.pending_options.buffer_select();
        self.submit_op(None, |sqe| {
            sqe.opcode = raw::IORING_OP_READ;
            sqe.fd = fd;
            sqe.len = length;
            sqe.off_or_addr2 = off;
            sqe.buf_index_or_group = bgid;
            if bundle {
                sqe.ioprio |= raw::IORING_RECVSEND_BUNDLE;
            }
        })
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Consommation : le guard ProvidedBuffer
// ───────────────────────────────────────────────────────────────────────────

impl Completion {
    /// Récupère le buffer **choisi par le kernel** pour cette complétion
    /// (`CQE_F_BUFFER`). `None` si la complétion n'a pas consommé de buffer fourni
    /// (op sans sélection, ou pénurie `-ENOBUFS`).
    ///
    /// L'emprunt `&'r mut ProvidedBufferRing` interdit le désenregistrement du
    /// groupe tant que le buffer est en cours de traitement.
    #[must_use]
    pub fn into_provided_buffer<'r>(
        self,
        group: &'r mut ProvidedBufferRing,
    ) -> Option<ProvidedBuffer<'r>> {
        let bid = self.buffer_id()?;
        let flags = self.flags();
        // Longueur utile = `cqe->res` octets reçus, bornée à la taille du buffer.
        let received = usize::try_from(self.raw_result()).unwrap_or(0);
        let len = received.min(usize::try_from(group.buf_size).expect("u32 ⊆ usize"));
        // Incrémental : `CQE_F_BUF_MORE` ⇒ le kernel garde le buffer (pas de
        // réapprovisionnement à la libération du guard).
        let replenish = !flags.contains(CompletionFlags::BUF_MORE);
        group.checkout(bid);
        Some(ProvidedBuffer {
            group,
            bid,
            len,
            replenish,
        })
    }
}

/// Accès RAII aux données reçues dans un buffer fourni. **Rend le buffer au
/// groupe** (réapprovisionnement) à la libération — sauf en mode incrémental
/// quand `CQE_F_BUF_MORE` est positionné (le kernel garde le buffer).
///
/// L'emprunt `&'r mut ProvidedBufferRing` empêche le désenregistrement du groupe
/// tant que le guard vit (sûreté par construction).
#[derive(Debug)]
pub struct ProvidedBuffer<'r> {
    /// Groupe propriétaire (emprunté mut → désenregistrement interdit).
    group: &'r mut ProvidedBufferRing,
    /// Id du buffer choisi par le kernel.
    bid: u16,
    /// Octets utiles reçus (`cqe->res`, borné à `buf_size`).
    len: usize,
    /// Réapprovisionner à la libération (faux si `CQE_F_BUF_MORE`).
    replenish: bool,
}

impl ProvidedBuffer<'_> {
    /// Id du buffer (16 bits hauts de `cqe->flags`).
    #[must_use]
    pub fn id(&self) -> u16 {
        self.bid
    }

    /// Octets reçus (longueur = `cqe->res`).
    #[must_use]
    pub fn data(&self) -> &[u8] {
        self.group.buffer_bytes(self.bid, self.len)
    }

    /// Octets reçus, en accès mutable.
    #[must_use]
    pub fn data_mut(&mut self) -> &mut [u8] {
        self.group.buffer_bytes_mut(self.bid, self.len)
    }
}

impl Drop for ProvidedBuffer<'_> {
    fn drop(&mut self) {
        if self.replenish {
            self.group.return_buffer(self.bid);
        }
    }
}

// ───────────────────────────────────────────────────────────────────────────
// Tests
// ───────────────────────────────────────────────────────────────────────────
//
// Tous les tests touchent `io_uring_register`/`enter` (non modélisés par Miri) →
// `#[cfg_attr(miri, ignore)]`. La logique du guard (réapprovisionnement,
// incrémental `BUF_MORE`, branche `None`) est exercée **déterministiquement** via
// des `Completion` **synthétiques** (champs construits dans ce module enfant),
// sans dépendre du timing socket ni de la mise à `BUF_MORE` par le kernel. La
// sûreté de lifetime (désenregistrement interdit sous un buffer vivant) est
// prouvée par le doctest `compile_fail` sur `unregister`.

#[cfg(test)]
mod tests;