Fabric Wiki

User Tools

Site Tools

Trace: • The Transaction system
tutorial:transfer-api_transactions

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
tutorial:transfer-api_transactions [2023/07/19 13:47] – technici4ntutorial:transfer-api_transactions [2023/07/19 14:00] (current) – [Nested transactions] technici4n
Line 98: Line 98:
  
 Here is how transactions can be visualized: Here is how transactions can be visualized:
-- Opening a new transaction creates a new copy of the state. From now on, that copy is modified. +  * Opening a new transaction creates a new copy of the state. From now on, that copy is modified. 
-- Aborting a transaction discards that copy. Back to the original state. +  * Aborting a transaction discards that copy. Back to the original state. 
-- Committing a transaction replaces the original state by the modified copy. From now on, this is the new state.+  * Committing a transaction replaces the original state by the modified copy. From now on, this is the new state.
  
 We can represent this in a graph with branches: We can represent this in a graph with branches:
-- Any modification operates on the top branch. +  * Any modification operates on the top branch. 
-- Opening a new transaction creates a new branch. +  * Opening a new transaction creates a new branch. 
-- Aborting a transaction discards the top branch. +  * Aborting a transaction discards the top branch. 
-- Committing a transaction merges the top branch into the branch below it.+  * Committing a transaction merges the top branch into the branch below it.
  
 Here is the branching graph for that first example: Here is the branching graph for that first example:
  
-{{https://i.imgur.com/qW0ROX3.png}}+{{:tutorial:transaction_graph_1.png?nolink&400|}}
  
 ==== Nested transactions ==== ==== Nested transactions ====
Line 152: Line 152:
 Here is the corresponding graph: Here is the corresponding graph:
  
-{{https://i.imgur.com/n4jZ9FH.png}}+{{:tutorial:transaction_graph_2.png?nolink|}}
  
 === Transaction vs TransactionContext === === Transaction vs TransactionContext ===
  
 You might have noticed that sometimes we use ''Transaction'' and sometimes we use ''TransactionContext''. The former has some additional functions that are only relevant to the code that opened the transaction. The rule of thumb is: You might have noticed that sometimes we use ''Transaction'' and sometimes we use ''TransactionContext''. The former has some additional functions that are only relevant to the code that opened the transaction. The rule of thumb is:
-- Use ''Transaction'' in code that opens and closes transactions. +  * Use ''Transaction'' in code that opens and closes transactions. 
-- Use ''TransactionContext'' in code that implements transaction-aware operations.+  * Use ''TransactionContext'' in code that implements transaction-aware operations.
  
 ==== Implementing support for transactions ==== ==== Implementing support for transactions ====
Line 165: Line 165:
  
 A ''SnapshotParticipant'' saves copies of its internal state and restores them when required. These copies are referred to as “snapshots”, hence the name. Using a ''SnapshotParticipant'' is generally quite simple: A ''SnapshotParticipant'' saves copies of its internal state and restores them when required. These copies are referred to as “snapshots”, hence the name. Using a ''SnapshotParticipant'' is generally quite simple:
-1. Choose a data type to represent copies of internal state. Usually this will be a record. Here we will use ''Integer''. +  - Choose a data type to represent copies of internal state. Usually this will be a record. Here we will use ''Integer''. 
-2. Extend ''SnapshotParticipant<internal state>''. Here we will add ''extends SnapshotParticipant<Integer>'' to our class. +  - Extend ''SnapshotParticipant<internal state>''. Here we will add ''extends SnapshotParticipant<Integer>'' to our class. 
-3. Implement functions to create copies of the internal state, and restore copies thereof - respectively ''createSnapshot'' and ''readSnapshot''. +  - Implement functions to create copies of the internal state, and restore copies thereof - respectively ''createSnapshot'' and ''readSnapshot''. 
-4. Call ''updateSnapshots(transaction)'' before any change to the internal state.+  - Call ''updateSnapshots(transaction)'' before any change to the internal state.
  
 Let’s start with the following template: Let’s start with the following template:
Line 245: Line 245:
  
 Now that we have been through this background knowledge, here is how the ''SnapshotParticipant'' operates: Now that we have been through this background knowledge, here is how the ''SnapshotParticipant'' operates:
-- When ''updateSnapshots'' is called: +  * When ''updateSnapshots'' is called: 
-  - If we already have a snapshot for this transaction, do nothing. +    * If we already have a snapshot for this transaction, do nothing. 
-  - Otherwise call ''createSnapshot'' to save a snapshot, and add a close callback. +    * Otherwise call ''createSnapshot'' to save a snapshot, and add a close callback. 
-- When a transaction is aborted: +  * When a transaction is aborted: 
-  - We are guaranteed to have a snapshot for that transaction due to how state is managed. +    * We are guaranteed to have a snapshot for that transaction due to how state is managed. 
-  - Call ''readSnapshot'' to revert the state changes. +    * Call ''readSnapshot'' to revert the state changes. 
-- When a transaction is committed: +  * When a transaction is committed: 
-  - If this is an outer (= not nested) transaction, the change is confirmed. +    * If this is an outer (= not nested) transaction, the change is confirmed. 
-    - We know that something probably changed, otherwise we would not have a registered close callback. +      * We know that something probably changed, otherwise we would not have a registered close callback. 
-    - Call ''addOuterCloseCallback''. The callback will call ''onFinalCommit''. +      * Call ''addOuterCloseCallback''. The callback will call ''onFinalCommit''. 
-  - If this is a nested transaction, we need to deal with the snapshot: +    * If this is a nested transaction, we need to deal with the snapshot: 
-    - If the parent transaction already has an older snapshot, discard the more recent snapshot. +      * If the parent transaction already has an older snapshot, discard the more recent snapshot. 
-    - Otherwise the snapshot is moved to the parent transaction.+      * Otherwise the snapshot is moved to the parent transaction.
  
 Hopefully that gives an overview of what is happening under the hood. You should now be ready to read [[https://github.com/FabricMC/fabric/blob/1.20.1/fabric-transfer-api-v1/src/main/java/net/fabricmc/fabric/api/transfer/v1/transaction/base/SnapshotParticipant.java|the source code of SnapshotParticipant]]. Hopefully that gives an overview of what is happening under the hood. You should now be ready to read [[https://github.com/FabricMC/fabric/blob/1.20.1/fabric-transfer-api-v1/src/main/java/net/fabricmc/fabric/api/transfer/v1/transaction/base/SnapshotParticipant.java|the source code of SnapshotParticipant]].
  
tutorial/transfer-api_transactions.1689774426.txt.gz · Last modified: 2023/07/19 13:47 by technici4n