Struct 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 events(&self) -> Option<&StoreEvents>

pub fn events_mut(&mut self) -> &mut StoreEvents

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>(&self, encoder: &mut E)

where E: Encoder,

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) -> Result<(), UpdateError>

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).

pub fn gc(&mut self, delete_set: Option<&DeleteSet>)

Perform garbage collection of deleted blocks, even if a document was created with skip_gc option.

If delete_set is provided, it will be used to limit the scope of garbage collection to only those blocks that are present in the delete set. If delete_set is None, all deleted blocks will be considered for garbage collection.

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>( &self, snapshot: &Snapshot, encoder: &mut E, ) -> Result<(), Error>

where E: Encoder,

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>(&self, state_vector: &StateVector, encoder: &mut E)

where E: Encoder,

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

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

Encodes the difference between remote peer state given its state_vector and the state of a current local peer, using lib0 v1 encoding.

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

Encodes the difference between remote peer state given its state_vector and the state of a current local peer, using lib0 v2 encoding.

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

where E: Encoder,

Encodes the difference between remote peer state given its state_vector and the state of a current local peer. Also includes pending updates which were not yet integrated into the main document state and entire delete set.

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

Encodes the difference between remote peer state given its state_vector and the state of a current local peer, using lib0 v1 encoding. Also includes pending updates which were not yet integrated into the main document state and entire delete set.

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

Encodes the difference between remote peer state given its state_vector and the state of a current local peer, using lib0 v2 encoding. Also includes pending updates which were not yet integrated into the main document state and entire delete set.

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>(&self, name: N) -> Option<TextRef>

where N: Into<Arc<str>>,

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>(&self, name: N) -> Option<ArrayRef>

where N: Into<Arc<str>>,

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>(&self, name: N) -> Option<MapRef>

where N: Into<Arc<str>>,

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>(&self, name: N) -> Option<XmlFragmentRef>

where N: Into<Arc<str>>,

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.

fn get<S>(&self, name: S) -> Option<Out>

where S: AsRef<str>,

fn parent_doc(&self) -> Option<Doc>

If current document has been inserted as a sub-document, returns a reference to a parent document, which contains it.

fn branch_id(&self) -> Option<BranchID>

If current document has been inserted as a sub-document, returns its BranchID.

fn has_missing_updates(&self) -> bool

Returns true if current document has any pending updates that are not yet integrated into the document.

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>(&mut self, name: N) -> TextRef

where N: Into<Arc<str>>,

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>(&mut self, name: N) -> MapRef

where N: Into<Arc<str>>,

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>(&mut self, name: N) -> ArrayRef

where N: Into<Arc<str>>,

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>(&mut self, name: N) -> XmlFragmentRef

where N: Into<Arc<str>>,

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.

fn prune_pending(&mut self) -> Option<Update>

Prunes a pending updates from the current document and returns them. Returns None if current document didn’t have any pending updates.