Actors.Actor.Entity (spawn v2.0.0-RC12)
View SourceManages the lifecycle of the Host Actor through the Entity
module.
The Entity
module provides a GenServer-based implementation for controlling the
lifecycle of actors, handling various actions, and interacting with the underlying
actor system.
Behavior
The module implements GenServer behavior with transient restart semantics.
Initialization: The module initializes the actor state and handles the loading of persisted states.
State Handling: Manages the lifecycle of the actor, including state transitions, initialization actions, and periodic snapshots.
Interaction: Exposes client APIs for retrieving actor state, synchronously invoking actions, and asynchronously triggering actions.
Terminating: Ensures that the actor's state will be saved and performs all necessary cleanups.
Client APIs
The following client APIs are available for interaction:
start_link/1
: Starts the entity for a given actor state.get_state/2
: Retrieves the actor state directly from memory.invoke/3
: Synchronously invokes an action on an actor.invoke_async/3
: Asynchronously invokes an action on an actor.
Callbacks
init/1
: Initializes the actor entity.handle_continue/2
: Handles asynchronous events during the actor lifecycle.handle_call/3
: Handles synchronous calls to the actor.handle_cast/2
: Handles asynchronous casts to the actor.handle_info/2
: Handles informational messages.terminate/2
: Terminates the actor entity.
Client APIs
start_link/1: Starts the entity for a given actor state.
get_state/2: Retrieves the actor state directly from memory.
invoke/3: Synchronously invokes an action on an actor.
invoke_async/3: Asynchronously invokes an action on an actor.
Usage
To use this module, start the actor by calling start_link/1
with an initial actor state.
Interaction with the actor is facilitated through the provided client APIs such as get_state/2
, invoke/3
, and invoke_async/3
.
Example
{:ok, actor} = Actors.Actor.Entity.start_link(%EntityState{actor: %Actor{id: %ActorId{name: "example"}}})
state = Actors.Actor.Entity.get_state(actor)
{:ok, result} = Actors.Actor.Entity.invoke(actor, %InvocationRequest{action: :some_action})
Note: Ensure proper configuration and integration with the distributed system for seamless actor interactions.
Summary
Functions
Returns a specification to start this module under a supervisor.
Retrieve the Actor state direct from memory.
Handles different types of incoming call
actions for an actor process.
Synchronously invokes an Action on an Actor.
Asynchronously invokes an Action on an Actor.
Retrieve the health check liveness status.
Retrieve the health check readiness status.
When the Actor is a Projection the messages sent to the projection can be reprocessed. See this for more information about this programming model.
Starts the entity for a given actor state.
Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
Retrieve the Actor state direct from memory.
Handles different types of incoming call
actions for an actor process.
This function is responsible for processing actions sent to the actor. It distinguishes between invocation requests
and other default actions. The main action handled is the :invocation_request
, which includes logic for task-based
actors and synchronous execution.
Parameters:
action
: Represents the action to be handled by the actor. It can be a tuple of{:invocation_request, invocation, opts}
or other actions.from
: The caller process that made the request, usually a tuple containing the PID and a reference.state
: The current state of the actor, typically passed in a packed format and unpacked at the start of the function.
Action Handling:
{:invocation_request, invocation, opts}
:- If the actor is of kind
:TASK
, the function schedules the task execution remotely usingFlameScheduler.schedule_and_invoke/2
. - For non-task actors, the function directly invokes the action using
Invocation.invoke/2
.
- If the actor is of kind
- Default actions are delegated to
do_handle_defaults/3
.
Return Value:
The function returns a packed response, which is either the result of an invocation or the default action handling.
The response is further processed by parse_packed_response/1
.
Workflow:
- The actor's state is unpacked via
EntityState.unpack/1
. - Based on the
action
:- For
{:invocation_request, invocation, opts}
, the function checks if the actor is of kind:TASK
:- If true, the invocation is handled remotely with the remote task scheduler (
FlameScheduler
), ensuring proper remote invocation while maintaining local state consistency. - Otherwise, the action is invoked locally.
- If true, the invocation is handled remotely with the remote task scheduler (
- For other actions,
do_handle_defaults/3
is called to manage additional behaviors.
- For
- The final response is returned as a packed structure after being processed by
parse_packed_response/1
.
See Also:
handle_invocation_request/4
schedule_task_invocation/3
FlameScheduler.schedule_and_invoke/2
Invocation.invoke/2
Synchronously invokes an Action on an Actor.
Asynchronously invokes an Action on an Actor.
Retrieve the health check liveness status.
@spec readiness(any(), any()) :: {:error, term()} | {:ok, term()}
@spec readiness(any(), any()) :: {:error, term()} | {:ok, term()}
Retrieve the health check readiness status.
When the Actor is a Projection the messages sent to the projection can be reprocessed. See this for more information about this programming model.
Starts the entity for a given actor state.