repository·master·Indexed 18 days ago
https://github.com/thespianpy/thespianAn actor-based framework for Python providing distributed computing capabilities, including actor management, automatic scaling, and environment orchestration. Features include Actor Troupes for parallel operations, multi-system conventions for distributed communication, fault tolerance with atomic messaging, and dynamic capability-based deployment. Supports loadable sources for updating actor code without restarting the system.
The Act 2 example demonstrates a pattern to solve periodic failures (such as missing updates or unexpected actor creation) that occur during startup handshakes.
Instead of using non-deterministic delays (like time.sleep()) or making actors ephemeral, this example uses a message-passing pattern:
Include the destination address (e.g., the address of an Analyzer) directly within the request message (e.g., EncodeThis). This allows the sender to provide the routing information immediately. The system will automatically delay the message until the target actor is ready, ensuring a deterministic startup without manual synchronization.
globalName when creating the primary entry point Actor (such as an Acceptor). By assigning a specific globalName, Thespian can re-use the existing set of running Actors instead of spawning new processes.In Thespian, killing a parent Actor causes all of its child Actors to be killed as well.
If you kill the primary entry point Actor (e.g., the Acceptor), all downstream child processes (like Analyzer or Encoder actors) will also be terminated. Because the globalName is no longer associated with a running process, the next time the application is invoked, Thespian will create a completely new instance of the Actor hierarchy.
Thespian supports multi-system configurations where multiple Actor Systems run independently (often on different network nodes). You can define specific capabilities for each system to control which Actors run where.
Actors can specify their requirements using the @requireCapability syntax. An Actor will only run in a system that possesses a matching set of capabilities. This allows for:
In this example setup, systems communicate via an administrator port. The first system started on port 1900 acts as the convention leader.
# Example of starting systems with specific capabilities
$ python start.py 1900
$ python start.py 10000 "morse,Caesar cipher"
$ python start.py 10101 "64bit encoder"In Thespian, when a child actor exits, its parent actor receives a ChildActorExited message. You can use this message to perform cleanup or state management, such as removing the exited child's address from a tracking dictionary. This allows the parent to detect the failure and restart the child when a new request arrives.
Additionally, when an actor is being killed, it receives an ActorExitRequest message. You can intercept this message within your actor to perform shutdown or cleanup operations before the actor terminates.
To build resilient, self-healing Actor-based applications, favor atomic messaging.
Instead of relying on an Actor's internal state to hold partial information for a multi-step request, pass all the information required to process a request within a single message. This ensures that if an actor (like an Analyzer) is killed and restarted, the new instance can immediately process subsequent requests using the information provided in the message, without needing to recover lost state.
Thespian supports a 'loadable source' feature that allows you to update running Actor code without restarting the Actor System. This is achieved by loading a ZIP file containing updated source code into a running system.
.zip file.createActor(), pass the returned source hash to ensure the Actor is instantiated from that specific version of the code.Source Authority. When new sources are loaded, they are passed to this Actor for validation (e.g., checking digital signatures) or decryption. Thespian only allows Actor creation from a source once the Source Authority has validated it.# Conceptual usage when creating an actor from a specific loaded source
# The source_hash is obtained from the load operation
actor_ref = system.createActor(MyActorClass, name='my_actor', sourceHash='a3ad084f02e92c6a2e3eb70e5d72a6c2')Multiple Thespian systems can communicate as part of a "convention". In this architecture, a Convention Leader handles all registration, resulting in a star topology for the convention.
Convention management is handled entirely by Thespian, meaning it has little to no impact on standard Actor development. However, Actors can optionally participate in Convention-related events.
You can manage the lifecycle of Actor Systems and their capabilities dynamically without restarting the entire application.
Use start.py with the following arguments:
port: The port number for the system's administrator.capabilities: A comma-separated list (no whitespace) of capabilities to assign to the system.Use stop.py to shut down specific Actor Systems. By default, it targets port 1900. You can pass additional port numbers to shut down multiple systems.
You can add or remove capabilities from a running system using a utility like chgcap.py. When a capability is removed, Thespian re-checks all running Actors in that system. If an Actor's @requireCapability specification is no longer met by the system's new capability set, the Actor is automatically shut down.
chgcap.py usage:
python chgcap.py <port> <+/-> <"capability name">
# Start a system on port 10000 with specific capabilities
$ python start.py 10000 "morse,Caesar cipher"
# Add a capability to system 10101
$ python chgcap.py 10101 + morse
# Remove a capability from system 10101
$ python chgcap.py 10101 - "64bit encoder"
# Stop multiple systems
$ python stop.py 1900 10000 10101The example consists of three main lifecycle scripts: start.py to initialize the Actor System, app.py to execute the application logic, and stop.py to clean up.
When running these scripts, you can provide an optional first argument to specify the system base (e.g., multiprocTCPBase or multiprocUDPBase).
# 1. Start the Actor System (defaults to multiprocTCPBase)
python start.py multiprocUDPBase
# 2. Run the application (pass message via stdin)
echo "Hello, World!" | python app.py multiprocUDPBase
# 3. Stop the Actor System and all Actors
python stop.py multiprocUDPBaseWhen finished with your multi-system test, use stop.py to shut down the specified Actor Systems.
$ python stop.py <port1> <port2> <port3>$ python stop.py 10101 10000 1900