FdbOperationContext

Namespace: FoundationDB.Client · class

Implements: IDisposable

Represents the context of a retry-able transactional function which accepts a read-only or read-write transaction.

Properties

Abort

bool Abort { get; set; }

If set to true, will abort and not commit the transaction. If false, will try to commit the transaction (and retry on failure)

Activity

Activity Activity { get; }

Current Activity, if tracing is enabled

Cancellation

CancellationToken Cancellation { get; }

Cancellation token associated with the operation

Committed

bool Committed { get; }

If true, the transaction has been committed successfully

Database

IFdbDatabase Database { get; }

The database used by the operation

Elapsed

TimeSpan Elapsed { get; }

Time elapsed since the start of the current attempt

This value is reset to zero every time the transaction fails and is retried. Note that this may not represent the actual lifetime of the transaction with the database itself, which starts at the first read operation.

ElapsedTotal

TimeSpan ElapsedTotal { get; }

Time elapsed since the start of the first attempt

Mode

FdbTransactionMode Mode { get; }

Mode of the transaction

PreviousError

FdbError PreviousError { get; }

Error code of the previous attempt

Equal to for the first attempt, or the error code generate by the previous failed attempt.

Retries

int Retries { get; }

Current attempt number (0 for first, 1+ for retries)

Tenant

IFdbTenant Tenant { get; }

The tenant used by the operation, if present

Methods

AddValueCheck

void AddValueCheck<TKey>(string tag, in TKey key, Slice expectedValue)

Add a check on the value of the key, that will be resolved before the transaction is able to commit

tag — Application-provided tag that can be used later to decide which layer failed the check.
key — Key to check
expectedValue — Expected value of the key. A value of Nil means the key is expected to NOT exist.

If key does not have the expected value, the transaction will fail to commit, with an error (simulating a conflict), which should trigger a retry, and a call to () will return for the next iteration of the retry-loop. Any change to the value of the key after this call, in the same transaction, will not be seen by this check. Only the value seen by this transaction at call time is considered.

void AddValueCheck<TKey, TValue>(string tag, in TKey key, in TValue expectedValue)

Add a check on the value of the key, that will be resolved before the transaction is able to commit

tag — Application-provided tag that can be used later to decide which layer failed the check.
key — Key to check
expectedValue — Expected value of the key. A value of Nil means the key is expected to NOT exist.

void AddValueCheck(string tag, Slice key, Slice expectedValue)

Add a check on the value of the key, that will be resolved before the transaction is able to commit

tag — Application-provided tag that can be used later to decide which layer failed the check.
key — Key to check
expectedValue — Expected value of the key. A value of Nil means the key is expected to NOT exist.

AddValueChecks

void AddValueChecks(string tag, IEnumerable<KeyValuePair<Slice, Slice>> items)

Add a check on the values of one or more keys, that will be resolved before the transaction is able to commit

tag — Application-provided tag that can be used later to decide which layer failed the check.
items — List of keys to check, and their expected values. A value of Nil means the corresponding key is expected to NOT exist.

If any of the keys does not have the expected value, the transaction will fail to commit, with an error (simulating a conflict), which should trigger a retry, and a call to () will return for the next iteration of the retry-loop. Any change to the value of these keys after this call, in the same transaction, will not be seen by this check. Only values seen by this transaction at call time are considered.

void AddValueChecks(string tag, KeyValuePair<Slice, Slice>[] items)

Add a check on the values of one or more keys, that will be resolved before the transaction is able to commit

tag — Application-provided tag that can be used later to decide which layer failed the check.
items — List of keys to check, and their expected values. A value of Nil means the corresponding key is expected to NOT exist.

void AddValueChecks(string tag, ReadOnlySpan<KeyValuePair<Slice, Slice>> items)

Add a check on the values of one or more keys, that will be resolved before the transaction is able to commit

tag — Application-provided tag that can be used later to decide which layer failed the check.
items — List of keys to check, and their expected values. A value of Nil means the corresponding key is expected to NOT exist.

Dispose

void Dispose()

GetApiVersion

int GetApiVersion()

Return the currently enforced API version for the database attached to this transaction.

GetOrCreateLocalData

TState GetOrCreateLocalData<TState, TToken>(TToken key, TState newState)

Return the corresponding instance attached to the transaction, or use the specified instance no value was found.

key — Value of the key. If there can be only one instance per TState, use a constant such as the string.Empty
newState — Instance that will be used if no value already exists in this transaction.

Returns: Either the existing value, or newState.

TState GetOrCreateLocalData<TState, TToken>(TToken key, Func<TState> factory)

Return the corresponding instance attached to the transaction, or invoke the specified factory if it was not already specified.

key — Value of the key. If there can be only one instance per TState, use a constant such as the string.Empty
factory — Handler called to generate a new TState instance if there is no match.

Returns: Either the existing value, or the value returned by invoking factory.

GetTransactionHandler

IFdbTransactionHandler GetTransactionHandler()

