pub struct TransactionMut<'doc> { /* private fields */ }Expand description
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§
Source§impl<'doc> TransactionMut<'doc>
impl<'doc> TransactionMut<'doc>
pub fn doc(&self) -> &Doc
pub fn events(&self) -> Option<&StoreEvents>
pub fn events_mut(&mut self) -> &mut StoreEvents
Sourcepub fn before_state(&self) -> &StateVector
pub fn before_state(&self) -> &StateVector
Corresponding document’s state vector at the moment when current transaction was created.
Sourcepub fn after_state(&self) -> &StateVector
pub fn after_state(&self) -> &StateVector
State vector of the transaction after [Transaction::commit] has been called.
Sourcepub fn delete_set(&self) -> &DeleteSet
pub fn delete_set(&self) -> &DeleteSet
Data about deletions performed in the scope of current transaction.
Sourcepub fn origin(&self) -> Option<&Origin>
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.
Sourcepub fn changed_parent_types(&self) -> &[BranchPtr]
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.
Sourcepub fn encode_update_v1(&self) -> Vec<u8> ⓘ
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.
Sourcepub fn encode_update_v2(&self) -> Vec<u8> ⓘ
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.
Sourcepub fn encode_update<E: Encoder>(&self, encoder: &mut E)
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.
Sourcepub fn apply_update(&mut self, update: Update) -> Result<(), UpdateError>
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.
Sourcepub fn commit(&mut self)
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).
Sourcepub fn gc(&mut self, delete_set: Option<&DeleteSet>)
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§
Source§impl<'doc> Drop for TransactionMut<'doc>
impl<'doc> Drop for TransactionMut<'doc>
Source§impl<'doc> ReadTxn for TransactionMut<'doc>
impl<'doc> ReadTxn for TransactionMut<'doc>
fn store(&self) -> &Store
Source§fn state_vector(&self) -> StateVector
fn state_vector(&self) -> StateVector
Source§fn snapshot(&self) -> Snapshot
fn snapshot(&self) -> Snapshot
Source§fn encode_state_from_snapshot<E: Encoder>(
&self,
snapshot: &Snapshot,
encoder: &mut E,
) -> Result<(), Error>
fn encode_state_from_snapshot<E: Encoder>( &self, snapshot: &Snapshot, encoder: &mut E, ) -> Result<(), Error>
snapshot.
This enables to encode state of a document at some specific point in the past.Source§fn encode_diff<E: Encoder>(&self, state_vector: &StateVector, encoder: &mut E)
fn encode_diff<E: Encoder>(&self, state_vector: &StateVector, encoder: &mut E)
state_vector and the state
of a current local peer. Read moreSource§fn encode_diff_v1(&self, state_vector: &StateVector) -> Vec<u8> ⓘ
fn encode_diff_v1(&self, state_vector: &StateVector) -> Vec<u8> ⓘ
state_vector and the state
of a current local peer, using lib0 v1 encoding. Read moreSource§fn encode_diff_v2(&self, state_vector: &StateVector) -> Vec<u8> ⓘ
fn encode_diff_v2(&self, state_vector: &StateVector) -> Vec<u8> ⓘ
state_vector and the state
of a current local peer, using lib0 v2 encoding. Read moreSource§fn encode_state_as_update<E: Encoder>(&self, sv: &StateVector, encoder: &mut E)
fn encode_state_as_update<E: Encoder>(&self, sv: &StateVector, encoder: &mut E)
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. Read moreSource§fn encode_state_as_update_v1(&self, sv: &StateVector) -> Vec<u8> ⓘ
fn encode_state_as_update_v1(&self, sv: &StateVector) -> Vec<u8> ⓘ
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. Read moreSource§fn encode_state_as_update_v2(&self, sv: &StateVector) -> Vec<u8> ⓘ
fn encode_state_as_update_v2(&self, sv: &StateVector) -> Vec<u8> ⓘ
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. Read moreSource§fn root_refs(&self) -> RootRefs<'_> ⓘ
fn root_refs(&self) -> RootRefs<'_> ⓘ
Source§fn subdoc_guids(&self) -> SubdocGuids<'_>
fn subdoc_guids(&self) -> SubdocGuids<'_>
Source§fn subdocs(&self) -> SubdocsIter<'_>
fn subdocs(&self) -> SubdocsIter<'_>
Source§fn get_map<N: Into<Arc<str>>>(&self, name: N) -> Option<MapRef>
fn get_map<N: Into<Arc<str>>>(&self, name: N) -> Option<MapRef>
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. Read moreSource§fn get_xml_fragment<N: Into<Arc<str>>>(&self, name: N) -> Option<XmlFragmentRef>
fn get_xml_fragment<N: Into<Arc<str>>>(&self, name: N) -> Option<XmlFragmentRef>
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. Read morefn get<S: AsRef<str>>(&self, name: S) -> Option<Out>
Source§fn parent_doc(&self) -> Option<Doc>
fn parent_doc(&self) -> Option<Doc>
Source§fn branch_id(&self) -> Option<BranchID>
fn branch_id(&self) -> Option<BranchID>
Source§fn has_missing_updates(&self) -> bool
fn has_missing_updates(&self) -> bool
true if current document has any pending updates that are not yet
integrated into the document.Source§impl<'doc> WriteTxn for TransactionMut<'doc>
impl<'doc> WriteTxn for TransactionMut<'doc>
fn store_mut(&mut self) -> &mut Store
fn subdocs_mut(&mut self) -> &mut Subdocs
Source§fn get_or_insert_map<N: Into<Arc<str>>>(&mut self, name: N) -> MapRef
fn get_or_insert_map<N: Into<Arc<str>>>(&mut self, name: N) -> MapRef
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. Read moreSource§fn get_or_insert_xml_fragment<N: Into<Arc<str>>>(
&mut self,
name: N,
) -> XmlFragmentRef
fn get_or_insert_xml_fragment<N: Into<Arc<str>>>( &mut self, name: N, ) -> XmlFragmentRef
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. Read moreSource§fn prune_pending(&mut self) -> Option<Update>
fn prune_pending(&mut self) -> Option<Update>
None if current document didn’t have any pending updates.Auto Trait Implementations§
impl<'doc> Freeze for TransactionMut<'doc>
impl<'doc> !RefUnwindSafe for TransactionMut<'doc>
impl<'doc> !Send for TransactionMut<'doc>
impl<'doc> !Sync for TransactionMut<'doc>
impl<'doc> Unpin for TransactionMut<'doc>
impl<'doc> !UnwindSafe for TransactionMut<'doc>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> JsonPathEval for Twhere
T: ReadTxn,
impl<T> JsonPathEval for Twhere
T: ReadTxn,
Source§fn json_path<'a>(
&'a self,
path: &'a JsonPath<'a>,
) -> <T as JsonPathEval>::Iter<'a>
fn json_path<'a>( &'a self, path: &'a JsonPath<'a>, ) -> <T as JsonPathEval>::Iter<'a>
Evaluate JSON path on the current transaction, starting from current transaction [Doc] as its root.
§Example
use yrs::{any, Array, ArrayPrelim, Doc, In, JsonPath, JsonPathEval, Map, MapPrelim, Out, Transact, WriteTxn};
let doc = Doc::new();
let mut txn = doc.transact_mut();
let users = txn.get_or_insert_array("users");
// populate the document with some data to query
users.insert(&mut txn, 0, MapPrelim::from([
("name".to_string(), In::Any(any!("Alice"))),
("surname".into(), In::Any(any!("Smith"))),
("age".into(), In::Any(any!(25))),
(
"friends".into(),
In::from(ArrayPrelim::from([
any!({ "name": "Bob", "nick": "boreas" }),
any!({ "nick": "crocodile91" }),
])),
),
]));
let query = JsonPath::parse("$.users..friends.*.nick").unwrap();
let values: Vec<Out> = txn.json_path(&query).collect();
assert_eq!(values, vec![Out::Any(any!("boreas")), Out::Any(any!("crocodile91"))]);