NAME

IPC::Manager::Role::Outbox - Non-blocking outbound queue for clients

DESCRIPTION

A client that consumes this role can never block on a full transport buffer when running in non-blocking mode (send_blocking=0). Calls that would otherwise block are deferred to a per-peer outbox; the service event loop drains the outbox via drain_pending when the writable handles for the affected peers become writable again.

The role is intended for clients whose transport can return EAGAIN mid-write (FIFO-based, datagram-socket-based). Memory- or DB-backed clients do not need this role; the base class IPC::Manager::Client provides no-op fallbacks so service code can call the API uniformly.

BLOCKING MODE

The blocking flag is per-client and toggleable.

Default: send_blocking=1

Calls to send_message block until bytes are committed. Suitable for short-lived caller code where backpressure-induced waits are preferable to lost messages.

Inside a service: send_blocking=0

Set by IPC::Manager::Role::Service at startup. send_message delegates to try_send_message; queued messages flush from the service's event loop when the transport reports writability.

ORDERING (IMPORTANT)

Queued messages are NOT delivered in their enqueue order with respect to one another or to subsequently-sent direct writes. The role drains peers in arbitrary hash order. Callers that depend on strict ordering must keep the client in blocking mode.

REQUIRED METHODS

Consumers must implement:

$bool = $self->_outbox_try_write($peer, $payload, %fields)

Attempt a non-blocking write. Returns true on full delivery, false when the transport returned EAGAIN (or when an Atomic::Pipe still has bytes pending in its OUT_BUFFER after a non-blocking flush).

$fh = $self->_outbox_writable_handle($peer)

Return a filehandle that becomes writable when the kernel has room again for $peer. May return undef if no such handle exists.

$self->_outbox_set_blocking($bool)

Apply the new blocking mode to all underlying transports.

$bool = $self->_outbox_can_send($peer)

Return true if a non-blocking write to $peer would succeed immediately.

PROVIDED METHODS

try_send_message, drain_pending, pending_sends, have_pending_sends, pending_sends_to, have_writable_handles, writable_handles, send_blocking, set_send_blocking, can_send_to.

SOURCE

The source code repository for IPC::Manager can be found at https://github.com/exodist/IPC-Manager.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See https://dev.perl.org/licenses/