pub struct ForwarderClient {
pub mgmt: MgmtClient,
/* private fields */
}Expand description
Client for connecting to and communicating with a running ndn-fwd forwarder.
Fields§
§mgmt: MgmtClientTyped management API — shares the control face.
Implementations§
Source§impl ForwarderClient
impl ForwarderClient
Sourcepub async fn connect(
face_socket: impl AsRef<Path>,
) -> Result<Self, ForwarderError>
pub async fn connect( face_socket: impl AsRef<Path>, ) -> Result<Self, ForwarderError>
Connect to the router’s face socket.
Automatically attempts SHM data plane with an auto-generated name; falls back to Unix socket if SHM is unavailable or fails.
Sourcepub async fn connect_with_mtu(
face_socket: impl AsRef<Path>,
mtu: Option<usize>,
) -> Result<Self, ForwarderError>
pub async fn connect_with_mtu( face_socket: impl AsRef<Path>, mtu: Option<usize>, ) -> Result<Self, ForwarderError>
Connect with an explicit MTU hint for the SHM data plane.
mtu is passed to the router’s faces/create so the SHM ring
is sized to carry Data packets whose content body can be up
to mtu bytes. Pass None to use the default slot size
(enough for ~256 KiB content bodies). Producers that plan to
emit larger segments — e.g. chunked transfers at 1 MiB per
segment — should pass Some(chunk_size) here.
Sourcepub async fn connect_unix_only(
face_socket: impl AsRef<Path>,
) -> Result<Self, ForwarderError>
pub async fn connect_unix_only( face_socket: impl AsRef<Path>, ) -> Result<Self, ForwarderError>
Connect using only the Unix socket for data (no SHM attempt).
Sourcepub async fn connect_with_name(
face_socket: impl AsRef<Path>,
shm_name: Option<&str>,
mtu: Option<usize>,
) -> Result<Self, ForwarderError>
pub async fn connect_with_name( face_socket: impl AsRef<Path>, shm_name: Option<&str>, mtu: Option<usize>, ) -> Result<Self, ForwarderError>
Connect with an explicit SHM name for the data plane.
If shm_name is Some, creates an SHM face with that name.
If None or SHM creation fails, falls back to Unix-only mode.
mtu sizes the SHM ring slot for the expected max Data body.
Sourcepub async fn register_prefix(&self, prefix: &Name) -> Result<(), ForwarderError>
pub async fn register_prefix(&self, prefix: &Name) -> Result<(), ForwarderError>
Register a prefix with the router via rib/register.
Sourcepub async fn unregister_prefix(
&self,
prefix: &Name,
) -> Result<(), ForwarderError>
pub async fn unregister_prefix( &self, prefix: &Name, ) -> Result<(), ForwarderError>
Unregister a prefix from the router via rib/unregister.
Sourcepub async fn close(self)
pub async fn close(self)
Gracefully tear down this client: cancel ongoing ops, destroy the SHM
face (if any) via faces/destroy, then close the control socket.
Call this before dropping the client to ensure the router removes the SHM face immediately rather than waiting for GC.
Sourcepub async fn send(&self, pkt: Bytes) -> Result<(), ForwarderError>
pub async fn send(&self, pkt: Bytes) -> Result<(), ForwarderError>
Send a packet on the data plane.
On the Unix transport, packets are wrapped in a minimal NDNLPv2 LpPacket
before sending. External forwarders (yanfd/ndnd, NFD) always use LP
framing on their Unix socket faces and reject bare TLV packets;
encode_lp_packet is idempotent so already-wrapped packets pass through
unchanged. SHM transport does not use LP — the engine handles framing
internally.
Sourcepub async fn send_batch(&self, pkts: &[Bytes]) -> Result<(), ForwarderError>
pub async fn send_batch(&self, pkts: &[Bytes]) -> Result<(), ForwarderError>
Send multiple packets on the data plane in one synchronisation.
On the SHM transport this goes through [SpscHandle::send_batch],
which publishes all pkts with a single atomic tail advance and
at most one wakeup — the primary reason this API exists. On the
Unix transport this is a plain loop over send;
the socket path has no equivalent batch primitive and per-packet
cost dominates anyway.
A pipelined consumer filling a segmented-fetch window (e.g.
ndn-peek) should prefer send_batch over a loop of send
calls: it collapses the per-Interest scheduler round-trips into
a single ring transition and measurably reduces the small-
segment overhead (see docs/notes/throughput-roadmap.md).
Sourcepub async fn recv(&self) -> Option<Bytes>
pub async fn recv(&self) -> Option<Bytes>
Receive a packet from the data plane.
Returns None if the data channel is closed or the router has
disconnected. On the first call, automatically starts the disconnect
monitor (see ForwarderClient::spawn_disconnect_monitor) so that callers
do not need to start it explicitly.
Sourcepub fn spawn_disconnect_monitor(&self)
pub fn spawn_disconnect_monitor(&self)
Explicitly start the disconnect monitor.
This is called automatically on the first ForwarderClient::recv call,
so most applications do not need to call this directly.
In SHM mode the monitor watches the control socket for closure
(no probes are sent; the control socket is idle after setup). In
Unix mode the data recv() already returns None on closure, so
this is a no-op.
Safe to call multiple times — only one monitor is ever started.
Sourcepub async fn probe_alive(&self) -> bool
pub async fn probe_alive(&self) -> bool
Check if the control face is still connected by attempting a
non-blocking management probe. Returns true if the router is alive.
Called lazily by applications that detect SHM stalls.