Actor Module Architecture

---

← Architecture Overview · §4 of 15

---

4. Actor Module (io.github.solaceharmony.core.actor)

The actor module implements the actor model for concurrent and distributed computation within SolaceCore. It provides abstractions for actors, their states, messages, and basic lifecycle management. The design emphasizes single responsibility, robust message handling, and resource management, leveraging Kotlin coroutines for asynchronous operations.

As per ACTOR_README.md, this module is designed with JDK 21+ and Kotlin 2.0.21+ in mind, utilizing features like virtual threads (implied for coroutine dispatchers), string templates, built-in UUIDs, and improved coroutines.

4.0. Actor System Design Principles, Status, and Goals

Insights from the wiki Actor System and Supervisor & Hot-Swap pages provide valuable context for the SolaceCore Actor System.

A. Design Principles

The actor system is built upon the following core principles:

• Isolation: Actors operate independently, each managing its own state and behavior, inaccessible directly by others.
• Message-Driven Communication: Interaction between actors occurs exclusively through asynchronous message passing via typed ports.
• Type Safety: Communication pathways (ports and messages) are designed to be type-safe, ensuring compatibility and reducing runtime errors.
• Concurrency: Actors are designed to process messages concurrently, leveraging Kotlin coroutines for efficient asynchronous operations.
• Lifecycle Management: Actors adhere to a well-defined lifecycle (Initialized, Running, Paused, Stopped, Error, Disposed), ensuring predictable behavior and resource management.
• Error Handling: The system aims for robust error handling, including timeouts and recovery mechanisms (though detailed recovery strategies beyond basic error states are part of future enhancements).

B. Noted Technology Considerations

• The design checklist for the hot-pluggable system mentions an objective to "Build actor-based architecture using Ktor." While Ktor was not identified as a core dependency in the :lib module's build.gradle.kts, this indicates a design consideration or potential future integration for aspects like inter-actor communication in a distributed setting or for exposing actor functionalities via network protocols.

C. Implementation Status Summary

• Completed:
  • Basic actor structure (Actor class) and lifecycle management.
  • Port system for type-safe message passing.
  • Basic error handling and timeout mechanisms within actors.
  • Collection of performance metrics (ActorMetrics).
  • Dynamic actor registration and unregistration (via SupervisorActor).
  • Hot-swapping capabilities for actors (via SupervisorActor).
• Partially Implemented / In Progress (at the time of the design documents):
  • Advanced queuing mechanisms for messages.
  • Correlation IDs for tracking tasks across multiple actors.

4.0.1. Conceptual Actor Communication Flow (Sequence Diagram)

Note: The actor communication sequence diagram and its description have been moved to the wiki Actor Communication Sequence page.

Back to Actor System