A RecoveryUnit is responsible for ensuring that data is persisted. More...

#include <recovery_unit.h>

Inheritance diagram for mongo::RecoveryUnit:

Detailed Description

A RecoveryUnit is responsible for ensuring that data is persisted.

All on-disk information must be mutated through this interface.

Classes
class	Change
	A Change is an action that is registerChange()'d while a WriteUnitOfWork exists. More...

Public Types
enum	ReadSource { kNone, kMajorityCommitted, kLastApplied, kLastAppliedSnapshot, kProvided }
	The ReadSource indicates which exteral or provided timestamp to read from for future transactions. More...

Public Member Functions
virtual	~RecoveryUnit ()

virtual void	beginUnitOfWork (OperationContext *opCtx)=0
	Marks the beginning of a unit of work. More...

virtual void	commitUnitOfWork ()=0
	Marks the end of a unit of work and commits all changes registered by calls to onCommit or registerChange, in order. More...

virtual void	abortUnitOfWork ()=0
	Marks the end of a unit of work and rolls back all changes registered by calls to onRollback or registerChange, in reverse order. More...

virtual void	prepareUnitOfWork ()
	Transitions the active unit of work to the "prepared" state. More...

virtual void	setIgnorePrepared (bool ignore)
	Sets whether or not to ignore prepared transactions if supported by this storage engine. More...

virtual bool	waitUntilDurable ()=0
	Waits until all commits that happened before this call are durable in the journal. More...

virtual bool	waitUntilUnjournaledWritesDurable ()
	Unlike `waitUntilDurable`, this method takes a stable checkpoint, making durable any writes on unjournaled tables that are behind the current stable timestamp. More...

virtual void	abandonSnapshot ()=0
	If there is an open transaction, it is closed. More...

virtual void	preallocateSnapshot ()
	Informs the RecoveryUnit that a snapshot will be needed soon, if one was not already established. More...

virtual Status	obtainMajorityCommittedSnapshot ()
	Obtains a majority committed snapshot. More...

virtual boost::optional< Timestamp >	getPointInTimeReadTimestamp () const
	Returns the Timestamp being used by this recovery unit or boost::none if not reading from a point in time. More...

virtual SnapshotId	getSnapshotId () const =0
	Gets the local SnapshotId. More...

virtual Status	setTimestamp (Timestamp timestamp)
	Sets a timestamp to assign to future writes in a transaction. More...

virtual void	setCommitTimestamp (Timestamp timestamp)
	Sets a timestamp that will be assigned to all future writes on this RecoveryUnit until clearCommitTimestamp() is called. More...

virtual void	clearCommitTimestamp ()

virtual Timestamp	getCommitTimestamp ()

virtual void	setPrepareTimestamp (Timestamp timestamp)
	Sets a prepare timestamp for the current transaction. More...

virtual void	setTimestampReadSource (ReadSource source, boost::optional< Timestamp > provided=boost::none)
	Sets which timestamp to use for read transactions. More...

virtual ReadSource	getTimestampReadSource () const

virtual void	registerChange (Change *change)=0
	The RecoveryUnit takes ownership of the change. More...

template<typename Callback >
void	onRollback (Callback callback)
	Registers a callback to be called if the current WriteUnitOfWork rolls back. More...

template<typename Callback >
void	onCommit (Callback callback)
	Registers a callback to be called if the current WriteUnitOfWork commits. More...

virtual void *	writingPtr (void *data, size_t len)=0
	Declare that the data at [x, x + len) is being written. More...

int &	writingInt (int &d)
	Declare write intent for an int. More...

template<typename T >
T *	writing (T *x)
	A templated helper for writingPtr. More...

virtual void	setRollbackWritesDisabled ()=0
	Sets a flag that declares this RecoveryUnit will skip rolling back writes, for the duration of the current outermost WriteUnitOfWork. More...

virtual void	setOrderedCommit (bool orderedCommit)=0

Protected Member Functions
	RecoveryUnit ()

Private Member Functions
	MONGO_DISALLOW_COPYING (RecoveryUnit)

Member Enumeration Documentation

◆ ReadSource

enum mongo::RecoveryUnit::ReadSource

The ReadSource indicates which exteral or provided timestamp to read from for future transactions.

Enumerator
kNone	Do not read from a timestamp. This is the default.
kMajorityCommitted	Read from the majority all-commmitted timestamp.
kLastApplied	Read from the last applied timestamp. New transactions start at the most up-to-date timestamp.
kLastAppliedSnapshot	Read from the last applied timestamp. New transactions will always read from the same timestamp and never advance.
kProvided	Read from the timestamp provided to setTimestampReadSource.

