Implementation Details

This page provides technical specifics about Theater's implementation, covering internal data structures, algorithms, and design decisions.

Actor Executor

WebAssembly Engine

Theater uses Wasmtime as its WebAssembly engine:

• Component Model Support: Uses Wasmtime's component model implementation
• Resource Management: Handles memory and table limits
• Capability Exposure: Controls which capabilities are available to components
• Asynchronous Execution: Supports async operations through poll-based approach

Host Function Implementation

Host functions are implemented using:

• WIT Bindings: Generated from WIT interface definitions
• Capability Checking: Runtime validation of permission to use functions
• Event Recording: Automatic recording of function invocations
• Resource Limiting: Constraints on resource usage

Event Chain

Data Structure

The Event Chain uses a linked data structure:

• Block Structure: Events are grouped into blocks
• Cryptographic Linking: Each block links to previous block via hash
• Content Addressing: Events and blocks are referenced by content hash
• Efficiency: Uses optimized serialization for compact representation

Persistence

Event Chain persistence strategy:

• Incremental Storage: New events are appended efficiently
• Background Compaction: Periodic optimization of storage
• Index Structures: Efficient lookup by actor, time, or event type
• Pruning Options: Configurable retention policies

Store System

Content-Addressing

Store's content-addressed architecture:

• Hash Function: SHA-256 for content identification
• Deduplication: Identical content stored only once
• Chunking Strategy: Large content split into manageable chunks
• Reference Counting: Tracks usage for garbage collection

Caching

Store's multi-level caching strategy:

• Memory Cache: Hot data kept in memory
• Local Disk Cache: Frequently accessed data on local storage
• Distributed Cache: Optional shared cache for clusters
• Prefetching: Predictive loading based on access patterns

Message Processing

Queue Implementation

Message queue architecture:

• Priority Handling: Messages can have different priorities
• Backpressure: Flow control for overloaded actors
• Delivery Guarantees: At-least-once delivery semantics
• Batching: Efficient processing of multiple messages

Concurrency Model

Approach to concurrent execution:

• Actor Isolation: Actors execute independently
• Thread Pool: Configurable worker threads for execution
• Work Stealing: Efficient distribution of processing load
• Fairness Policies: Prevent starvation of actors

Supervision System

Fault Detection

How failures are detected:

• Exception Tracking: Catches WebAssembly exceptions
• Resource Monitoring: Detects excessive resource usage
• Deadlock Detection: Identifies non-responsive actors
• Health Checks: Periodic verification of actor health

Recovery Implementation

How recovery is implemented:

• State Preservation: Maintains actor identity during restarts
• Mailbox Handling: Options for preserving or discarding pending messages
• Escalation Chain: Multi-level supervision hierarchy
• Circuit Breaking: Prevents repeated rapid failures

Networking

Protocol Design

Communication protocol details:

• Message Format: Binary protocol with versioning
• Compression: Adaptive compression based on content
• Authentication: TLS with certificate validation
• Multiplexing: Multiple logical connections over single transport

WebSocket Implementation

WebSocket support details:

• Subprotocol: Theater-specific subprotocol
• Event Streaming: Efficient real-time events
• Backpressure: Client-side flow control
• Reconnection: Automatic reconnection with session resumption

Understanding these implementation details provides insight into the technical decisions that enable Theater's unique properties and how they are realized in practice.