Struct AimDb

Source

pub struct AimDb { /* private fields */ }

Expand description

Producer-consumer database

A database instance with type-safe record registration and cross-record communication via the Emitter pattern. The runtime is held as a value (Arc<dyn RuntimeOps>) — records are the only generic surface.

See examples/ for usage.

§Examples

Illustrative (not compiled: the runtime adapter lives in a downstream crate aimdb-core cannot depend on):

use aimdb_tokio_adapter::TokioAdapter;

let mut builder = AimDbBuilder::new().runtime(Arc::new(TokioAdapter::new()?));
builder.register_record::<Temperature>(&TemperatureConfig);
let (db, runner) = builder.build().await?;

Implementations§

Source §

impl AimDb

Source

pub fn extensions(&self) -> &Extensions

Returns the extension storage frozen at build() time.

External crates (e.g. aimdb-persistence) retrieve their typed state here to service query calls. The extensions are read-only on the live handle.

Source

pub async fn build_with( rt: Arc<impl RuntimeOps + 'static>, f: impl FnOnce(&mut AimDbBuilder), ) -> DbResult<()>

Builds a database with a closure-based builder pattern

Source

pub fn produce<T>(&self, key: impl AsRef<str>, value: T) -> DbResult<()>
where T: Send + 'static + Debug + Clone,

Produces a value to a specific record by key.

Uses O(1) key-based lookup to find the correct record. Sync + fallible — only the lookup can fail; the buffer push itself is infallible.

For hot paths, prefer db.producer::<T>(key)? once and reuse the returned handle.

§Arguments

key - The record key (e.g., “sensor.temperature”)
value - The value to produce

Subscribes to a specific record by key

Uses O(1) key-based lookup to find the correct record.

§Arguments

key - The record key (e.g., “sensor.temperature”)

Source

pub fn producer<T>(&self, key: impl Into<String>) -> DbResult<Producer<T>>
where T: Send + 'static + Debug + Clone,

Creates a type-safe producer for a specific record by key

Returns a Producer<T> bound to a specific record key.

§Arguments

key - The record key (e.g., “sensor.temperature”)

Source

pub fn consumer<T>(&self, key: impl Into<String>) -> DbResult<Consumer<T>>
where T: Send + Sync + 'static + Debug + Clone,

Creates a type-safe consumer for a specific record by key

Returns a Consumer<T> bound to a specific record key.

§Arguments

key - The record key (e.g., “sensor.temperature”)

Source

pub fn resolve_key(&self, key: &str) -> Option<RecordId>

Resolve a record key to its RecordId

Useful for checking if a record exists before operations.

Source

pub fn records_of_type<T: 'static>(&self) -> Vec<RecordId>

Get all record IDs for a specific type

Returns a slice of RecordIds for all records of type T. Useful for introspection when multiple records of the same type exist.

Source

pub fn runtime_ops(&self) -> Arc<dyn RuntimeOps> ⓘ

Returns an owned Arc handle to the runtime capabilities.

Connectors that hand the runtime to a 'static engine future (e.g. the session client engine, which needs the clock for reconnect backoff/keepalive) clone it through here.

Source

pub fn runtime_ctx(&self) -> RuntimeContext

Returns a RuntimeContext over this database’s runtime — the value handed to services and context-aware (de)serializers.

Source

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

Lists all registered records (std only)

Returns metadata for all registered records, useful for remote access introspection. Available only when the std feature is enabled.

Source

pub fn try_latest_as_json(&self, record_name: &str) -> Option<Value>

Try to get record’s latest value as JSON by name

Convenience wrapper around AimDbInner::try_latest_as_json().

§Arguments

record_name - The full Rust type name (e.g., “server::Temperature”)

§Returns

Some(JsonValue) with the current value, or None if the record has no value yet, no buffer, or a buffer with no canonical latest — i.e. SpmcRing. A ring is a stream/backlog with no single “current value”; read it via a subscriber or record.drain, not a peek (record.get). Use SingleLatest for state you want to read latest-value style.

Source

pub fn try_latest_as_json_bytes(&self, record_name: &str) -> Option<Vec<u8>>

Try to get a record’s latest value as owned JSON bytes.

Semantics match try_latest_as_json: buffers without a canonical latest value (notably SpmcRing) return None. AimX record.get retains its per-connection drain fallback for those records.

Source

pub fn set_record_from_json( &self, record_name: &str, json_value: Value, ) -> DbResult<()>

Sets a record value from JSON (remote access API)

Deserializes JSON and produces the value to the record’s buffer.

SAFETY: Enforces “No Producer Override” rule - only works for configuration records without active producers.

§Arguments

record_name - Full Rust type name
json_value - JSON value to set

§Returns

Ok(()) on success, error if record not found, has producers, or deserialization fails

Source

pub fn collect_inbound_routes(&self, scheme: &str) -> Vec<(String, IngestFn)>

Collects inbound connector routes for automatic router construction (std only)

Iterates all records, filters their inbound_connectors by scheme, and returns routes with fused ingest callbacks (deserialize + produce in one typed closure — no Box<dyn Any> per message).

§Arguments

scheme - URL scheme to filter by (e.g., “mqtt”, “kafka”)

§Returns

Vector of tuples: (topic, ingest)

The topic is resolved dynamically if a TopicResolverFn is configured, otherwise the static topic from the URL is used.

Source

pub fn collect_outbound_routes(&self, scheme: &str) -> Vec<OutboundRoute>

Collects outbound routes for a specific protocol scheme

Mirrors collect_inbound_routes() for symmetry. Iterates all records, filters their outbound_connectors by scheme, and returns OutboundRoutes carrying fused serialized sources (subscribe → recv → resolve topic → serialize, all typed inside — no Box<dyn Any> per message).

This method is called by connectors during their build() phase to collect all configured outbound routes and spawn publisher tasks (usually via pump_sink).