Constructor & Destructor Documentation

◆ ~RecoveryUnit()

virtual mongo::RecoveryUnit::~RecoveryUnit ( )

inlinevirtual

◆ RecoveryUnit()

mongo::RecoveryUnit::RecoveryUnit ( )

inlineprotected

Member Function Documentation

◆ abandonSnapshot()

virtual void mongo::RecoveryUnit::abandonSnapshot ( )

pure virtual

If there is an open transaction, it is closed.

On return no transaction is active. This cannot be called inside of a WriteUnitOfWork, and should fail if it is.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::RecoveryUnitNoop, mongo::MobileRecoveryUnit, mongo::EphemeralForTestRecoveryUnit, and mongo::DurRecoveryUnit.

◆ abortUnitOfWork()

virtual void mongo::RecoveryUnit::abortUnitOfWork ( )

pure virtual

Marks the end of a unit of work and rolls back all changes registered by calls to onRollback or registerChange, in reverse order.

Must be matched by exactly one preceding call to beginUnitOfWork.

Should be called through WriteUnitOfWork rather than directly.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::MobileRecoveryUnit, mongo::RecoveryUnitNoop, mongo::DurRecoveryUnit, and mongo::EphemeralForTestRecoveryUnit.

◆ beginUnitOfWork()

virtual void mongo::RecoveryUnit::beginUnitOfWork ( OperationContext * opCtx )

pure virtual

Marks the beginning of a unit of work.

Each call must be matched with exactly one call to either commitUnitOfWork or abortUnitOfWork.

Should be called through WriteUnitOfWork rather than directly.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::MobileRecoveryUnit, mongo::DurRecoveryUnit, mongo::EphemeralForTestRecoveryUnit, and mongo::RecoveryUnitNoop.

◆ clearCommitTimestamp()

virtual void mongo::RecoveryUnit::clearCommitTimestamp ( )

inlinevirtual

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ commitUnitOfWork()

virtual void mongo::RecoveryUnit::commitUnitOfWork ( )

pure virtual

Marks the end of a unit of work and commits all changes registered by calls to onCommit or registerChange, in order.

Must be matched by exactly one preceding call to beginUnitOfWork.

Should be called through WriteUnitOfWork rather than directly.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::MobileRecoveryUnit, mongo::DurRecoveryUnit, mongo::EphemeralForTestRecoveryUnit, and mongo::RecoveryUnitNoop.

◆ getCommitTimestamp()

virtual Timestamp mongo::RecoveryUnit::getCommitTimestamp ( )

inlinevirtual

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ getPointInTimeReadTimestamp()

virtual boost::optional<Timestamp> mongo::RecoveryUnit::getPointInTimeReadTimestamp ( ) const

inlinevirtual

Returns the Timestamp being used by this recovery unit or boost::none if not reading from a point in time.

Any point in time returned will reflect one of the following:

when using ReadSource::kProvided, the timestamp provided.
when using ReadSource::kLastAppliedSnapshot, the timestamp chosen using the storage engine's last applied timestamp.
when using ReadSource::kLastApplied, the last applied timestamp at which the current storage transaction was opened, if one is open.
when using ReadSource::kMajorityCommitted, the majority committed timestamp chosen by the storage engine after a transaction has been opened or after a call to obtainMajorityCommittedSnapshot().

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ getSnapshotId()

virtual SnapshotId mongo::RecoveryUnit::getSnapshotId ( ) const

pure virtual

Gets the local SnapshotId.

It is only valid to compare SnapshotIds generated by a single RecoveryUnit.

This is unrelated to Timestamp which must be globally comparable.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::RecoveryUnitNoop, mongo::EphemeralForTestRecoveryUnit, mongo::MobileRecoveryUnit, and mongo::DurRecoveryUnit.

◆ getTimestampReadSource()

virtual ReadSource mongo::RecoveryUnit::getTimestampReadSource ( ) const

inlinevirtual

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ MONGO_DISALLOW_COPYING()

mongo::RecoveryUnit::MONGO_DISALLOW_COPYING ( RecoveryUnit )

private

◆ obtainMajorityCommittedSnapshot()

virtual Status mongo::RecoveryUnit::obtainMajorityCommittedSnapshot ( )

inlinevirtual

Obtains a majority committed snapshot.

Snapshots should still be separately acquired and newer committed snapshots should be used if available whenever implementations would normally change snapshots.

If no snapshot has yet been marked as Majority Committed, returns a status with error code ReadConcernMajorityNotAvailableYet. After this returns successfully, at any point where implementations attempt to acquire committed snapshot, if there are none available due to a call to SnapshotManager::dropAllSnapshots(), a AssertionException with the same code should be thrown.