Return the underlying native handler for this transaction

This is only intended for testing or troubleshooting purpose!

GetValueChecksFromPreviousAttempt

List<(string, FdbValueCheckResult, Slice, Slice, Slice)> GetValueChecksFromPreviousAttempt(string tag = null, FdbValueCheckResult? result = null)

Return the list of all value-checks performed in the previous transaction attempt

tag — If not-null, only return the checks with the specified tag.
result — If not-null, only return the checks with the specified result

Returns: List of value-checks that match the specified filters.

Observe

void Observe(IHandleTransactionLifecycle observer)

Registers an observer that will only be called once the transaction state changes

void Observe(Action<FdbOperationContext, FdbTransactionState> callback)

Registers a callback that will be called when the transaction state changes

void Observe(Func<FdbOperationContext, CancellationToken, Task> callback)

Registers a callback that will be called when the transaction state changes

OnCommitFailed

void OnCommitFailed(Action<IFdbTransaction, FdbError> callback)

Register a callback that will only be called once the transaction has completed successfully (after a commit for write transactions)

NOTE: there are no guarantees that the callback will fire at all, so this should only be used for cache updates or idempotent operations!

void OnCommitFailed(Func<IFdbTransaction, FdbError, CancellationToken, Task> callback)

Register a callback that will only be called once the transaction has completed successfully (after a commit for write transactions)

Please note that it is NOT guaranteed that the callback will be called at all! This should only be used for cache updates, idempotent operations, or for logging purpose.

OnConflict

void OnConflict(Action<IFdbTransaction> callback)

Register a callback that will be called if the transaction fails to commit with a NotCommitted error (conflict with another transaction)

Please note that it is NOT guaranteed that the callback will be called at all! This should only be used for cache updates, idempotent operations, or for logging purpose.

void OnConflict(Func<IFdbTransaction, CancellationToken, Task> callback)

Register a callback that will only be called once the transaction has completed successfully (after a commit for write transactions)

Please note that it is NOT guaranteed that the callback will be called at all! This should only be used for cache updates, idempotent operations, or for logging purpose.

OnSuccess

void OnSuccess(Action<IFdbTransaction> callback)

Register a callback that will only be called once the transaction has completed successfully (after a commit for write transactions)

Please note that it is NOT guaranteed that the callback will be called at all! This should only be used for cache updates, idempotent operations, or for logging purpose.

void OnSuccess(Func<IFdbTransaction, CancellationToken, Task> callback)

Register a callback that will only be called once the transaction has completed successfully (after a commit for write transactions)

Please note that it is NOT guaranteed that the callback will be called at all! This should only be used for cache updates, idempotent operations, or for logging purpose.

RemoveLocalData

bool RemoveLocalData<TState, TToken>(TToken key)

Remove a cached instance previously attached to the transaction

key — Value of the key to remove. If there can be only one instance per TState, use a constant such as the string.Empty

Returns: Returns true if the value was found and removed; otherwise, false.

ReplaceLocalData

TState ReplaceLocalData<TState, TToken>(TToken key, TState newState)

Replace the value of a cached instance attached to the transaction, and return the previous one

key — Value of the key to remove. If there can be only one instance per TState, use a constant such as the string.Empty
newState — New instance that must be attached to the transaction

Returns: Previous cached instance, or null if none was found.

SetLocalData

void SetLocalData<TState, TToken>(TToken key, TState newState)

Set the value of a cached instance attached to the transaction

key — Value of the key to remove. If there can be only one instance per TState, use a constant such as the string.Empty
newState — New instance that must be attached to the transaction

Returns: If there was already a cached instance for this key, it will be discarded

TestValueCheckFromPreviousAttempt

FdbValueCheckResult TestValueCheckFromPreviousAttempt(string tag)

Return the result of all value checks performed with the specified tag in the previous attempt

tag — Tag that was passed to a call to AddValueCheck (or similar overloads) in the previous attempt of this context, that failed (meaning the expected value did not match with the database)

Returns: Combined result of all value checks with this tag. If Unknown no check was performed with this tag in the previous attempt, and the application is left to decide the odds of the value having changed in the database.

The caller should use this as a hint about the likelyhood that previously cached data is invalid, and should be discarded. Note that this method can fall victim to the ABA pattern, meaning that a subsquent read of the checked key could return the expected value (changed back to its original value by another transaction). To reduce the chances of ABA, checked keys should only be updated using atomic increment operations, or use versionstamps if possible. If you need to get more precise results about which key/value pair passed or failed, you can also call with the same tag, which will returns all key/value pairs with their individual results.

TryGetLocalData

bool TryGetLocalData<TState, TToken>(TToken key, out TState state)

Return the corresponding instance attached to the transaction, if it exists.

key — Value of the key. If there can be only one instance per TState, use a constant such as the string.Empty
state — Receive the value if it was found; otherwise, default()

Returns: Returns true if the value was found; otherwise, false.