Struct yrs::TransactionMut

pub struct TransactionMut<'doc> { /* private fields */ }

Read-write transaction. It can be used to modify an underlying state of the corresponding Doc. Read-write transactions require an exclusive access to document store - only one such transaction can be present per Doc at the same time (read-only Transactions are not allowed to coexists at the same time as well).

This transaction type stores the information about all of the changes performed in its scope. These will be used during TransactionMut::commit call to optimize metadata of incoming updates, triggering necessary event callbacks etc. For performance reasons it’s preferred to batch as many updates as possible using the same transaction.

In Yrs transactions are always auto-committing all of their changes when dropped. Rollbacks are not supported (if some operations needs to be undone, this can be achieved using UndoManager)

Implementations

impl<'doc> TransactionMut<'doc>

pub fn doc(&self) -> &Doc

pub fn before_state(&self) -> &StateVector

Corresponding document’s state vector at the moment when current transaction was created.

pub fn after_state(&self) -> &StateVector

State vector of the transaction after [Transaction::commit] has been called.

pub fn delete_set(&self) -> &DeleteSet

Data about deletions performed in the scope of current transaction.

pub fn origin(&self) -> Option<&Origin>

Returns origin of the transaction if any was defined. Read-write transactions can get an origin assigned via Transact::try_transact_mut_with/Transact::transact_mut_with methods.

pub fn changed_parent_types(&self) -> &[BranchPtr]

Returns a list of root level types changed in a scope of the current transaction. This list is not filled right away, but as a part of TransactionMut::commit process.

pub fn encode_update_v1(&self) -> Vec<u8>

Encodes changes made within the scope of the current transaction using lib0 v1 encoding.

Document updates are idempotent and commutative. Caveats:

• It doesn’t matter in which order document updates are applied.
• As long as all clients receive the same document updates, all clients end up with the same content.
• Even if an update contains known information, the unknown information is extracted and integrated into the document structure.

pub fn encode_update_v2(&self) -> Vec<u8>

Encodes changes made within the scope of the current transaction using lib0 v2 encoding.

Document updates are idempotent and commutative. Caveats:

• It doesn’t matter in which order document updates are applied.
• As long as all clients receive the same document updates, all clients end up with the same content.
• Even if an update contains known information, the unknown information is extracted and integrated into the document structure.

pub fn encode_update<E: Encoder>(&self, encoder: &mut E)

Encodes changes made within the scope of the current transaction.

Document updates are idempotent and commutative. Caveats:

• It doesn’t matter in which order document updates are applied.
• As long as all clients receive the same document updates, all clients end up with the same content.
• Even if an update contains known information, the unknown information is extracted and integrated into the document structure.

pub fn apply_update(&mut self, update: Update)

Applies a deserialized Update contents into a document owning current transaction. Update payload can be generated by methods such as TransactionMut::encode_diff or passed to Doc::observe_update_v1/Doc::observe_update_v2 callbacks. Updates are allowed to contain duplicate blocks (already presen in current document store) - these will be ignored.

Pending updates

Remote update integration requires that all to-be-integrated blocks must have their direct predecessors already in place. Out of order updates from the same peer will be stashed internally and their integration will be postponed until missing blocks arrive first.

pub fn commit(&mut self)

Commits current transaction. This step involves cleaning up and optimizing changes performed during lifetime of a transaction. Such changes include squashing delete sets data, squashing blocks that have been appended one after another to preserve memory and triggering events.

This step is performed automatically when a transaction is about to be dropped (its life scope comes to an end).

Trait Implementations

impl<'doc> Drop for TransactionMut<'doc>

fn drop(&mut self)

Executes the destructor for this type.

impl<'doc> ReadTxn for TransactionMut<'doc>

fn store(&self) -> &Store

fn state_vector(&self) -> StateVector

Returns state vector describing current state of the updates.

fn snapshot(&self) -> Snapshot

Returns a snapshot which describes a current state of updates and removals made within the corresponding document.

