Skip to main content

Node

Struct Node 

Source
pub struct Node { /* private fields */ }
Expand description

A live participant in a dataflow.

Implementations§

Source§

impl Node

Source

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.

Source

pub fn ext_store_with_ttl( &self, key: &ExtensionKey, value: Vec<u8>, ttl: Duration, ) -> Result<()>

Stores value under key, to be reclaimed after ttl.

§Errors

As Node::ext_store.

Source

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.

Source

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.

Source

pub async fn ext_load_async( &self, key: &ExtensionKey, ) -> Result<Option<Vec<u8>>>

The async twin of Node::ext_load.

§Errors

As Node::ext_load.

Source

pub async fn ext_load_async_timeout( &self, key: &ExtensionKey, timeout: Duration, ) -> Result<Option<Vec<u8>>>

The async twin of Node::ext_load_timeout.

§Errors

As Node::ext_load.

Source

pub fn ext_drop(&self, key: &ExtensionKey) -> Result<()>

Drops key from the table (§7.3 ExtDrop).

§Errors

NodeError::DaemonGone once the session has ended.

Source

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

Source

pub fn log(&self, level: LogLevel, message: impl Into<String>)

Emits a record at level.

Never fails: see the module documentation.

Source

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).

Source

pub fn log_error(&self, message: impl Into<String>)

Emits an ERROR record.

Source

pub fn log_warn(&self, message: impl Into<String>)

Emits a WARN record.

Source

pub fn log_info(&self, message: impl Into<String>)

Emits an INFO record.

Source

pub fn log_debug(&self, message: impl Into<String>)

Emits a DEBUG record.

Source

pub fn log_trace(&self, message: impl Into<String>)

Emits a TRACE record.

Source

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

pub fn log_record( &self, level: LogLevel, message: impl Into<String>, ) -> LogRecord

Builds a record stamped with this node’s identity, without sending it.

For a caller that wants to batch, filter or record locally before the wire sees anything.

Source

pub fn send_log(&self, record: LogRecord) -> Result<()>

Sends an already-built record.

§Errors

As Node::try_log.

Source§

impl Node

Source

pub fn from_registration( registration: Registration, type_check: TypeCheckMode, orphan: Option<OrphanGuard>, ) -> (Self, EventStream)

Builds a node around a completed registration.

Source

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.

Source

pub fn builder() -> NodeBuilder

A builder for a node that needs to override something.

Source

pub fn init_from_node_id( node_id: impl AsRef<str>, ) -> Result<(Self, EventStream)>

Attaches a path: dynamic node under node_id (§8.3).

§Errors

As NodeBuilder::connect.

Source

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.

Source

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).

Source

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.

Source

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.

Source

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.

Source

pub fn request_next_event(&self) -> Result<()>

Node::request_events with the protocol’s default batch size.

§Errors

As Node::request_events.

Source

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.

Source

pub fn id(&self) -> &NodeId

The node’s id (§9.1).

Source

pub fn dataflow_id(&self) -> DataflowId

The dataflow this node belongs to.

Source

pub fn session_id(&self) -> SessionId

The connection’s session id (§7.2).

Source

pub fn descriptor(&self) -> &NodeSpawnSpec

The node’s effective specification, as the daemon assigned it.

Source

pub fn is_restart(&self) -> bool

Whether this process is a restart of a node that ran before (§12).

Source

pub fn restart_count(&self) -> u64

How many times this node has been restarted; 0 on a first spawn.

Source

pub fn generation(&self) -> u64

This node’s incarnation counter — the same number as Node::restart_count, under the name the wire uses.

Source

pub fn hlc_now(&self) -> HlcTimestamp

The next hybrid-logical-clock reading (§4.3).

Source

pub fn metadata(&self) -> Metadata

A fresh metadata block stamped with Node::hlc_now.

Source

pub const fn type_check(&self) -> TypeCheckMode

How strictly typed handles check declared types (§9.2).

Source

pub fn stats(&self) -> SessionStats

A snapshot of the session’s counters.

Source

pub fn input_ids(&self) -> Vec<DataId>

The inputs this node reads, in name order.

Source

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.

Source

pub fn queue_snapshots(&self) -> Vec<(DataId, QueueSnapshot)>

Every input’s queue counters, in name order.

Source

pub fn stream_stats(&self) -> StreamStats

The event stream’s own counters.

Source

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.

Source

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.

Source

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.

Source

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).

Source

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.

Source

pub fn is_orphaned(&self) -> bool

Whether the orphan guard has observed its parent’s disappearance (§4.2).

Source

pub fn is_closed(&self) -> bool

Whether the session has ended.

Source

pub fn session(&self) -> &Arc<SessionShared> ⓘ

The shared session state, for the patterns and the testing harness.

Source

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.

Source

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.

Source

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.

Source

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

Source

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.

Source

pub fn goal_bytes( &self, output: &mut RawOutput, payload: impl AsRef<[u8]>, ) -> Result<GoalId>

Sends an untyped goal, returning its id.

§Errors

As RawOutput::send_bytes.

Source

pub fn goal_status<T: AstrsMessage>( &self, output: &mut Output<T>, goal: &GoalId, status: GoalStatus, value: impl Into<T>, ) -> Result<()>

Reports a typed status update for goal (§9.4).

§Errors

As Output::send.

Source

pub fn goal_status_bytes( &self, output: &mut RawOutput, goal: &GoalId, status: GoalStatus, payload: impl AsRef<[u8]>, ) -> Result<()>

Reports an untyped status update for goal.

§Errors

As RawOutput::send_bytes.

Source

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

As RawOutput::send_bytes.

Source

pub fn goal_metadata(&self, goal: &GoalId, status: GoalStatus) -> Metadata

The metadata a status update for goal carries.

Source§

impl Node

Source

pub fn service_request<T: AstrsMessage>( &self, output: &mut Output<T>, value: impl Into<T>, ) -> Result<RequestId>

Publishes a typed service request, returning its correlation id (§9.4).

§Errors

As Output::send.

Source

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

As RawOutput::send_bytes.

Source

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.

Source

pub fn service_response_bytes( &self, output: &mut RawOutput, request: &Metadata, payload: impl AsRef<[u8]>, ) -> Result<()>

Publishes an untyped response to request.

§Errors

As Node::service_response.

Source

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

Source

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

As RawOutput::send_bytes.

Source

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

As RawOutput::send_bytes.

Source

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.

Source

pub fn stream_chunk_of(event: &Event) -> Option<(DataId, ChunkRef)>

The input a stream chunk arrived on, when an event is one.

Trait Implementations§

Source§

impl Debug for Node

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Drop for Node

Source§

fn drop(&mut self)

Executes the destructor for this type. Read more
Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

§

impl Freeze for Node

§

impl RefUnwindSafe for Node

§

impl Send for Node

§

impl Sync for Node

§

impl Unpin for Node

§

impl UnsafeUnpin for Node

§

impl UnwindSafe for Node

Blanket Implementations§

Source§

impl<T> Allocation for T
where T: RefUnwindSafe + Send + Sync,

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> MaybeDebug for T

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more