bornera 0.0.1-rc.4

Deterministic connection ownership for native protocol clients.
Documentation
//! Cloneable producer for one exact connection's bounded command mailbox.

use std::io;

use bornera_core::OperationId;
use calandria::{Deadline, MailboxSender, TrySendError};

use crate::{ConnectionCommand, ConnectionToken};

/// Acknowledgement-free notification handle for one Bornera selector.
///
/// Each call reaches the underlying Mio waker. Producers must publish durable state
/// before pulsing, and the connection-set owner must drain or rescan that state.
#[derive(Clone, Debug)]
pub struct ConnectionPulseHandle {
    pulse: calandria_mio::MioPulseHandle,
}

impl ConnectionPulseHandle {
    pub(crate) fn new(pulse: calandria_mio::MioPulseHandle) -> Self {
        Self { pulse }
    }

    /// Notifies the selector without a Calandria acknowledgement domain.
    pub fn pulse(&self) -> io::Result<()> {
        self.pulse.pulse()
    }
}

/// Cross-thread producer bound to one generation-fenced connection.
///
/// Successful enqueue means only that the bounded set mailbox owns the
/// command. The authoritative confirmation for admission is
/// [`crate::ConnectionEvent::AdmissionOpened`].
#[derive(Clone, Debug)]
pub struct ConnectionPort {
    connection: ConnectionToken,
    sender: MailboxSender<ConnectionCommand>,
}

impl ConnectionPort {
    pub(crate) const fn new(
        connection: ConnectionToken,
        sender: MailboxSender<ConnectionCommand>,
    ) -> Self {
        Self { connection, sender }
    }

    /// Returns the exact set generation targeted by this producer.
    pub const fn connection(&self) -> ConnectionToken {
        self.connection
    }

    /// Queues admission opening after the caller has established its protocol session.
    pub fn open_admission(&self) -> Result<(), TrySendError<ConnectionCommand>> {
        self.sender
            .try_send_control(ConnectionCommand::OpenAdmission {
                connection: self.connection,
            })
    }

    /// Queues explicit local cancellation of one accepted operation.
    pub fn cancel(&self, operation: OperationId) -> Result<(), TrySendError<ConnectionCommand>> {
        self.sender.try_send(ConnectionCommand::Cancel {
            connection: self.connection,
            operation,
        })
    }

    /// Queues admission closure and operation plus transport draining through one deadline.
    pub fn begin_drain(&self, deadline: Deadline) -> Result<(), TrySendError<ConnectionCommand>> {
        self.sender.try_send_control(ConnectionCommand::BeginDrain {
            connection: self.connection,
            deadline,
        })
    }

    /// Queues forced mechanical closure, preempting transport-local graceful shutdown.
    pub fn close(&self) -> Result<(), TrySendError<ConnectionCommand>> {
        self.sender.try_send_control(ConnectionCommand::Close {
            connection: self.connection,
        })
    }
}