Package net.fabricmc.fabric.api.transfer.v1.transaction.base

Class SnapshotParticipant<T>

java.lang.Object

net.fabricmc.fabric.api.transfer.v1.transaction.base.SnapshotParticipant<T>

Type Parameters:

T - The objects that this participant uses to save its state snapshots. Experimental feature, we reserve the right to remove or change it without further notice. The transfer API is a complex addition, and we want to be able to correct possible design mistakes.

All Implemented Interfaces:

TransactionContext.CloseCallback, TransactionContext.OuterCloseCallback

Direct Known Subclasses:

SingleStackStorage, SingleVariantStorage

@Experimental
public abstract class SnapshotParticipant<T>
extends Object
implements TransactionContext.CloseCallback, TransactionContext.OuterCloseCallback

A base participant implementation that modifies itself during transactions, saving snapshots of its state in objects of type T in case it needs to revert to a previous state.

How to use from subclasses

• Call updateSnapshots(net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext) right before the state of your subclass is modified in a transaction.
• Override createSnapshot(): it is called when necessary to create an object representing the state of your subclass.
• Override readSnapshot(T): it is called when necessary to revert to a previous state of your subclass.
• You may optionally override onFinalCommit(): it is called at the of a transaction that modified the state. For example, it could contain a call to markDirty().
• (Advanced!) You may optionally override releaseSnapshot(T): it is called once a snapshot object will not be used, for example you may wish to pool expensive state objects.

More technical explanation

updateSnapshots(net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext) should be called before any modification. This will save the state of this participant using createSnapshot() if no state was already saved for that transaction. When the transaction is aborted and changes need to be rolled back, readSnapshot(T) will be called to signal that the current state should revert to that of the snapshot. The snapshot object is then released, and can be cached for subsequent use, or discarded.

When an outer transaction is committed, readSnapshot(T) will not be called so that the current state of this participant is retained. releaseSnapshot(T) will be called because the snapshot is not necessary anymore, and onFinalCommit() will be called after the transaction is closed.

Constructor Summary

Constructors

Constructor	Description
SnapshotParticipant()

Method Summary

Modifier and Type	Method	Description
void	afterOuterClose(TransactionContext.Result result)	Perform an action after the top-level transaction is closed.
protected abstract T	createSnapshot()	Return a new nonnull object containing the current state of this participant.
void	onClose(TransactionContext transaction, TransactionContext.Result result)	Perform an action when a transaction is closed.
protected void	onFinalCommit()	Called after an outer transaction succeeded, to perform irreversible actions such as markDirty() or neighbor updates.
protected abstract void	readSnapshot(T snapshot)	Roll back to a state previously created by createSnapshot().
protected void	releaseSnapshot(T snapshot)	Signals that the snapshot will not be used anymore, and is safe to cache for next calls to createSnapshot(), or discard entirely.
void	updateSnapshots(TransactionContext transaction)	Update the stored snapshots so that the changes happening as part of the passed transaction can be correctly committed or rolled back.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SnapshotParticipant

public SnapshotParticipant()

Method Details

createSnapshot

protected abstract T createSnapshot()

Return a new nonnull object containing the current state of this participant. null may not be returned, or an exception will be thrown!

readSnapshot

protected abstract void readSnapshot(T snapshot)

Roll back to a state previously created by createSnapshot().

releaseSnapshot

protected void releaseSnapshot(T snapshot)

Signals that the snapshot will not be used anymore, and is safe to cache for next calls to createSnapshot(), or discard entirely.

onFinalCommit

protected void onFinalCommit()

Called after an outer transaction succeeded, to perform irreversible actions such as markDirty() or neighbor updates.

updateSnapshots

public void updateSnapshots(TransactionContext transaction)

Update the stored snapshots so that the changes happening as part of the passed transaction can be correctly committed or rolled back. This function should be called every time the participant is about to change its internal state as part of a transaction.

onClose

public void onClose(TransactionContext transaction,
 TransactionContext.Result result)

Description copied from interface: TransactionContext.CloseCallback

Perform an action when a transaction is closed.

Specified by:

onClose in interface TransactionContext.CloseCallback

Parameters:

transaction - The closed transaction. Only TransactionContext.nestingDepth(), TransactionContext.getOpenTransaction(int) and TransactionContext.addOuterCloseCallback(net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext.OuterCloseCallback) may be called on that transaction. TransactionContext.addCloseCallback(net.fabricmc.fabric.api.transfer.v1.transaction.TransactionContext.CloseCallback) may additionally be called on parent transactions (accessed through TransactionContext.getOpenTransaction(int) for lower nesting depths).

result - The result of this transaction: whether it was committed or aborted.

afterOuterClose

public void afterOuterClose(TransactionContext.Result result)

Description copied from interface: TransactionContext.OuterCloseCallback

Perform an action after the top-level transaction is closed.

Specified by:

afterOuterClose in interface TransactionContext.OuterCloseCallback

Parameters:

result - The result of the top-level transaction.