Struct Topic 

pub struct Topic<T> { /* private fields */ }

One topic under one key. Cheap to build; hold none. subscribe and channel are the [TopicHandle]’s; publish is this type’s own, so a topic bound to an @isolation attempt rides it.

Implementations

impl<T> Topic<T>

where T: Serialize + DeserializeOwned + Send + 'static,

pub fn new( backplane: Arc<dyn SubscriptionBackplane>, topic: &str, key: impl Display, ) -> Self

topic is the declared name (RoomMessage), key the key’s value.

pub async fn publish(&self, message: &T) -> Result<(), CratestackError>

Delivers message to every current subscriber, on every replica. From an @isolation procedure’s handle it is delivered only if the attempt commits, never for one that rolls back or retries: with PgNotifyBackplane as Self::publish_in_tx in a savepoint of the attempt, with any other backplane queued and sent after the commit. Inside db.transaction(..) there, use publish_in_tx(tx, ..).

pub async fn publish_in_tx( &self, tx: &mut Transaction<'_, Postgres>, message: &T, ) -> Result<(), CratestackError>

Delivers message only if tx commits, when it commits. On a topic from an @isolation procedure’s handle, a backplane the transaction cannot notify gets it queued until the attempt commits (dropped if this db.transaction(..) rolls back). Otherwise such a backplane (InProcessBackplane) is refused: call Self::publish after the commit instead.

Methods from Deref<Target = TopicHandle<T>>

pub fn channel(&self) -> &str

The backplane channel: cratestack.topic.<Topic>.<key>.

pub fn backplane(&self) -> &Arc<dyn SubscriptionBackplane>

The backplane the topic publishes on.

pub fn encode(&self, message: &T) -> Result<String, CratestackError>

message as the JSON payload the backplane carries.

pub async fn publish(&self, message: &T) -> Result<(), CratestackError>

Delivers message to every current subscriber, on every replica.

pub async fn subscribe( &self, ) -> Result<Pin<Box<dyn Stream<Item = Result<T, CratestackError>> + Send>>, CratestackError>

Every message published from now on. Resolves once the subscription is live. Ends with unavailable when it falls behind ("subscription lagged") or the backplane may have lost messages ("subscription interrupted"): resubscribe and refetch.

Trait Implementations

impl<T> Deref for Topic<T>

type Target = TopicHandle<T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.