sabi

Trait DataConn

Source 
pub trait DataConn {
    // Required methods
    fn commit(&mut self, ag: &mut AsyncGroup<'_>) -> Result<(), Err>;
    fn rollback(&mut self, ag: &mut AsyncGroup<'_>);
    fn close(&mut self);

    // Provided methods
    fn pre_commit(&mut self, ag: &mut AsyncGroup<'_>) -> Result<(), Err> { ... }
    fn post_commit(&mut self, ag: &mut AsyncGroup<'_>) { ... }
    fn should_force_back(&self) -> bool { ... }
    fn force_back(&mut self, ag: &mut AsyncGroup<'_>) { ... }
}
Expand description

The trait that abstracts a connection per session to an external data service, such as a database, file system, or messaging service.

Its primary purpose is to enable cohesive transaction operations across multiple external data services within a single transaction context. Implementations of this trait provide the concrete input/output operations for their respective data services.

Methods declared within this trait are designed to handle transactional logic. The AsyncGroup parameter in various methods allows for asynchronous processing when commit or rollback operations are time-consuming.

Required Methods§

Source

fn commit(&mut self, ag: &mut AsyncGroup<'_>) -> Result<(), Err>

Attempts to commit the changes made within this data connection’s transaction.

This method should encapsulate the logic required to finalize the transaction for the specific external data service.

§Parameters
  • ag: A mutable reference to an AsyncGroup for potentially offloading time-consuming commit operations to an asynchronous runtime.
§Returns
  • Result<(), Err>: Ok(()) if the commit is successful, or an Err if the commit fails.
Source

fn rollback(&mut self, ag: &mut AsyncGroup<'_>)

Rolls back any changes made within this data connection’s transaction.

This method undoes all operations performed since the beginning of the transaction, restoring the data service to its state before the transaction began.

§Parameters
  • ag: A mutable reference to an AsyncGroup for potentially offloading time-consuming rollback operations to an asynchronous runtime.
Source

fn close(&mut self)

Closes the connection to the external data service.

This method should release any resources held by the data connection, ensuring a graceful shutdown of the connection.

Provided Methods§

Source

fn pre_commit(&mut self, ag: &mut AsyncGroup<'_>) -> Result<(), Err>

This method is executed before the transaction commit process for all DataConn instances involved in the transaction.

This method provides a timing to execute unusual commit processes or update operations not supported by transactions beforehand. This allows other update operations to be rolled back if the operations in this method fail.

Source

fn post_commit(&mut self, ag: &mut AsyncGroup<'_>)

This method is executed after the transaction commit process has successfully completed for all DataConn instances involved in the transaction.

It provides a moment to perform follow-up actions that depend on a successful commit. For example, after a database commit, a messaging service’s DataConn might use this method to send a “transaction completed” message.

§Parameters
  • ag: A mutable reference to an AsyncGroup for potentially offloading asynchronous post-commit operations.
Source

fn should_force_back(&self) -> bool

Determines whether a “force back” operation is required for this data connection.

A force back is typically executed if one external data service successfully commits its changes, but a subsequent external data service within the same transaction fails its commit. This method indicates if the committed changes of this data service need to be undone (forced back).

§Returns
  • bool: true if a force back is needed for this connection, false otherwise.
Source

fn force_back(&mut self, ag: &mut AsyncGroup<'_>)

Executes an operation to revert committed changes.

This method provides an opportunity to undo changes that were successfully committed to this external data service, typically when a commit fails for another data service within the same distributed transaction, necessitating a rollback of already committed changes.

§Parameters
  • ag: A mutable reference to an AsyncGroup for potentially offloading asynchronous force back operations.

Implementors§