Struct syndicate::actor::Activation

pub struct Activation<'activation> {
    pub facet: FacetRef,
    pub state: &'activation mut RunningActor,
    /* private fields */
}

The main API for programming Syndicated Actor objects.

Through Activations, programs can access the state of their animating RunningActor and their active Facet.

Usually, an Activation will be supplied to code that needs one; but when non-Actor code (such as a linked task) needs to enter an Actor’s execution context, use FacetRef::activate to construct one.

Many actions that an entity can perform are methods directly on Activation, but methods on the RunningActor and FacetRef values contained in an Activation are also sometimes useful.

This is what other implementations call a “Turn”, renamed here to avoid conflicts with crate::schemas::protocol::Turn.

Fields

facet: FacetRef

A reference to the currently active Facet and the implementation-side state of its Actor.

state: &'activation mut RunningActor

A reference to the current state of the active Actor.

Implementations

impl<'activation> Activation<'activation>

pub fn trace_collector(&self) -> Option<TraceCollector>

pub fn create_account(&self, name: Name) -> Arc<Account>

Constructs a new Account with the given name, inheriting its trace_collector from the current Activation’s cause.

pub fn facet_ids(&mut self) -> Vec<FacetId>

Retrieves the chain of facet IDs, in order, from the currently-active Facet up to and including the root facet of the active actor. Useful for debugging.

pub fn assert<M: 'static + Send + Debug>( &mut self, r: &Arc<Ref<M>>, a: M ) -> Handle

Core API: assert a at recipient r.

Returns the Handle for the new assertion.

pub fn retract(&mut self, handle: Handle)

Core API: retract a previously-established assertion.

pub fn update<M: 'static + Send + Debug>( &mut self, handle: &mut Option<Handle>, r: &Arc<Ref<M>>, a: Option<M> )

Core API: assert, retract, or replace an assertion.

pub fn message<M: 'static + Send + Debug>(&mut self, r: &Arc<Ref<M>>, m: M)

Core API: send message m to recipient r.

pub fn sync<M: 'static + Send>(&mut self, r: &Arc<Ref<M>>, peer: Arc<Ref<Synced>>)

Core API: begins a synchronisation with r.

Once the synchronisation request reaches r’s actor, it will send a response to peer, which acts as a continuation for the synchronisation request.

pub fn on_stop_notify<M: 'static + Send>(&mut self, r: &Arc<Ref<M>>)

Registers the entity r in the list of stop actions for the active facet. If the facet terminates cleanly, r’s stop will be called in the context of the facet’s parent.

Note. If the actor crashes, stop actions will not be called.

Use RunningActor::add_exit_hook to install a callback that will be called at the end of the lifetime of the actor rather than the facet. (Also, exit hooks are called no matter whether actor termination was normal or abnormal.)

pub fn on_stop<F: 'static + Send + FnOnce(&mut Activation<'_>) -> ActorResult>( &mut self, action: F )

Registers action in the list of stop actions for the active facet. If the facet terminates cleanly, action will be called in the context of the facet’s parent. See also notes against on_stop_notify.

pub fn account(&self) -> &Arc<Account>

Retrieve the Account against which actions are recorded.

pub fn commit(&mut self) -> ActorResult

Delivers all pending actions in this activation and resets it, ready for more. Succeeds iff all pre-commit actions succeed.

Commit procedure

If an activation’s f function returns successfully, the activation commits according to the following procedure:

1. While the dataflow graph needs repairing or outstanding pre-commit actions exist:

   1. repair the dataflow graph
   2. run all pre-commit actions Note that graph repair or a pre-commit action may fail, causing the commit to abort, or may further damage the dataflow graph or schedule another pre-commit action, causing another go around the loop.

2. The commit becomes final. All queued events are sent; all internal accounting actions are performed.

pub fn inert_entity<M>(&mut self) -> Arc<Ref<M>>

Construct an entity with behaviour InertEntity within the active facet.

pub fn create<M, E: Entity<M> + Send + 'static>(&mut self, e: E) -> Arc<Ref<M>>

Construct an entity with behaviour e within the active facet.

pub fn create_inert<M>(&mut self) -> Arc<Ref<M>>

Construct an entity (within the active facet) whose behaviour will be specified later via become_entity.

pub fn linked_task<F: 'static + Send + Future<Output = Result<LinkedTaskTermination, Error>>>( &mut self, name: Name, boot: F )

Start a new linked task attached to the active facet. The task will execute the future “boot” to completion unless it is cancelled first (by e.g. termination of the owning facet or crashing of the owning actor). Stops the active facet when the linked task completes. Uses name for log messages emitted by the task.

pub fn after<F: 'static + Send + FnOnce(&mut Activation<'_>) -> ActorResult>( &mut self, duration: Duration, a: F )

Executes the given action after the given duration has elapsed (so long as the active facet still exists at that time).

