module Earl::Agent

Overview

Earl's foundation module.

Agents must implement the #call method that will be invoked when the agent is started (or spawned).

Agents have a state that is automatically maintained throughout an object life. See Status for the different statuses. Agents can act upon their state, for example loop while .running? returns true.

Direct including types

Defined in:

agent.cr
agent/state.cr

Instance Method Summary

Instance Method Detail

abstract def call #

The logic of the Agent. May loop forever or until asked to stopped. If an exception is raised the agent will be crashed; if the method returns the agent will simply stop.


[View source]
def crashed? : Bool #

[View source]
def recycle : Nil #

Tells the agent to recycle.


[View source]
def recycling? : Bool #

[View source]
def reset : Nil #

Called when the agent must be recycled. This must return the object to its pristine state so it can be restarted properly. Does nothing by default.


[View source]
def running? : Bool #

[View source]
def spawn(*, link : Agent | Nil = nil, _yield = true) : Nil #

Spawns a new Fiber to start the agent in. Doesn't block and returns immediately.


[View source]
def start(*, link : Agent | Nil = nil) : Nil #

Starts the agent in the current Fiber. Blocks until the agent is stopped or crashed.

You may link another object to be notified if the agent crashed (raised an exception) or stopped gracefully by calling its #trap method.


[View source]
def starting? : Bool #

[View source]
def stop : Nil #

Asks the agent to stop.


[View source]
def stopped? : Bool #

[View source]
def stopping? : Bool #

[View source]
def terminate : Nil #

Called when the agent is asked to stop. Does nothing by default.


[View source]
def trap(agent : Agent, exception : Exception | Nil) : Nil #

Called when a linked agent has crashed (exception is set) or stoppped (exception is nil). Does nothing by default.

Always called from the passed agent Fiber and thus never runs concurrently to the passed agent #call method. This means this method will be called concurrently to this agent. Modifying self internal state thus requires concurrency safe structures.


[View source]