Stardust Rust: query subscription signatures, sync release vs async docs

stardust-subscribe-signatures.md

Stardust Rust: subscribing to a query today

Sync: release alpha-2610112101 (abi/bindings/rust/src/db.rs)

impl Database {
    pub fn query<'a>(&self, source: impl Into<Source<'a>>) -> Result<Query>; // stored path or inline Document
}

impl Query {
    pub fn subscribe(&self, parameters: Option<&Document>, options: &RunOptions) -> Result<Subscription>;
}

impl Subscription {
    pub fn next(&self, max_wait: Duration) -> Result<Option<Event>>; // Ok(None) = timed out
    pub fn events(&self) -> Events<'_>; // Iterator<Item = Result<Event>>, waits with no limit
    pub fn cancel(&self);
    pub fn close(&self);
}

pub struct Event {
    pub sequence: i64,
    pub superseded: i64,
    pub transaction: i64,
    pub result: Document,
}

Async: the docs (Rust reference)

impl Query {
    pub async fn subscribe(&self, parameters: Option<&Document>, options: &RunOptions) -> Result<Subscription>;
}

impl Subscription {
    pub async fn next(&self, max_wait: Duration) -> Result<Option<Event>>;
    pub async fn events(&self) -> Events<'_>;
    pub async fn cancel(&self) -> Result<()>;
    pub async fn close(&self) -> Result<()>;
}

Notes

• next still takes max_wait. In async code timeouts usually come from the runtime (timeout, select!). Ok(None) means "timed out", not "ended".
• cancel is async and returns Result. Its natural callers (a Ctrl-C handler, a Drop) can't .await. The sync fn cancel(&self) is the better shape.
• events() is async fn returning Events<'_>: is that a Stream, or does it have its own next().await?
• &self everywhere allows concurrent next callers. The C ABI supports that, but a single consumer (&mut self) plus a cloneable canceller is simpler.

Proposal: https://gist.github.com/cablehead/7c0078019081652047aec648497bf1d0