fn encode_state_from_snapshot<E: Encoder>( &self, snapshot: &Snapshot, encoder: &mut E ) -> Result<(), Error>

Encodes all changes from current transaction block store up to a given snapshot. This enables to encode state of a document at some specific point in the past.

fn encode_diff<E: Encoder>(&self, state_vector: &StateVector, encoder: &mut E)

Encodes the difference between remove peer state given its state_vector and the state of a current local peer

fn encode_diff_v1(&self, state_vector: &StateVector) -> Vec<u8>

fn encode_diff_v2(&self, state_vector: &StateVector) -> Vec<u8>

fn encode_state_as_update<E: Encoder>(&self, sv: &StateVector, encoder: &mut E)

fn encode_state_as_update_v1(&self, sv: &StateVector) -> Vec<u8>

fn encode_state_as_update_v2(&self, sv: &StateVector) -> Vec<u8>

fn is_alive<B>(&self, node: &B) -> bool

where B: SharedRef,

Check if given node is alive. Returns false if node has been deleted.

fn root_refs(&self) -> RootRefs<'_>

Returns an iterator over top level (root) shared types available in current Doc.

fn subdoc_guids(&self) -> SubdocGuids<'_>

Returns a collection of globally unique identifiers of sub documents linked within the structures of this document store.

fn subdocs(&self) -> SubdocsIter<'_>

Returns a collection of sub documents linked within the structures of this document store.

fn get_text<N: Into<Arc<str>>>(&self, name: N) -> Option<TextRef>

Returns a TextRef data structure stored under a given name. Text structures are used for collaborative text editing: they expose operations to append and remove chunks of text, which are free to execute concurrently by multiple peers over remote boundaries.

fn get_array<N: Into<Arc<str>>>(&self, name: N) -> Option<ArrayRef>

Returns an ArrayRef data structure stored under a given name. Array structures are used for storing a sequences of elements in ordered manner, positioning given element accordingly to its index.

fn get_map<N: Into<Arc<str>>>(&self, name: N) -> Option<MapRef>

Returns a MapRef data structure stored under a given name. Maps are used to store key-value pairs associated. These values can be primitive data (similar but not limited to a JavaScript Object Notation) as well as other shared types (Yrs maps, arrays, text structures etc.), enabling to construct a complex recursive tree structures.

fn get_xml_fragment<N: Into<Arc<str>>>(&self, name: N) -> Option<XmlFragmentRef>

Returns a XmlFragmentRef data structure stored under a given name. XML elements represent nodes of XML document. They can contain attributes (key-value pairs, both of string type) and other nested XML elements or text values, which are stored in their insertion order.

impl<'doc> WriteTxn for TransactionMut<'doc>

fn store_mut(&mut self) -> &mut Store

fn subdocs_mut(&mut self) -> &mut Subdocs

fn get_or_insert_text<N: Into<Arc<str>>>(&mut self, name: N) -> TextRef

Returns a TextRef data structure stored under a given name. Text structures are used for collaborative text editing: they expose operations to append and remove chunks of text, which are free to execute concurrently by multiple peers over remote boundaries.

fn get_or_insert_map<N: Into<Arc<str>>>(&mut self, name: N) -> MapRef

Returns a MapRef data structure stored under a given name. Maps are used to store key-value pairs associated. These values can be primitive data (similar but not limited to a JavaScript Object Notation) as well as other shared types (Yrs maps, arrays, text structures etc.), enabling to construct a complex recursive tree structures.

fn get_or_insert_array<N: Into<Arc<str>>>(&mut self, name: N) -> ArrayRef

Returns an ArrayRef data structure stored under a given name. Array structures are used for storing a sequences of elements in ordered manner, positioning given element accordingly to its index.

fn get_or_insert_xml_fragment<N: Into<Arc<str>>>( &mut self, name: N ) -> XmlFragmentRef

Returns a XmlFragmentRef data structure stored under a given name. XML elements represent nodes of XML document. They can contain attributes (key-value pairs, both of string type) as well as other nested XML elements or text values, which are stored in their insertion order.