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>>, ) -> StartTransaction<S>

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

pub fn read_concern(self, value: ReadConcern) -> StartTransaction<S>

Set the TransactionOptions::read_concern option.

pub fn write_concern(self, value: WriteConcern) -> StartTransaction<S>

Set the TransactionOptions::write_concern option.

pub fn selection_criteria(self, value: SelectionCriteria) -> StartTransaction<S>

Set the TransactionOptions::selection_criteria option.

pub fn max_commit_time(self, value: Duration) -> StartTransaction<S>

Set the TransactionOptions::max_commit_time option.

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

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

where F: for<'b> FnMut(&'b mut ClientSession, &'b mut C) -> Pin<Box<dyn Future<Output = Result<R, Error>> + Send + 'b>>,

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?;
*/

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, ) -> <StartTransaction<&'a mut ClientSession> as IntoFuture>::IntoFuture

Creates a future from a value.