Struct StartTransaction

pub struct StartTransaction<S> { /* private fields */ }

Start a new transaction. Construct with ClientSession::start_transaction.

Implementations

impl<S> StartTransaction<S>

pub fn with_options(self, value: impl Into<Option<TransactionOptions>>) -> Self

Set all options. Note that this will replace all previous values set.

pub fn read_concern(self, value: ReadConcern) -> Self

The read concern to use for the transaction.

pub fn write_concern(self, value: WriteConcern) -> Self

The write concern to use when committing or aborting a transaction.

pub fn selection_criteria(self, value: SelectionCriteria) -> Self

The selection criteria to use for all read operations in a transaction.

pub fn max_commit_time(self, value: Duration) -> Self

The maximum amount of time to allow a single commitTransaction to run.

impl<'a> StartTransaction<&'a mut ClientSession>

pub fn run(self) -> Result<()>

Available on crate feature sync only.

Synchronously execute this action.

impl<'a> StartTransaction<&'a mut ClientSession>

pub async fn and_run<R, C, F>(self, context: C, callback: F) -> Result<R>

where F: for<'b> FnMut(&'b mut ClientSession, &'b mut C) -> BoxFuture<'b, Result<R>>,

Starts a transaction, runs the given callback, and commits or aborts the transaction. Transient transaction errors will cause the callback or the commit to be retried; other errors will cause the transaction to be aborted and the error returned to the caller. If the callback needs to provide its own error information, the Error::custom method can accept an arbitrary payload that can be retrieved via Error::get_custom.

If a command inside the callback fails, it may cause the transaction on the server to be aborted. This situation is normally handled transparently by the driver. However, if the application does not return that error from the callback, the driver will not be able to determine whether the transaction was aborted or not. The driver will then retry the callback indefinitely. To avoid this situation, the application MUST NOT silently handle errors within the callback. If the application needs to handle errors within the callback, it MUST return them after doing so.

Because the callback can be repeatedly executed and because it returns a future, the rust closure borrowing rules for captured values can be overly restrictive. As a convenience, and_run accepts a context argument that will be passed to the callback along with the session:

let coll = client.database("mydb").collection::<Document>("mycoll");
let my_data = "my data".to_string();
// This works:
session.start_transaction().and_run(
    (&coll, &my_data),
    |session, (coll, my_data)| async move {
        coll.insert_one(doc! { "data": *my_data }).session(session).await
    }.boxed()
).await?;
/* This will not compile with a "variable moved due to use in generator" error:
session.start_transaction().and_run(
    (),
    |session, _| async move {
        coll.insert_one(doc! { "data": my_data }).session(session).await
    }.boxed()
).await?;
*/

impl StartTransaction<&mut ClientSession>

pub fn run(self) -> Result<()>

Available on crate feature sync only.

Synchronously execute this action.

pub fn and_run<R, F>(self, callback: F) -> Result<R>

where F: for<'b> FnMut(&'b mut ClientSession) -> Result<R>,

Available on crate feature sync only.

Starts a transaction, runs the given callback, and commits or aborts the transaction. Transient transaction errors will cause the callback or the commit to be retried; other errors will cause the transaction to be aborted and the error returned to the caller. If the callback needs to provide its own error information, the Error::custom method can accept an arbitrary payload that can be retrieved via Error::get_custom.

If a command inside the callback fails, it may cause the transaction on the server to be aborted. This situation is normally handled transparently by the driver. However, if the application does not return that error from the callback, the driver will not be able to determine whether the transaction was aborted or not. The driver will then retry the callback indefinitely. To avoid this situation, the application MUST NOT silently handle errors within the callback. If the application needs to handle errors within the callback, it MUST return them after doing so.

Trait Implementations

impl<'a> Action for StartTransaction<&'a mut ClientSession>

fn optional<Value>( self, value: Option<Value>, f: impl FnOnce(Self, Value) -> Self, ) -> Self

where Self: Sized,

If the value is Some, call the provided function on self. Convenient for chained updates with values that need to be set conditionally. For example:

impl<'a> IntoFuture for StartTransaction<&'a mut ClientSession>

type Output = Result<(), Error>

The output that the future will produce on completion.

type IntoFuture = StartTransactionFuture<'a>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.