Actors.Actor.Entity (spawn v2.0.0-RC12)

View Source

Manages 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

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_state(ref, opts \\ [])

@spec get_state(any(), any()) :: {:error, term()} | {:ok, term()}

Retrieve the Actor state direct from memory.

handle_call(msg, from, state)

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 using FlameScheduler.schedule_and_invoke/2.
    • For non-task actors, the function directly invokes the action using Invocation.invoke/2.
  • 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:

  1. The actor's state is unpacked via EntityState.unpack/1.
  2. 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.
    • For other actions, do_handle_defaults/3 is called to manage additional behaviors.
  3. 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

invoke(ref, request, opts \\ [])

@spec invoke(any(), any(), any()) :: any()

Synchronously invokes an Action on an Actor.

invoke_async(ref, request, opts \\ [])

@spec invoke_async(any(), any(), any()) :: :ok

Asynchronously invokes an Action on an Actor.

liveness(ref, opts \\ [])

Retrieve the health check liveness status.

readiness(ref, opts \\ [])

@spec readiness(any(), any()) :: {:error, term()} | {:ok, term()}
@spec readiness(any(), any()) :: {:error, term()} | {:ok, term()}

Retrieve the health check readiness status.

replay(ref, opts)

@spec replay(pid() | module(), Keyword.t()) :: {:error, term()} | :ok

When the Actor is a Projection the messages sent to the projection can be reprocessed. See this for more information about this programming model.

start_link(state)

Starts the entity for a given actor state.