Struct Awareness 

pub struct Awareness { /* private fields */ }

The Awareness class implements a simple shared state protocol that can be used for non-persistent data like awareness information (cursor, username, status, ..). Each client can update its own local state and listen to state changes of remote clients.

Each client is identified by a unique client id (something we borrow from doc.clientID). A client can override its own state by propagating a message with an increasing timestamp (clock). If such a message is received, it is applied if the known state of that client is older than the new state (clock < new_clock). If a client thinks that a remote client is offline, it may propagate a message with { clock, state: null, client }. If such a message is received, and the known clock of that client equals the received clock, it will clean the state.

Before a client disconnects, it should propagate a null state with an updated clock.

Implementations

impl Awareness

pub fn new(doc: Doc) -> Awareness

Creates a new instance of Awareness struct, which operates over a given document. Awareness instance has full ownership of that document. If necessary it can be accessed using either Awareness::doc or Awareness::doc_mut methods.

pub fn with_clock<C>(doc: Doc, clock: C) -> Awareness

where C: Clock + 'static,

Creates a new instance of Awareness struct, which operates over a given document. Awareness instance has full ownership of that document. If necessary it can be accessed using either Awareness::doc or Awareness::doc_mut methods.

pub fn on_update<F>(&self, f: F) -> Arc<dyn Drop>

where F: Fn(&Awareness, &Event, Option<&Origin>) + 'static,

Returns a channel receiver for an incoming awareness events. This channel can be cloned.

pub fn on_update_with<K, F>(&self, key: K, f: F)

where K: Into<Origin>, F: Fn(&Awareness, &Event, Option<&Origin>) + 'static,

Returns a channel receiver for an incoming awareness events. This channel can be cloned.

pub fn unobserve_update<K>(&self, key: K) -> bool

where K: Into<Origin>,

Returns a channel receiver for an incoming awareness events. This channel can be cloned.

pub fn on_change<F>(&self, f: F) -> Arc<dyn Drop>

where F: Fn(&Awareness, &Event, Option<&Origin>) + 'static,

Returns a channel receiver for an incoming awareness events. This channel can be cloned.

pub fn on_change_with<K, F>(&self, key: K, f: F)

where K: Into<Origin>, F: Fn(&Awareness, &Event, Option<&Origin>) + 'static,

Returns a channel receiver for an incoming awareness events. This channel can be cloned.

pub fn unobserve_change<K>(&self, key: K) -> bool

where K: Into<Origin>,

Returns a channel receiver for an incoming awareness events. This channel can be cloned.

pub fn doc(&self) -> &Doc

Returns a read-only reference to an underlying Doc.

pub fn doc_mut(&mut self) -> &mut Doc

Returns a read-write reference to an underlying Doc.

pub fn client_id(&self) -> u64

Returns a globally unique client ID of an underlying Doc.

pub fn iter(&self) -> AwarenessIter<'_>

Returns a state map of all the clients tracked by current Awareness instance. Those states are identified by their corresponding ClientIDs. The associated state is represented and replicated to other clients as a JSON string.

pub fn local_state<S>(&self) -> Option<S>

where S: DeserializeOwned,

Returns a JSON string state representation of a current Awareness instance.

pub fn local_state_raw(&self) -> Option<Arc<str>>

Returns a JSON string state representation of a current Awareness instance.

pub fn remove_state(&self, client_id: u64)

Clears out a state of a given client, effectively marking it as disconnected.

pub fn state<D>(&self, client_id: u64) -> Option<D>

where D: DeserializeOwned,

Gets the state of a particular client.

pub fn meta(&self, client_id: u64) -> Option<(u32, u64)>

Get the (sequence number, last updated timestamp) metadata associated with particular client.

pub fn clean_local_state(&self)

Clears out a state of a current client (see: Awareness::client_id), effectively marking it as disconnected.

pub fn set_local_state<S>(&self, state: S) -> Result<(), Error>

where S: Serialize,

Sets a current Awareness instance state to a corresponding JSON string. This state will be replicated to other clients as part of the AwarenessUpdate and it will trigger an event to be emitted if current instance was created using [Awareness::with_observer] method.

pub fn set_local_state_raw<S>(&self, json: S)

where S: Into<Arc<str>>,

Sets a current Awareness instance state to a corresponding JSON string. This state will be replicated to other clients as part of the AwarenessUpdate and it will trigger an event to be emitted if current instance was created using [Awareness::with_observer] method.

pub fn update(&self) -> Result<AwarenessUpdate, Error>

Returns a serializable update object which is representation of a current Awareness state. This doesn’t include states that have been removed in the past.

pub fn update_with_clients<I>( &self, clients: I, ) -> Result<AwarenessUpdate, Error>

where I: IntoIterator<Item = u64>,

Returns a serializable update object which is representation of a current Awareness state. Unlike Awareness::update, this method variant allows to prepare update only for a subset of known clients. These clients must all be known to a current Awareness instance, otherwise a Error::ClientNotFound error will be returned.

pub fn apply_update(&self, update: AwarenessUpdate) -> Result<(), Error>

Applies an update (incoming from remote channel or generated using Awareness::update / Awareness::update_with_clients methods) and modifies a state of a current instance.

If current instance has an observer channel (see: [Awareness::with_observer]), applied changes will also be emitted as events.

pub fn apply_update_with<O>( &self, update: AwarenessUpdate, origin: O, ) -> Result<(), Error>

where O: Into<Origin>,

Applies an update (incoming from remote channel or generated using Awareness::update / Awareness::update_with_clients methods) and modifies a state of a current instance.

If current instance has an observer channel (see: [Awareness::with_observer]), applied changes will also be emitted as events.

pub fn apply_update_summary( &self, update: AwarenessUpdate, ) -> Result<Option<AwarenessUpdateSummary>, Error>

Applies an update (incoming from remote channel or generated using Awareness::update / Awareness::update_with_clients methods) and modifies a state of a current instance. Returns an AwarenessUpdateSummary object informing about the changes that were applied.

If current instance has an observer channel (see: [Awareness::with_observer]), applied changes will also be emitted as events.

pub fn apply_update_summary_with<O>( &self, update: AwarenessUpdate, origin: O, ) -> Result<Option<AwarenessUpdateSummary>, Error>

where O: Into<Origin>,

Applies an update (incoming from remote channel or generated using Awareness::update / Awareness::update_with_clients methods) and modifies a state of a current instance. Returns an AwarenessUpdateSummary object informing about the changes that were applied.

If current instance has an observer channel (see: [Awareness::with_observer]), applied changes will also be emitted as events.

Trait Implementations

impl Debug for Awareness

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

Formats the value using the given formatter.

impl Default for Awareness

Available on not (target_family=wasm and target_os=unknown).

fn default() -> Awareness

Returns the “default value” for a type.