Transaction

public protocol Transaction

This protocol describes a transaction that is occurring on a database.

  • read(_:snapshot:) Default implementation

    This method reads a value from the data store.

    This will automatically add a read conflict for the key, so that if it has changed since the start of this transaction this transaction will not be accepted.

    If this is a snapshot read, this will not add a read conflict.

    Default Implementation

    This method reads a key as a tuple.

    Declaration

    Swift

    func read(_ key: DatabaseValue, snapshot: Bool) -> EventLoopFuture<DatabaseValue?>

    Parameters

    key

    The key that we are reading.
    snapshot

    Whether we should do a snapshot read.

    Return Value

    The value that we are reading, if any exists.

  • This method finds a key using a key selector.

    Declaration

    Swift

    func findKey(selector: KeySelector, snapshot: Bool) -> EventLoopFuture<DatabaseValue?>

    Parameters

    selector

    The selector telling us where to find the key.
    snapshot

    Whether we should perform a snapshot read when finding the key.

    Return Value

    The first key matching this selector.

  • This method reads a range of values for a range of keys matching two key selectors.

    The keys included in the result range will be from the first key matching the start key selector to the first key matching the end key selector. The start key will be included in the results, but the end key will not.

    The results will be ordered in lexographic order by their keys.

    This will automatically add a read conflict for the range, so that if any key has changed in this range since the start of this transaction this transaction will not be accepted.

    If this is a snapshot read, this will not add a read conflict.

    Declaration

    Swift

    func readSelectors(from start: KeySelector, to end: KeySelector, limit: Int?, mode: StreamingMode, snapshot: Bool, reverse: Bool) -> EventLoopFuture<ResultSet>

    Parameters

    start

    The selector for the beginning of the range.
    end

    The selector for the end of the range.
    limit

    The maximum number of values to return.
    mode

    A mode specifying how we should chunk the return values from each iteration of the read.
    snapshot

    Whether we should treat this as a snapshot read.
    reverse

    Whether we should reverse the order of the rows.

    Return Value

    A list of tuples with the keys and their corresponding values.

  • store(key:value:) Default implementation

    This method stores a value for a key.

    Default Implementation

    This method stores a value as a tuple.

    Declaration

    Swift

    func store(key: DatabaseValue, value: DatabaseValue)

    Parameters

    key

    The key that we are storing the value under.
    value

    The value that we are storing.
  • clear(key:) Default implementation

    This method clears a value for a key.

    Default Implementation

    This method clears a key, specified as a tuple.

    Declaration

    Swift

    func clear(key: DatabaseValue)

    Parameters

    key

    The key that we are clearing.
  • clear(range:) Default implementation

    This method clears a range of keys.

    Default Implementation

    This method clears a range of keys.

    This method clears a range of keys.

    Declaration

    Swift

    func clear(range: Range<DatabaseValue>)

    Parameters

    range

    The range of keys to clear.
  • addReadConflict(on:) Default implementation

    This method adds a range of keys that we want to reserve for reading.

    If the transaction is committed and the database has any changes to keys in this range, the commit will fail.

    Default Implementation

    This method adds a range of keys that we want to reserve for reading.

    If the transaction is committed and the database has any changes to keys in this range, the commit will fail.

    This method adds a range of keys that we want to reserve for reading.

    If the transaction is committed and the database has any changes to keys in this range, the commit will fail.

    Declaration

    Swift

    func addReadConflict(on range: Range<DatabaseValue>)

    Parameters

    range

    The range of keys to add the conflict on.

  • This method adds a range of keys that we want to reserve for writing.

    If the system commits this transaction, and another transaction has a read conflict on one of these keys, that second transaction will then fail to commit.

    Declaration

    Swift

    func addWriteConflict(on range: Range<DatabaseValue>)

    Parameters

    range

    The range of keys to add the conflict on.

  • This method gets the version of the database that this transaction is reading from.

    Declaration

    Swift

    func getReadVersion() -> EventLoopFuture<Int64>

  • This method gets the version of the database that this transaction should read from.

    Declaration

    Swift

    func setReadVersion(_ version: Int64)

    Parameters

    version

    The new version.

  • This method gets the version of the database that this transaction committed its changes at.

    If the transaction has not committed, this will return -1.

    Declaration

    Swift

    func getCommittedVersion() -> EventLoopFuture<Int64>

  • This method attempts to retry a transaction after an error.

    If the error is retryable, this will reset the transaction and fire the returned future when the transaction is ready to use again. If the error is not retryable, the returned future will rethrow the error.

    Declaration

    Swift

    func attemptRetry(error: Error) -> EventLoopFuture<Void>

    Parameters

    error

    The error that the system encountered.

    Return Value

    A future indicating when the transaction is ready again.

  • This method resets the transaction to its initial state.

    Declaration

    Swift

    func reset()

  • This method cancels the transaction, preventing it from being committed and freeing up some associated resources.

    Declaration

    Swift

    func cancel()

  • This method performs an atomic operation against a key and value.

    Declaration

    Swift

    func performAtomicOperation(operation: MutationType, key: DatabaseValue, value: DatabaseValue)

    Parameters

    operation

    The operation to perform.
    key

    The key to read for the operation.
    value

    The new value to provide to the operation.

  • This method gets a version stamp, which is a key segment containing the committed version of the transaction.

    This can be called before the transaction is committed, and it will only return a value once the transaction is committed.

    Declaration

    Swift

    func getVersionStamp() -> EventLoopFuture<DatabaseValue>

  • This method sets an option on the transaction.

    Some options require values to be set on them, and some do not. The options that do not require a value have the semantics of setting a flag to true.

    See TransactionOption for more details on what options require a value.

    Declaration

    Swift

    func setOption(_ option: TransactionOption, value: DatabaseValue?)

    Parameters

    option

    The option to set.
    value

    The value to set for the option.
  • read(range:) Extension method

    This method reads a range of values for a range of keys.

    The results will be ordered in lexographic order by their keys.

    This will automatically add a read conflict for the range, so that if any key has changed in this range since the start of this transaction this transaction will not be accepted.

    Declaration

    Swift

    public func read(range: Range<Tuple>) -> EventLoopFuture<TupleResultSet>

    Parameters

    range

    The range of keys to read.

    Return Value

    A list of tuples with the keys and their corresponding values.

  • read(range:) Extension method

    This method reads a range of values for a range of keys.

    The results will be ordered in lexographic order by their keys.

    This will automatically add a read conflict for the range, so that if any key has changed in this range since the start of this transaction this transaction will not be accepted.

    Declaration

    Swift

    public func read(range: ClosedRange<Tuple>) -> EventLoopFuture<TupleResultSet>

    Parameters

    range

    The range of keys to read.

    Return Value

    A list of tuples with the keys and their corresponding values.

  • read(_:) Extension method

    This method reads a value from the database.

    Declaration

    Swift

    public func read(_ key: DatabaseValue) -> EventLoopFuture<DatabaseValue?>

    Parameters

    key

    The key to read.

    Return Value

    The value for that key.

  • This method reads a range of values for a range of keys matching two key selectors.

    The keys included in the result range will be from the first key matching the start key selector to the first key matching the end key selector. The start key will be included in the results, but the end key will not.

    The results will be ordered in lexographic order by their keys.

    This will automatically add a read conflict for the range, so that if any key has changed in this range since the start of this transaction this transaction will not be accepted.

    Declaration

    Swift

    public func read(from start: KeySelector, to end: KeySelector, limit: Int? = nil, mode: StreamingMode = .iterator, snapshot: Bool = false, reverse: Bool = false) -> EventLoopFuture<ResultSet>

    Parameters

    start

    The selector for the beginning of the range.
    end

    The selector for the end of the range.
    limit

    The maximum number of values to return.
    mode

    A mode specifying how we should chunk the return values from each iteration of the read.
    snapshot

    Whether we should treat this as a snapshot read.
    reverse

    Whether we should reverse the order of the rows.

    Return Value

    A list of tuples with the keys and their corresponding values.

  • read(range:) Extension method

    This method reads a range of values for a range of keys.

    The results will be ordered in lexographic order by their keys.

    This will automatically add a read conflict for the range, so that if any key has changed in this range since the start of this transaction this transaction will not be accepted.

    Declaration

    Swift

    public func read(range: Range<DatabaseValue>) -> EventLoopFuture<ResultSet>

    Parameters

    range

    The range of keys to read.

    Return Value

    A list of tuples with the keys and their corresponding values.

  • addReadConflict(key:) Extension method

    This method adds a read conflict on a single key.

    If this key has been changed since the transaction started, the transaction will be rejected at commit time.

    Declaration

    Swift

    public func addReadConflict(key: DatabaseValue)

    Parameters

    key

    The key to add a conflict to.
  • addWriteConflict(key:) Extension method

    This method adds a write conflict on a single key.

    If another outstanding transaction has read the key, that transaction will be rejected at commit time.

    Declaration

    Swift

    public func addWriteConflict(key: DatabaseValue)

    Parameters

    key

    The key to add a conflict to.
  • setOption(_:) Extension method

    This method sets an option on the transaction to true.

    Declaration

    Swift

    public func setOption(_ option: TransactionOption)

    Parameters

    option

    The option to set.