Struct AimxConnection 

pub struct AimxConnection { /* private fields */ }

A live connection to an AimDB instance over the shared session engine.

Holds the cheap-clone ClientHandle (use handle to issue raw call/subscribe/write) and the driven engine task. Typed wrappers cover the common AimX methods.

Implementations

impl AimxConnection

pub async fn connect(endpoint: &str) -> ClientResult<Self>

Resolve endpoint to a transport, start the engine, and complete the hello handshake, bounded by DEFAULT_CONNECT_TIMEOUT.

endpoint is a scheme:// URL — unix://PATH / uds://PATH, serial://DEVICE?baud=N — or a bare path (the unix:// shorthand). The scheme picks the transport via crate::endpoint::dial; an unknown scheme (or one whose transport isn’t compiled in) fails before the engine starts.

pub async fn connect_with_timeout( endpoint: &str, connect_timeout: Duration, ) -> ClientResult<Self>

Like connect, but with an explicit handshake deadline.

pub async fn connect_over(dialer: impl Dialer + 'static) -> ClientResult<Self>

Connect over an explicit Dialer, bypassing endpoint resolution — for transports the resolver doesn’t cover, or a pre-built dialer.

pub async fn connect_over_with_timeout( dialer: impl Dialer + 'static, connect_timeout: Duration, ) -> ClientResult<Self>

Like connect_over, with an explicit handshake deadline.

pub fn handle(&self) -> &ClientHandle

The raw engine handle — call / subscribe / write for methods the typed wrappers below don’t cover.

pub fn server_info(&self) -> &WelcomeMessage

The server’s Welcome (permissions, writable records) from the handshake.

pub async fn list_records(&self) -> ClientResult<Vec<RecordMetadata>>

List all registered records.

pub async fn get_record(&self, name: &str) -> ClientResult<Value>

Get a record’s current value.

For a SingleLatest/state record this is a non-destructive read. A ring (SpmcRing) has no canonical latest, so the server returns the most recent value from this connection’s drain cursor — which advances that cursor (interleaving with drain_record) and is empty until the ring produces a value after the connection first reads it. Prefer drain_record for ring/history records.

pub async fn set_record(&self, name: &str, value: Value) -> ClientResult<Value>

Set a record’s value (RPC; awaits the server’s reply).

pub fn subscribe( &self, pattern: &str, ) -> ClientResult<BoxStream<'static, Result<RecordUpdate, ClientError>>>

Subscribe to a record or topic pattern.

Yields the full RecordUpdate — value, per-record topic, skipped gap count and snapshot_end burst marker — so a consumer that cares about completeness (a watcher, a mirror, an archiver) can see what the engine dropped. One that only wants values drops the rest:

let values = conn.subscribe("temp.vienna")?
    .filter_map(|r| futures::future::ready(r.ok().and_then(|u| u.value)));

Wildcards (#, *) are supported: one subscription fans in every matching record, each update tagged with the record that fired. The engine routes events back by the request id it owns, so there is no subscription_id to track.

A refused subscription — denied, or past the server’s per-connection limit — yields one Err item and then ends, so it stays distinguishable from a clean end (disconnect, closed record), which is simply None. Dropping the stream stops local delivery.

pub fn write_record(&self, name: &str, value: Value) -> ClientResult<()>

Fire-and-forget write to a record (no reply; routes through the server’s producer/arbiter path — single-writer-per-key stays intact).

pub async fn drain_record(&self, name: &str) -> ClientResult<DrainResponse>

Drain all values accumulated since the previous drain of name (a destructive read against this connection’s per-record cursor).

pub async fn drain_record_with_limit( &self, name: &str, limit: u32, ) -> ClientResult<DrainResponse>

Drain at most limit values from name.

pub async fn query(&self, params: Value) -> ClientResult<Value>

Run a persistence query (requires the server’s with_persistence()).

pub async fn graph_nodes(&self) -> ClientResult<Vec<Value>>

All nodes in the dependency graph.

pub async fn graph_edges(&self) -> ClientResult<Vec<Value>>

All edges in the dependency graph.

pub async fn graph_topo_order(&self) -> ClientResult<Vec<String>>

Record keys in topological order.

pub async fn reset_stage_profiling(&self) -> ClientResult<Value>

Reset stage-profiling counters (server built with profiling; needs write permission).

pub async fn reset_buffer_metrics(&self) -> ClientResult<Value>

Reset buffer-metrics counters (server built with metrics; needs write permission).

Trait Implementations

impl Drop for AimxConnection

fn drop(&mut self)

Executes the destructor for this type.

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.