Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.