§reference

ActionPlan

Where perform() stages its changes. The executor makes a new plan for each call, and for each retry, and hands it to perform(). After perform() returns, the executor writes what is on it.

Type signature

// ekbatan::action::ActionPlan
impl ActionPlan {
    pub fn new() -> Self;

    pub fn add<E: Persistable>(&mut self, persistable: E) -> Result<E, Error>;
    pub fn add_all<E: Persistable>(&mut self, persistables: Vec<E>) -> Result<Vec<E>, Error>;
    pub fn update<E: Persistable>(&mut self, persistable: E) -> Result<E, Error>;
    pub fn update_all<E: Persistable>(&mut self, persistables: Vec<E>) -> Result<Vec<E>, Error>;

    pub fn additions<E: Persistable>(&self) -> &[E];
    pub fn updates<E: Persistable>(&self) -> &[E];
    pub fn has_changes(&self) -> bool;
    pub fn changes(&self) -> impl Iterator<Item = &dyn AnyChanges>;
    pub fn events(&self) -> Vec<&dyn AnyModelEvent>;
}

Persistable is what both a model and an entity are: #[model] and #[entity] implement it. The plan holds both kinds the same way. The only difference shows when the executor writes: a model’s events become event rows, and an entity has none.

The staging methods are generic, so plan.add(wallet) gives back a Wallet, not something you have to convert.

The plan is the same in both kinds of action. An AsyncAction stages on it exactly as an Action does, and nothing on it is awaited.

One writer at a time

perform() gets the plan as &mut ActionPlan, so Rust’s borrow rules allow one writer at a time. You can’t hand the plan to several tasks or threads at once. If an action reads in parallel, wait for all the reads, then stage from perform() itself.

Staging

add(model) / add_all(models)

Stages an INSERT. Returns the value as given. The plan fills in nothing: the id, the version (with_initial_version(), which is 1) and the dates come from your builder.

update(model) / update_all(models)

Stages an UPDATE. Pass the value at the version it was read at. update returns it at version + 1, which is the version the row will have once written, so the action can return it or keep using it.

add_all and update_all stage each value in order and return them in the same order. They stop at the first error.

One row, one change

Each id can be staged once per call, per type. A second add or update of the same id returns Error::Unexpected:

Wallet 0193... is already registered for addition operation, cannot update. ...

The error stops the action, and nothing is written. Make all the changes to the value first, then stage it once:

let wallet = wallet.deposit(Decimal::TEN)?.deposit(Decimal::ONE)?;
plan.update(wallet)?;

Staging twice can’t mean two writes: the second write would need a version the database never held.

Reading the plan

additions::<E>() / updates::<E>()

What was staged for one type, in staging order. An empty slice for a type nothing was staged for. updates gives the values as staged, at the version they were read at, not version + 1.

has_changes()

Whether anything was staged. A plan with nothing on it is not an error: the call still writes one event row, as below.

changes()

Every staged type, as &dyn AnyChanges, in the order the types were first staged. Each one gives model_name(), addition_count(), update_count() and events().

events()

Every event carried by the staged models: for each type, its additions first, then its updates. Entities add nothing here.

These are mostly for tests. ActionAssert is built on them.

What the executor does with it

execute()
   +-- ActionPlan::new()
   +-- perform(&mut plan, ...)      stages on it
   +-- group the staged rows by shard
   +-- on each shard, in one transaction:
         per type: one multi-row INSERT for the additions,
                   one UPDATE for the updates (each row checked on its version)
         then the event rows

A retry gets a new plan, so nothing from a failed attempt carries over.

A call that stages nothing still writes one event row, with no event in it, on the default shard. So “this ran and found nothing to do” is in the log, and can be told apart from “this never ran”.

See also