StorageEngines that don't support a SnapshotManager should use the default implementation.

Reimplemented in mongo::WiredTigerRecoveryUnit, and mongo::EphemeralForTestRecoveryUnit.

◆ onCommit()

template<typename Callback >

void mongo::RecoveryUnit::onCommit ( Callback callback )

inline

Registers a callback to be called if the current WriteUnitOfWork commits.

Be careful about the lifetimes of all variables captured by the callback!

◆ onRollback()

template<typename Callback >

void mongo::RecoveryUnit::onRollback ( Callback callback )

inline

Registers a callback to be called if the current WriteUnitOfWork rolls back.

Be careful about the lifetimes of all variables captured by the callback!

◆ preallocateSnapshot()

virtual void mongo::RecoveryUnit::preallocateSnapshot ( )

inlinevirtual

Informs the RecoveryUnit that a snapshot will be needed soon, if one was not already established.

This specifically allows the storage engine to preallocate any required transaction resources while minimizing the critical section between generating a new timestamp and setting it using setTimestamp.

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ prepareUnitOfWork()

virtual void mongo::RecoveryUnit::prepareUnitOfWork ( )

inlinevirtual

Transitions the active unit of work to the "prepared" state.

Must be called after beginUnitOfWork and before calling either abortUnitOfWork or commitUnitOfWork. Must be overridden by storage engines that support prepared transactions.

Must be preceded by a call to beginUnitOfWork and setPrepareTimestamp, in that order.

This cannot be called after setTimestamp or setCommitTimestamp.

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ registerChange()

virtual void mongo::RecoveryUnit::registerChange ( Change * change )

pure virtual

The RecoveryUnit takes ownership of the change.

The commitUnitOfWork() method calls the commit() method of each registered change in order of registration. The endUnitOfWork() method calls the rollback() method of each registered Change in reverse order of registration. Either will unregister and delete the changes.

The registerChange() method may only be called when a WriteUnitOfWork is active, and may not be called during commit or rollback.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::RecoveryUnitNoop, mongo::EphemeralForTestRecoveryUnit, mongo::MobileRecoveryUnit, and mongo::DurRecoveryUnit.

◆ setCommitTimestamp()

virtual void mongo::RecoveryUnit::setCommitTimestamp ( Timestamp timestamp )

inlinevirtual

Sets a timestamp that will be assigned to all future writes on this RecoveryUnit until clearCommitTimestamp() is called.

This must be called outside of a WUOW and setTimestamp() must not be called while a commit timestamp is set.

Parameters

[in] timestamp Timestamp to assign to future writes in a transaction

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ setIgnorePrepared()

virtual void mongo::RecoveryUnit::setIgnorePrepared ( bool ignore )

inlinevirtual

Sets whether or not to ignore prepared transactions if supported by this storage engine.

When 'ignore' is true, allows reading data in prepared, but uncommitted transactions.

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ setOrderedCommit()

virtual void mongo::RecoveryUnit::setOrderedCommit ( bool orderedCommit )

pure virtual

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::MobileRecoveryUnit, mongo::RecoveryUnitNoop, mongo::EphemeralForTestRecoveryUnit, and mongo::DurRecoveryUnit.

◆ setPrepareTimestamp()

virtual void mongo::RecoveryUnit::setPrepareTimestamp ( Timestamp timestamp )

inlinevirtual

Sets a prepare timestamp for the current transaction.

A subsequent call to prepareUnitOfWork() is expected and required. This cannot be called after setTimestamp or setCommitTimestamp. This must be called inside a WUOW and may only be called once.

Parameters

[in] timestamp Timestamp to use when calling prepareUnitOfWork

Reimplemented in mongo::WiredTigerRecoveryUnit, and mongo::EphemeralForTestRecoveryUnit.

◆ setRollbackWritesDisabled()

virtual void mongo::RecoveryUnit::setRollbackWritesDisabled ( )

pure virtual

Sets a flag that declares this RecoveryUnit will skip rolling back writes, for the duration of the current outermost WriteUnitOfWork.

This function can only be called between a pair of unnested beginUnitOfWork() / endUnitOfWork() calls. The flag is cleared when endUnitOfWork() is called. While the flag is set, rollback will skip rolling back writes, but custom rollback change functions are still called. Clearly, this functionality should only be used when writing to temporary collections that can be cleaned up externally. For example, foreground index builds write to a temporary collection; if something goes wrong that normally requires a rollback, we can instead clean up the index by dropping the entire index. Setting the flag may permit increased performance.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::RecoveryUnitNoop, mongo::EphemeralForTestRecoveryUnit, mongo::MobileRecoveryUnit, and mongo::DurRecoveryUnit.

