Struct Doorbell 

pub struct Doorbell { /* private fields */ }

A doorbell for cross-process wakeup.

Uses a Unix domain socketpair (SOCK_DGRAM) for bidirectional signaling. Wrapped in AsyncFd for async readiness notification via epoll/kqueue.

Implementations

impl Doorbell

pub fn create_pair() -> Result<(Self, DoorbellHandle)>

Create a socketpair and return (host_doorbell, guest_handle).

The guest_handle should be passed to the plugin (e.g., via command line). The host keeps the Doorbell.

pub fn from_handle(handle: DoorbellHandle) -> Result<Self>

Create a Doorbell from an opaque handle (guest/plugin side).

This is the cross-platform way to reconstruct a Doorbell in a spawned process. Consumes the handle, taking ownership of the underlying file descriptor.

pub fn from_raw_fd(fd: RawFd) -> Result<Self>

Create a Doorbell from a raw file descriptor (plugin side).

Prefer Self::from_handle for cross-platform code.

Safety

The fd must be a valid, open file descriptor from a socketpair.

pub async fn signal(&self) -> SignalResult

Signal the other side.

Sends a 1-byte datagram. If the socket buffer is full (EAGAIN), the signal is dropped (the other side is already signaled).

Returns SignalResult::PeerDead if the peer has disconnected (EPIPE, ECONNRESET, ENOTCONN). This is logged once per doorbell to avoid spam.

pub fn is_peer_dead(&self) -> bool

Check if the peer appears to be dead (signal has failed).

pub async fn wait(&self) -> Result<()>

Wait for a signal from the other side.

pub fn drain(&self)

Drain any pending signals without blocking.

pub async fn accept(&self) -> Result<()>

Accept an incoming connection (no-op on Unix).

On Unix, socketpairs are already connected when created, so this is a no-op. On Windows, named pipe servers must call this to accept the client connection.

pub fn pending_bytes(&self) -> usize

Get the number of bytes pending in the socket buffer (for diagnostics).