Trait Agent 

pub trait Agent:
    Sized
    + Send
    + 'static {
    type Context: AgentContext<Self>;
    type Link: From<Address<Self>>;

    // Provided methods
    fn initialize(&mut self, _ctx: &mut Context<Self>) -> Next<Self> { ... }
    fn begin(&mut self) -> Next<Self> { ... }
    fn interrupt(&mut self, ctx: &mut Context<Self>) { ... }
    fn event<'life0, 'life1, 'async_trait>(
        &'life0 mut self,
        ctx: &'life1 mut Context<Self>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn failed(&mut self, err: Error, _ctx: &mut Context<Self>) { ... }
    fn rollback<'life0, 'life1, 'async_trait>(
        _this: Option<&'life0 mut Self>,
        _err: Error,
        _ctx: &'life1 mut Context<Self>,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn finalize(&mut self, _ctx: &mut Context<Self>) { ... }
    fn end(&mut self) { ... }
}

Agent is a universal trait of a hybrid (transactional) actor. It has a rich lifecycle, beginning its execution with the initialize method, which in turn calls the begin method. This nesting allows for initialization with context or simply setting an initial state.

Agent is an actor that either reactively processes incoming messages or executes special states, similar to a finite state machine, temporarily blocking message processing. This enables the actor to be prepared for operation or reconfigured in a transactional mode.

Required Associated Types

type Context: AgentContext<Self>

Context is the functional environment in which an actor operates.

type Link: From<Address<Self>>

Link is a means of interacting with an actor—it essentially defines the available methods that send specific types of messages.

If a special interface is not required, it makes sense to simply use Address<Self>.

Provided Methods

fn initialize(&mut self, _ctx: &mut Context<Self>) -> Next<Self>

The initialize method is called first when the actor starts. It should return a Next state, which the actor will transition to.

An execution context is passed as a parameter.

By default, the method implementation calls the begin method.

fn begin(&mut self) -> Next<Self>

The begin method is an initialization method without context.

It is usually the most commonly used method to start the actor in transactional mode by initiating finite state machine message processing.

If the method is not overridden, it starts the actor’s mode—reactive message processing. You can achieve this by calling the Next::events() method.

fn interrupt(&mut self, ctx: &mut Context<Self>)

The method is called when an attempt is made to interrupt the agent’s execution.

It is triggered only in actor mode. If the agent is in finite state machine mode, it will not be called until it transitions to a reactive state by invoking Next::events().

The default implementation interrupts the agent’s execution by calling the Context::shutdown() method.

By overriding this method, you can define your own termination rules, for example, initiating a finalization process that determines whether the agent should actually be terminated.

fn event<'life0, 'life1, 'async_trait>( &'life0 mut self, ctx: &'life1 mut Context<Self>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The method responsible for handling messages in actor mode.

The default implementation calls the next_envelope() method of the agent’s context, thereby retrieving a message with a handler and executing it by calling the handle() method.

If the channel has been closed, the stop() method of the context will be called, immediately halting execution. The request message for interrupting the actor is received through the same mechanism and closes the channel.

fn failed(&mut self, err: Error, _ctx: &mut Context<Self>)

This method is called every time a handler call ends with an unhandled error.

By default, it simply logs the error, but you can also define additional actions since the method has access to the agent’s context.

fn rollback<'life0, 'life1, 'async_trait>( _this: Option<&'life0 mut Self>, _err: Error, _ctx: &'life1 mut Context<Self>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The rollback method is called when the agent is completely terminated due to an error. In this case, the method receives a reference to the agent instance, if it was successfully preserved, as well as the error that caused the agent’s runtime to fail fatally. Additionally, a context is available to extract additional data.

fn finalize(&mut self, _ctx: &mut Context<Self>)

The finalize method is called when the agent has fully terminated. This method has access to the context. By default, its implementation calls another agent method, end.

fn end(&mut self)

The end method is called when the agent’s runtime has fully terminated to perform final actions with the agent.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors