pub struct Node { /* private fields */ }Expand description
A live participant in a dataflow.
Implementations§
Source§impl Node
impl Node
Sourcepub fn ext_store(&self, key: &ExtensionKey, value: Vec<u8>) -> Result<()>
pub fn ext_store(&self, key: &ExtensionKey, value: Vec<u8>) -> Result<()>
Stores value under key (§7.3 ExtStore).
§Errors
NodeError::Pattern for a key in a namespace a node may not write,
and NodeError::DaemonGone once the session has ended.
Sourcepub fn ext_store_with_ttl(
&self,
key: &ExtensionKey,
value: Vec<u8>,
ttl: Duration,
) -> Result<()>
pub fn ext_store_with_ttl( &self, key: &ExtensionKey, value: Vec<u8>, ttl: Duration, ) -> Result<()>
Sourcepub fn ext_load(&self, key: &ExtensionKey) -> Result<Option<Vec<u8>>>
pub fn ext_load(&self, key: &ExtensionKey) -> Result<Option<Vec<u8>>>
Reads key back, waiting up to the session’s default timeout.
§Errors
NodeError::Timeout when the daemon does not answer,
NodeError::DaemonGone once the session has ended.
Sourcepub fn ext_load_timeout(
&self,
key: &ExtensionKey,
timeout: Duration,
) -> Result<Option<Vec<u8>>>
pub fn ext_load_timeout( &self, key: &ExtensionKey, timeout: Duration, ) -> Result<Option<Vec<u8>>>
Reads key back, waiting up to timeout.
§Errors
As Node::ext_load, plus NodeError::BlockingInAsync when the
caller may not block.
Sourcepub async fn ext_load_async(
&self,
key: &ExtensionKey,
) -> Result<Option<Vec<u8>>>
pub async fn ext_load_async( &self, key: &ExtensionKey, ) -> Result<Option<Vec<u8>>>
Sourcepub async fn ext_load_async_timeout(
&self,
key: &ExtensionKey,
timeout: Duration,
) -> Result<Option<Vec<u8>>>
pub async fn ext_load_async_timeout( &self, key: &ExtensionKey, timeout: Duration, ) -> Result<Option<Vec<u8>>>
Sourcepub fn ext_drop(&self, key: &ExtensionKey) -> Result<()>
pub fn ext_drop(&self, key: &ExtensionKey) -> Result<()>
Sourcepub fn ext_key(name: impl Into<String>) -> Result<ExtensionKey>
pub fn ext_key(name: impl Into<String>) -> Result<ExtensionKey>
A validated key in the user namespace.
§Errors
NodeError::Id when the name fails the identifier grammar.
Source§impl Node
impl Node
Sourcepub fn log(&self, level: LogLevel, message: impl Into<String>)
pub fn log(&self, level: LogLevel, message: impl Into<String>)
Emits a record at level.
Never fails: see the module documentation.
Sourcepub fn log_with_fields(
&self,
level: LogLevel,
message: impl Into<String>,
fields: BTreeMap<String, String>,
)
pub fn log_with_fields( &self, level: LogLevel, message: impl Into<String>, fields: BTreeMap<String, String>, )
Emits a record at level with structured fields (§9.1
log_with_fields).
Sourcepub fn try_log(
&self,
level: LogLevel,
message: impl Into<String>,
fields: BTreeMap<String, String>,
) -> Result<()>
pub fn try_log( &self, level: LogLevel, message: impl Into<String>, fields: BTreeMap<String, String>, ) -> Result<()>
Emits a record, reporting whether it reached the wire.
The local tracing emission happens either way — a node whose daemon
has gone still deserves its own logs.
§Errors
crate::NodeError::DaemonGone once the session has ended, and
crate::NodeError::Backpressure when the writer is behind.
Source§impl Node
impl Node
Sourcepub fn from_registration(
registration: Registration,
type_check: TypeCheckMode,
orphan: Option<OrphanGuard>,
) -> (Self, EventStream)
pub fn from_registration( registration: Registration, type_check: TypeCheckMode, orphan: Option<OrphanGuard>, ) -> (Self, EventStream)
Builds a node around a completed registration.
Sourcepub fn init_from_env() -> Result<(Self, EventStream)>
pub fn init_from_env() -> Result<(Self, EventStream)>
Joins a dataflow using the ASTRS_NODE_CONFIG blob (§24.2).
§Errors
NodeError::Config when the blob is missing or malformed, and
whatever NodeBuilder::connect reports.
Sourcepub fn builder() -> NodeBuilder
pub fn builder() -> NodeBuilder
A builder for a node that needs to override something.
Sourcepub fn init_from_node_id(
node_id: impl AsRef<str>,
) -> Result<(Self, EventStream)>
pub fn init_from_node_id( node_id: impl AsRef<str>, ) -> Result<(Self, EventStream)>
Sourcepub fn init_testing() -> Result<TestHarness>
pub fn init_testing() -> Result<TestHarness>
Spins an in-process mock daemon and joins it (§9.1’s init_testing).
§Errors
NodeError::Testing when the harness cannot be started.
Sourcepub fn output<T: AstrsMessage>(
&mut self,
output: impl AsRef<str>,
) -> Result<Output<T>>
pub fn output<T: AstrsMessage>( &mut self, output: impl AsRef<str>, ) -> Result<Output<T>>
A typed publishing handle for output (§9.1).
§Errors
NodeError::UnknownOutput when the node does not declare it or a
handle is already open, and NodeError::TypeMismatch when the
port’s declared URN disagrees with T under
ASTRS_TYPE_CHECK=error (§9.2).
Sourcepub fn raw_output(&mut self, output: impl AsRef<str>) -> Result<RawOutput>
pub fn raw_output(&mut self, output: impl AsRef<str>) -> Result<RawOutput>
An untyped publishing handle for output.
§Errors
NodeError::UnknownOutput when the node does not declare it or a
handle is already open.
Sourcepub fn input_source(&self, input: impl AsRef<str>) -> Option<PortRef>
pub fn input_source(&self, input: impl AsRef<str>) -> Option<PortRef>
The producer port behind one of this node’s inputs.
Event::Input deliberately does not carry it — a node’s input has one
source in the manifest, so it is a property of the wiring rather than
of the message.
Sourcepub fn request_events(
&self,
max_batch: u32,
timeout: Option<Duration>,
) -> Result<()>
pub fn request_events( &self, max_batch: u32, timeout: Option<Duration>, ) -> Result<()>
Asks the daemon for the next event(s) explicitly (§7.3 NextEvent).
The node API is push-based: a node that simply reads its stream never needs this, and the daemon delivers as messages arrive. A node running its own event loop — an operator host, a bridge draining another runtime — uses it to control when work arrives, which is exactly what the verb exists for.
max_batch bounds how many events one answer may carry; timeout
asks the daemon to answer with an empty batch rather than blocking
forever.
§Errors
NodeError::DaemonGone once the session has ended.
Sourcepub fn request_next_event(&self) -> Result<()>
pub fn request_next_event(&self) -> Result<()>
Sourcepub fn close_outputs(&mut self) -> Result<()>
pub fn close_outputs(&mut self) -> Result<()>
Closes every output at once, which is what a node does as it exits
(§7.3 CloseOutputs).
§Errors
NodeError::DaemonGone once the session has ended.
Sourcepub fn dataflow_id(&self) -> DataflowId
pub fn dataflow_id(&self) -> DataflowId
The dataflow this node belongs to.
Sourcepub fn session_id(&self) -> SessionId
pub fn session_id(&self) -> SessionId
The connection’s session id (§7.2).
Sourcepub fn descriptor(&self) -> &NodeSpawnSpec
pub fn descriptor(&self) -> &NodeSpawnSpec
The node’s effective specification, as the daemon assigned it.
Sourcepub fn is_restart(&self) -> bool
pub fn is_restart(&self) -> bool
Whether this process is a restart of a node that ran before (§12).
Sourcepub fn restart_count(&self) -> u64
pub fn restart_count(&self) -> u64
How many times this node has been restarted; 0 on a first spawn.
Sourcepub fn generation(&self) -> u64
pub fn generation(&self) -> u64
This node’s incarnation counter — the same number as
Node::restart_count, under the name the wire uses.
Sourcepub fn hlc_now(&self) -> HlcTimestamp
pub fn hlc_now(&self) -> HlcTimestamp
The next hybrid-logical-clock reading (§4.3).
Sourcepub fn metadata(&self) -> Metadata
pub fn metadata(&self) -> Metadata
A fresh metadata block stamped with Node::hlc_now.
Sourcepub const fn type_check(&self) -> TypeCheckMode
pub const fn type_check(&self) -> TypeCheckMode
How strictly typed handles check declared types (§9.2).
Sourcepub fn stats(&self) -> SessionStats
pub fn stats(&self) -> SessionStats
A snapshot of the session’s counters.
Sourcepub fn queue_snapshot(&self, input: impl AsRef<str>) -> Option<QueueSnapshot>
pub fn queue_snapshot(&self, input: impl AsRef<str>) -> Option<QueueSnapshot>
A point-in-time reading of one input’s queue (§11.2).
The counters astrs list and the TUI show per node: depth, how many
of those are eviction-immune, and how many messages the policy has
dropped.
Sourcepub fn queue_snapshots(&self) -> Vec<(DataId, QueueSnapshot)>
pub fn queue_snapshots(&self) -> Vec<(DataId, QueueSnapshot)>
Every input’s queue counters, in name order.
Sourcepub fn stream_stats(&self) -> StreamStats
pub fn stream_stats(&self) -> StreamStats
The event stream’s own counters.
Sourcepub fn route_planes(&self) -> Vec<(DataId, RoutePlane)>
pub fn route_planes(&self) -> Vec<(DataId, RoutePlane)>
Which plane every known output is publishing on (§6.3).
The producer end of the route. Node::input_planes is the consumer
end, and the two are kept apart because an id names an output or an
input, never both, and a node with an image input and an image
output would otherwise have two rows nobody could tell apart.
Sourcepub fn input_planes(&self) -> Vec<(DataId, RoutePlane)>
pub fn input_planes(&self) -> Vec<(DataId, RoutePlane)>
Which plane every input the daemon has spoken about is read from (§6.3).
An input reaches RoutePlane::Shm
on its own: the daemon says which segment feeds it, the session
attaches, and the payloads that arrive are
Payload::is_zero_copy. An input the
daemon has never mentioned does not appear at all.
Sourcepub fn input_plane(&self, input: impl AsRef<str>) -> RoutePlane
pub fn input_plane(&self, input: impl AsRef<str>) -> RoutePlane
Which plane one input is read from (§6.3).
RoutePlane::Daemon for an input
that is not on a ring, including one this node does not declare.
Sourcepub fn input_plane_stats(&self) -> InputPlaneStats
pub fn input_plane_stats(&self) -> InputPlaneStats
What the consumer-side plane has done: attachments, samples read straight out of a ring, and the §6.2 fallbacks (§6.3, §13).
Sourcepub fn input_segment(&self, input: impl AsRef<str>) -> Option<ShmSegmentSpec>
pub fn input_segment(&self, input: impl AsRef<str>) -> Option<ShmSegmentSpec>
The segment one input reads from, when it is on a ring (§6.2).
The geometry the daemon chose — name, generation, slot count and slot size — which is what a probe needs to say whether the addresses it saw cycled through the ring.
Sourcepub fn is_orphaned(&self) -> bool
pub fn is_orphaned(&self) -> bool
Whether the orphan guard has observed its parent’s disappearance (§4.2).
Sourcepub fn session(&self) -> &Arc<SessionShared> ⓘ
pub fn session(&self) -> &Arc<SessionShared> ⓘ
The shared session state, for the patterns and the testing harness.
Sourcepub fn shutdown(&mut self) -> Result<()>
pub fn shutdown(&mut self) -> Result<()>
Closes every output and ends the session.
Called by Drop; explicit when a node wants to observe the result.
§Errors
NodeError::DaemonGone when the session had already ended, which is
not a failure so much as a statement of fact.
Sourcepub async fn join(&mut self)
pub async fn join(&mut self)
Waits for the session’s tasks to finish, after Node::shutdown.
Used by the testing harness to make shutdown deterministic.
Sourcepub async fn flush_outputs(&mut self)
pub async fn flush_outputs(&mut self)
This node’s private drain_writer’s safe-to-call-from-anywhere
twin: waits, asynchronously, for the writer task to finish
sending everything already queued (typically right after
Node::shutdown or a last RawOutput::send_batch), bounded by
the same SHUTDOWN_DRAIN timeout.
drain_writer exists for exactly one caller — Drop — which
cannot .await, so on a current-thread runtime it can only bail
out rather than risk blocking that runtime’s one worker on the
very task that has to do the flushing (see its own docs for the
loss that leaves open: the M1 pipeline losing its last frame on
one run in twenty). A caller that is already inside an async
context — a node built with NodeBuilder::connect_async, which
is precisely a caller for whom blocking was never on the table —
has no such excuse: awaiting the writer here is cooperative, not
blocking, and closes the gap drain_writer cannot on exactly the
runtime flavor that gap matters most on.
Only the writer is awaited, matching drain_writer: the reader
lives until the daemon closes the socket, and a caller flushing
its own outputs has no reason to wait for that. Idempotent —
calling this (or letting the node drop) again afterward is a
no-op, since the tasks are taken once.
Sourcepub fn stop_cause_of(error: &NodeError) -> Option<StopCause>
pub fn stop_cause_of(error: &NodeError) -> Option<StopCause>
The stop cause a node should report for error, or None when it is
not an ending.
Source§impl Node
impl Node
Sourcepub fn goal<T: AstrsMessage>(
&self,
output: &mut Output<T>,
value: impl Into<T>,
) -> Result<GoalId>
pub fn goal<T: AstrsMessage>( &self, output: &mut Output<T>, value: impl Into<T>, ) -> Result<GoalId>
Sends a typed goal, returning its id (§9.4).
The goal carries goal_status = Accepted, which is the first state of
the FSM: a client that has sent a goal and heard nothing knows it is
accepted-and-not-yet-executing rather than in no state at all.
§Errors
As Output::send.
Sourcepub fn goal_bytes(
&self,
output: &mut RawOutput,
payload: impl AsRef<[u8]>,
) -> Result<GoalId>
pub fn goal_bytes( &self, output: &mut RawOutput, payload: impl AsRef<[u8]>, ) -> Result<GoalId>
Sourcepub fn goal_status<T: AstrsMessage>(
&self,
output: &mut Output<T>,
goal: &GoalId,
status: GoalStatus,
value: impl Into<T>,
) -> Result<()>
pub fn goal_status<T: AstrsMessage>( &self, output: &mut Output<T>, goal: &GoalId, status: GoalStatus, value: impl Into<T>, ) -> Result<()>
Sourcepub fn goal_status_bytes(
&self,
output: &mut RawOutput,
goal: &GoalId,
status: GoalStatus,
payload: impl AsRef<[u8]>,
) -> Result<()>
pub fn goal_status_bytes( &self, output: &mut RawOutput, goal: &GoalId, status: GoalStatus, payload: impl AsRef<[u8]>, ) -> Result<()>
Sourcepub fn goal_signal(
&self,
output: &mut RawOutput,
goal: &GoalId,
status: GoalStatus,
) -> Result<()>
pub fn goal_signal( &self, output: &mut RawOutput, goal: &GoalId, status: GoalStatus, ) -> Result<()>
Reports a status update with no payload — the common case for
Accepted, Canceling and a bare Aborted.
§Errors
Sourcepub fn goal_metadata(&self, goal: &GoalId, status: GoalStatus) -> Metadata
pub fn goal_metadata(&self, goal: &GoalId, status: GoalStatus) -> Metadata
The metadata a status update for goal carries.
Source§impl Node
impl Node
Sourcepub fn service_request<T: AstrsMessage>(
&self,
output: &mut Output<T>,
value: impl Into<T>,
) -> Result<RequestId>
pub fn service_request<T: AstrsMessage>( &self, output: &mut Output<T>, value: impl Into<T>, ) -> Result<RequestId>
Sourcepub fn service_request_bytes(
&self,
output: &mut RawOutput,
payload: impl AsRef<[u8]>,
) -> Result<RequestId>
pub fn service_request_bytes( &self, output: &mut RawOutput, payload: impl AsRef<[u8]>, ) -> Result<RequestId>
Publishes an untyped service request, returning its correlation id.
§Errors
Sourcepub fn service_response<T: AstrsMessage>(
&self,
output: &mut Output<T>,
request: &Metadata,
value: impl Into<T>,
) -> Result<()>
pub fn service_response<T: AstrsMessage>( &self, output: &mut Output<T>, request: &Metadata, value: impl Into<T>, ) -> Result<()>
Publishes a typed response to request (§9.4).
request is the request’s metadata; the id is copied from it, so a
server cannot answer with the wrong one.
§Errors
NodeError::Pattern when request carries no request_id, plus
whatever Output::send reports.
Sourcepub fn service_response_bytes(
&self,
output: &mut RawOutput,
request: &Metadata,
payload: impl AsRef<[u8]>,
) -> Result<()>
pub fn service_response_bytes( &self, output: &mut RawOutput, request: &Metadata, payload: impl AsRef<[u8]>, ) -> Result<()>
Sourcepub fn response_metadata(&self, request: &Metadata) -> Result<Metadata>
pub fn response_metadata(&self, request: &Metadata) -> Result<Metadata>
The metadata a response to request must carry.
Exposed for a node that builds its own payload but wants the correlation handled for it.
§Errors
NodeError::Pattern when request carries no request_id.
Source§impl Node
impl Node
Sourcepub fn stream_chunk(
&self,
output: &mut RawOutput,
writer: &mut StreamWriter,
payload: impl AsRef<[u8]>,
fin: bool,
) -> Result<ChunkRef>
pub fn stream_chunk( &self, output: &mut RawOutput, writer: &mut StreamWriter, payload: impl AsRef<[u8]>, fin: bool, ) -> Result<ChunkRef>
Publishes one stream chunk (§9.4).
The writer advances its own (segment, seq) bookkeeping, so a node
never numbers a chunk by hand.
§Errors
Sourcepub fn stream_chunk_with(
&self,
output: &mut RawOutput,
writer: &mut StreamWriter,
payload: impl AsRef<[u8]>,
fin: bool,
flush: bool,
) -> Result<ChunkRef>
pub fn stream_chunk_with( &self, output: &mut RawOutput, writer: &mut StreamWriter, payload: impl AsRef<[u8]>, fin: bool, flush: bool, ) -> Result<ChunkRef>
Publishes one stream chunk, optionally asking for an immediate delivery.
§Errors
Sourcepub fn stream_segment(
&self,
output: &mut RawOutput,
writer: &mut StreamWriter,
payload: &[u8],
chunk_size: usize,
) -> Result<usize>
pub fn stream_segment( &self, output: &mut RawOutput, writer: &mut StreamWriter, payload: &[u8], chunk_size: usize, ) -> Result<usize>
Publishes a whole payload as a run of chunks of at most chunk_size
bytes, ending the segment.
§Errors
NodeError::Pattern for a zero chunk size, plus whatever
Node::stream_chunk reports.