Skip to content

Commit

Permalink
Rewrite a stale doc comment to reflect that abort_transaction() no lo…
Browse files Browse the repository at this point in the history 
…nger exists
  • Loading branch information
@tgoyne
tgoyne committed Jun 4, 2024
1 parent afe0e0f commit 553d059
Showing 1 changed file with 26 additions and 66 deletions.
92 changes: 26 additions & 66 deletions src/realm/replication.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,70 +112,34 @@ class Replication {
/// \defgroup replication_transactions
//@{

/// From the point of view of the Replication class, a transaction is
/// initiated when, and only when the associated Transaction object calls
/// initiate_transact() and the call is successful. The associated
/// Transaction object must terminate every initiated transaction either by
/// calling finalize_commit() or by calling abort_transact(). It may only
/// call finalize_commit(), however, after calling prepare_commit(), and
/// only when prepare_commit() succeeds. If prepare_commit() fails (i.e.,
/// throws) abort_transact() must still be called.
/// From the point of view of the Replication class, a write transaction
/// has the following steps:
///
/// The associated Transaction object is supposed to terminate a transaction
/// as soon as possible, and is required to terminate it before attempting
/// to initiate a new one.
/// 1. The parent Transaction acquires exclusive write access to the local Realm.
/// 2. initiate_transact() is called and succeeds.
/// 3. Mutations in the Realm occur, each of which is reported to
/// Replication via one of the member functions at the top of the class
/// (`set()` and friends).
/// 4. prepare_commit() is called as the first phase of two-phase commit.
/// This writes the produced replication log to whatever form of persisted
/// storage the specific Replication subclass uses. As this may be the
/// Realm file itself, this must be called while the write transaction is
/// still active. After this function is called, no more modifications
/// which require replication may be performed until the next transaction
/// is initiated. If this step fails (by throwing an exception), the
/// transaction cannot be committed and must be rolled back.
/// 5. The parent Transaction object performs the commit operation on the local Realm.
/// 6. finalize_commit() is called by the Transaction object. With
/// out-of-Realm replication logs this was used to mark the logs written in
/// step 4 as being valid. With modern in-Realm storage it is merely used
/// to clean up temporary state.
///
/// initiate_transact() is called by the associated Transaction object as
/// part of the initiation of a transaction, and at a time where the caller
/// has acquired exclusive write access to the local Realm. The Replication
/// implementation is allowed to perform "precursor transactions" on the
/// local Realm at this time. During the initiated transaction, the
/// associated DB object must inform the Replication object of all
/// modifying operations by calling set_value() and friends.
///
/// FIXME: There is currently no way for implementations to perform
/// precursor transactions, since a regular transaction would cause a dead
/// lock when it tries to acquire a write lock. Consider giving access to
/// special non-locking precursor transactions via an extra argument to this
/// function.
///
/// prepare_commit() serves as the first phase of a two-phase commit. This
/// function is called by the associated Transaction object immediately
/// before the commit operation on the local Realm. The associated
/// Transaction object will then, as the second phase, either call
/// finalize_commit() or abort_transact() depending on whether the commit
/// operation succeeded or not. The Replication implementation is allowed to
/// modify the Realm via the associated Transaction object at this time
/// (important to in-Realm histories).
///
/// initiate_transact() and prepare_commit() are allowed to block the
/// calling thread if, for example, they need to communicate over the
/// network. If a calling thread is blocked in one of these functions, it
/// must be possible to interrupt the blocking operation by having another
/// thread call interrupt(). The contract is as follows: When interrupt() is
/// called, then any execution of initiate_transact() or prepare_commit(),
/// initiated before the interruption, must complete without blocking, or
/// the execution must be aborted by throwing an Interrupted exception. If
/// initiate_transact() or prepare_commit() throws Interrupted, it counts as
/// a failed operation.
///
/// finalize_commit() is called by the associated Transaction object
/// immediately after a successful commit operation on the local Realm. This
/// happens at a time where modification of the Realm is no longer possible
/// via the associated Transaction object. In the case of in-Realm
/// histories, the changes are automatically finalized as part of the commit
/// operation performed by the caller prior to the invocation of
/// finalize_commit(), so in that case, finalize_commit() might not need to
/// do anything.
///
/// abort_transact() is called by the associated Transaction object to
/// terminate a transaction without committing. That is, any transaction
/// that is not terminated by finalize_commit() is terminated by
/// abort_transact(). This could be due to an explicit rollback, or due to a
/// failed commit attempt.
///
/// Note that finalize_commit() and abort_transact() are not allowed to
/// throw.
/// In previous versions every call to initiate_transact() had to be
/// paired with either a call to finalize_commit() or abort_transaction().
/// This is no longer the case, and aborted write transactions are no
/// longer reported to Replication. This means that initiate_transact()
/// must discard any pending state and begin a fresh transaction if it is
/// called twice without an intervening finalize_commit().
///
/// \param current_version The version of the snapshot that the current
/// transaction is based on.
Expand All @@ -184,10 +148,6 @@ class Replication {
/// updated to reflect the currently bound snapshot, such as when
/// _impl::History::update_early_from_top_ref() was called during the
/// transition from a read transaction to the current write transaction.
///
/// \throw Interrupted Thrown by initiate_transact() and prepare_commit() if
/// a blocking operation was interrupted.

void initiate_transact(Group& group, version_type current_version, bool history_updated);
/// \param current_version The version of the snapshot that the current
/// transaction is based on.
Expand Down

0 comments on commit 553d059

Please sign in to comment.