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.