Struct MovementManager

pub struct MovementManager { /* private fields */ }

A minimalist helper class to handle movement registration and updating based on unique [SubsystemId] values.

Implementations

impl MovementManager

pub fn new(db: Arc<dyn BarkPersister>) -> Self

Creates an instances of the MovementManager.

pub async fn register_subsystem( &self, id: Subsystem, ) -> Result<(), MovementError>

Registers a subsystem with the movement manager. Subsystems are identified using unique names, to maintain this guarantee a unique [SubsystemId] will be generated and returned by this function. Future calls to register or modify movements must provide this ID.

pub async fn new_movement( &self, subsystem_id: Subsystem, movement_kind: impl Into<String>, ) -> Result<MovementId, MovementError>

Begins the process of creating a new movement. This newly created movement will be defaulted to a MovementStatus::Pending state. It can then be updated by using MovementUpdate in combination with MovementManager::update_movement.

MovementManager::finish_movement can be used once a movement has finished (whether successful or not).

Parameters:

• subsystem_id: The ID of the subsystem that wishes to start a new movement.
• movement_kind: A descriptor for the type of movement being performed, e.g. “send”, “receive”, “round”.

Errors:

• If the subsystem ID is not recognized.
• If a database error occurs.

pub async fn new_guarded_movement( self: &Arc<Self>, subsystem_id: Subsystem, movement_kind: impl Into<String>, on_drop: OnDropStatus, ) -> Result<MovementGuard, MovementError>

Creates a new Movement and returns a MovementGuard to manage it. The guard will call MovementManager::finish_movement on drop unless MovementGuard::success has already been called.

See MovementManager::new_movement and MovementGuard::new for more information.

Parameters:

• subsystem_id: The ID of the subsystem that wishes to start a new movement.
• movement_kind: A descriptor for the type of movement being performed, e.g. “send”, “receive”, “round”.
• on_drop: Determines what status the movement will be set to when the guard is dropped.

pub async fn new_movement_with_update( &self, subsystem_id: Subsystem, movement_kind: impl Into<String>, update: MovementUpdate, ) -> Result<MovementId, MovementError>

Similar to MovementManager::new_movement but it immediately calls MovementManager::update_movement afterward.

Parameters:

• subsystem_id: The ID of the subsystem that wishes to start a new movement.
• movement_kind: A descriptor for the type of movement being performed, e.g. “send”, “receive”, “round”.
• update: Describes the initial state of the movement.

Errors:

• If the subsystem ID is not recognized.
• If a database error occurs.

pub async fn new_guarded_movement_with_update( self: &Arc<Self>, subsystem_id: Subsystem, movement_kind: impl Into<String>, on_drop: OnDropStatus, update: MovementUpdate, ) -> Result<MovementGuard, MovementError>

Similar to MovementManager::new_guarded_movement but it immediately calls MovementManager::update_movement after creating the Movement.

Parameters:

• subsystem_id: The ID of the subsystem that wishes to start a new movement.
• movement_kind: A descriptor for the type of movement being performed, e.g. “send”, “receive”, “round”.
• on_drop: Determines what status the movement will be set to when the guard is dropped.
• update: Describes the initial state of the movement.

Errors:

• If the subsystem ID is not recognized.
• If a database error occurs.

pub async fn new_finished_movement( &self, subsystem_id: Subsystem, movement_kind: impl Into<String>, status: MovementStatus, details: MovementUpdate, ) -> Result<MovementId, MovementError>

Creates and marks a Movement as finished based on the given parameters. This is useful for one-shot movements where the details are known at the time of creation, an example would be when receiving funds asynchronously from a third party.

Parameters:

• subsystem_id: The ID of the subsystem that wishes to start a new movement.
• movement_kind: A descriptor for the type of movement being performed, e.g. “send”, “receive”, “round”.
• status: The MovementStatus to set. This can’t be MovementStatus::Pending.
• details: Contains information about the movement, e.g. what VTXOs were consumed or produced.

Errors:

• If the subsystem ID is not recognized.
• If MovementStatus::Pending is given.
• If a database error occurs.

pub async fn update_movement( &self, id: MovementId, update: MovementUpdate, ) -> Result<(), MovementError>

Updates a movement with the given parameters.

See also: MovementManager::new_movement and MovementManager::finish_movement

Parameters:

• id: The ID of the movement previously created by MovementManager::new_movement.
• update: Specifies properties to set on the movement. Option fields will be ignored if they are None. Some will result in that particular field being overwritten.

Errors:

• If the MovementId is not recognized.
• If a movement is not MovementStatus::Pending.
• If a database error occurs.

pub async fn finish_movement( &self, id: MovementId, new_status: MovementStatus, ) -> Result<(), MovementError>

Finalizes a movement, setting it to the given MovementStatus.

See also: MovementManager::new_movement and MovementManager::update_movement

Parameters:

• id: The ID of the movement previously created by MovementManager::new_movement.
• new_status: The final MovementStatus to set. This can’t be MovementStatus::Pending.

Errors:

• If the movement ID is not recognized.
• If MovementStatus::Pending is given.
• If a database error occurs.

pub async fn finish_movement_with_update( &self, id: MovementId, new_status: MovementStatus, update: MovementUpdate, ) -> Result<(), MovementError>

Applies a MovementUpdate before finalizing the movement with MovementManager::finish_movement.

Parameters:

• id: The ID of the movement previously created by MovementManager::new_movement.
• new_status: The final MovementStatus to set. This can’t be MovementStatus::Pending.
• update: Contains information to apply to the movement before finalizing it.

Errors:

• If the movement ID is not recognized.
• If MovementStatus::Pending is given.
• If a database error occurs.