pub fn every<F: 'static + Send + FnMut(&mut Activation<'_>) -> ActorResult>( &mut self, duration: Duration, a: F ) -> ActorResult

Executes the given action immediately, and then every time another multiple of the given duration has elapsed (so long as the active facet still exists at that time).

pub fn at<I: Into<Instant>, F: 'static + Send + FnOnce(&mut Activation<'_>) -> ActorResult>( &mut self, instant: I, a: F )

Executes the given action at the given instant (so long as the active facet still exists at that time).

pub fn pre_commit<F: 'static + Send + FnOnce(&mut Activation<'_>) -> ActorResult>( &mut self, action: F )

Schedules the given action to run just prior to commit.

pub fn spawn<F: 'static + Send + FnOnce(&mut Activation<'_>) -> ActorResult>( &mut self, name: Name, boot: F ) -> ActorRef

Schedule the creation of a new actor when the Activation commits.

pub fn spawn_link<F: 'static + Send + FnOnce(&mut Activation<'_>) -> ActorResult>( &mut self, name: Name, boot: F ) -> ActorRef

Schedule the creation of a new actor when the Activation commits.

The new actor will be “linked” to the active facet: if the new actor terminates, the active facet is stopped, and if the active facet stops, the new actor’s root facet is stopped.

pub fn facet<F: FnOnce(&mut Activation<'_>) -> ActorResult>( &mut self, boot: F ) -> Result<FacetId, ActorError>

Create a new subfacet of the currently-active facet. Runs boot in the new facet’s context. If boot returns leaving the new facet inert, the new facet is stopped.

pub fn prevent_inert_check(&mut self) -> DisarmFn

Useful during facet (and actor) startup, in some situations: when a facet boot procedure would return while the facet is inert, but the facet should survive until some subsequent time, call prevent_inert_check to increment a counter that prevents inertness-checks from succeeding on the active facet.

The result of prevent_inert_check is a function which, when called, decrements the counter again. After the counter has been decremented, any subsequent inertness checks will no longer be artificially forced to fail.

An example of when you might want this: creating an actor having only a single Dataspace entity within it, then using the Dataspace from other actors. At the start of its life, the Dataspace actor will have no outbound assertions, no child facets, and no linked tasks, so the only way to prevent it from being prematurely garbage collected is to use prevent_inert_check in its boot function.

pub fn stop_facet_and_continue<F: 'static + Send + FnOnce(&mut Activation<'_>) -> ActorResult>( &mut self, facet_id: FacetId, continuation: Option<F> ) -> ActorResult

If continuation is supplied, adds it as a stop action for the Facet named by facet_id. Then, cleanly stops the facet immediately, without waiting for self to commit.

pub fn stop_facet(&mut self, facet_id: FacetId)

Arranges for the Facet named by facet_id to be stopped cleanly when self commits.

Equivalent to self.stop_facet_and_continue(facet_id, None), except that the lack of a continuation means that there’s no need for this method to return ActorResult.

pub fn stop(&mut self)

Arranges for the active facet to be stopped cleanly when self commits.

Equivalent to self.stop_facet(self.facet.facet_id).

pub fn stop_root(&mut self)

Arranges for the active actor’s root facet to be stopped cleanly when self commits; this is one way to arrange a clean shutdown of the entire actor.

Equivalent to self.stop_facet(self.state.root).

pub fn named_field<T: Any + Send>( &mut self, name: &str, initial_value: T ) -> Arc<Field<T>>

Create a new named dataflow variable (field) within the active Actor.

pub fn field<T: Any + Send>(&mut self, initial_value: T) -> Arc<Field<T>>

Create a new anonymous dataflow variable (field) within the active Actor.

pub fn get<T: Any + Send>(&mut self, field: &Field<T>) -> &T

Retrieve a reference to the current value of a dataflow variable (field); if execution is currently within a dataflow block, marks the block as depending upon the field.

pub fn get_mut<T: Any + Send>(&mut self, field: &Field<T>) -> &mut T

Retrieve a mutable reference to the contents of a dataflow variable (field). As for get, if used within a dataflow block, marks the block as depending upon the field. In addition, because the caller may mutate the field, this function (pessimistically) marks the field as dirty, which will lead to later reevaluation of dependent blocks.

pub fn set<T: Any + Send>(&mut self, field: &Field<T>, value: T)

Overwrite the value of a dataflow variable (field). Marks the field as dirty, even if the new value is eq to the value being overwritten.

pub fn dataflow<F: 'static + Send + FnMut(&mut Activation<'_>) -> ActorResult>( &mut self, block: F ) -> ActorResult

Creates (and immediately executes) a new dataflow block that will be reexecuted if any of its dependent fields (accessed via e.g. get or get_mut) are mutated.

Trait Implementations

impl<'activation> Drop for Activation<'activation>

fn drop(&mut self)

Executes the destructor for this type.