◆ setTimestamp()

virtual Status mongo::RecoveryUnit::setTimestamp ( Timestamp timestamp )

inlinevirtual

Sets a timestamp to assign to future writes in a transaction.

All subsequent writes will be assigned this timestamp. If setTimestamp() is called again, specifying a new timestamp, future writes will use this new timestamp but past writes remain with their originally assigned timestamps. Writes that occur before any setTimestamp() is called will be assigned the timestamp specified in the last setTimestamp() call in the transaction, at commit time.

setTimestamp() will fail if a commit timestamp is set using setCommitTimestamp() and not yet cleared with clearCommitTimestamp().

Parameters

[in] timestamp Timestamp to assign to future writes in a transaction

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ setTimestampReadSource()

virtual void mongo::RecoveryUnit::setTimestampReadSource	(	ReadSource	source,
		boost::optional< Timestamp >	provided = `boost::none`
	)

inlinevirtual

Sets which timestamp to use for read transactions.

If 'provided' is supplied, only kProvided is an acceptable input.

Must be called in one of the following cases:

a transaction is not active
no read source has been set yet
the read source provided is the same as the existing read source

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ waitUntilDurable()

virtual bool mongo::RecoveryUnit::waitUntilDurable ( )

pure virtual

Waits until all commits that happened before this call are durable in the journal.

Returns true, unless the storage engine cannot guarantee durability, which should never happen when isDurable() returned true. This cannot be called from inside a unit of work, and should fail if it is.

Returns: Whether or not the storage engine can guarantee durability.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::RecoveryUnitNoop, mongo::MobileRecoveryUnit, mongo::DurRecoveryUnit, and mongo::EphemeralForTestRecoveryUnit.

◆ waitUntilUnjournaledWritesDurable()

virtual bool mongo::RecoveryUnit::waitUntilUnjournaledWritesDurable ( )

inlinevirtual

Unlike waitUntilDurable, this method takes a stable checkpoint, making durable any writes on unjournaled tables that are behind the current stable timestamp.

If the storage engine is starting from an "unstable" checkpoint, this method call will turn into an unstable checkpoint.

This must not be called by a system taking user writes until after a stable timestamp is passed to the storage engine.

Returns: Whether or not the storage engine can guarantee durability.

Reimplemented in mongo::WiredTigerRecoveryUnit.

◆ writing()

template<typename T >

T* mongo::RecoveryUnit::writing ( T * x )

inline

A templated helper for writingPtr.

◆ writingInt()

int& mongo::RecoveryUnit::writingInt ( int & d )

inline

Declare write intent for an int.

◆ writingPtr()

virtual void* mongo::RecoveryUnit::writingPtr	(	void *	data,
		size_t	len
	)

pure virtual

Declare that the data at [x, x + len) is being written.

Implemented in mongo::HeapRecordStoreBtreeRecoveryUnit, mongo::WiredTigerRecoveryUnit, mongo::RecoveryUnitNoop, mongo::EphemeralForTestRecoveryUnit, mongo::MobileRecoveryUnit, and mongo::DurRecoveryUnit.

The documentation for this class was generated from the following file:

/home/louis/git/mongodbsource.github.io/src/src/mongo/db/storage/recovery_unit.h

Detailed Description

Classes

Public Types

Public Member Functions

Protected Member Functions

Private Member Functions

Member Enumeration Documentation

◆ ReadSource

Constructor & Destructor Documentation

◆ ~RecoveryUnit()

◆ RecoveryUnit()

Member Function Documentation

◆ abandonSnapshot()

◆ abortUnitOfWork()

◆ beginUnitOfWork()

◆ clearCommitTimestamp()

◆ commitUnitOfWork()

◆ getCommitTimestamp()

◆ getPointInTimeReadTimestamp()

◆ getSnapshotId()

◆ getTimestampReadSource()

◆ MONGO_DISALLOW_COPYING()

◆ obtainMajorityCommittedSnapshot()

◆ onCommit()

◆ onRollback()

◆ preallocateSnapshot()

◆ prepareUnitOfWork()

◆ registerChange()

◆ setCommitTimestamp()

◆ setIgnorePrepared()

◆ setOrderedCommit()

◆ setPrepareTimestamp()

◆ setRollbackWritesDisabled()

◆ setTimestamp()

◆ setTimestampReadSource()

◆ waitUntilDurable()

◆ waitUntilUnjournaledWritesDurable()

◆ writing()

◆ writingInt()

◆ writingPtr()