Actor system

ThingsBoard Edge uses an actor-based concurrency model to manage per-entity state. Every device, rule chain, and calculated field gets its own actor — a lightweight object with a private mailbox. The actor processes messages one at a time, eliminating locks and race conditions across the platform.

Each actor follows this lifecycle:

1. Created on demand: When a message arrives for an entity (for example, telemetry from device ABC), the system creates an actor if one does not already exist.
2. Mailbox queuing: Incoming messages land in the actor’s mailbox, an in-memory queue.
3. Sequential processing: The actor processes messages one at a time, in order. No two threads ever execute inside the same actor simultaneously.
4. Ephemeral state: Actors may hold in-memory state (like latest attribute values or active RPC requests), but this state is rebuilt from PostgreSQL on restart. The database is always the source of truth.

Edge runs a single tenant, so the actor hierarchy is shallower than on the ThingsBoard server. One App actor sits at the root, with a single Tenant actor beneath it:

                        ┌─────────────┐
                        │  App Actor  │
                        └──────┬──────┘
                               │
                        ┌──────┴──────┐
                        │   Tenant    │
                        └──────┬──────┘
                               │
         ┌────────────┬────────┴──────┬──────────────┐
         ▼            ▼               ▼               ▼
    ┌─────────┐ ┌──────────┐  ┌────────────┐  ┌──────────────┐
    │ Device  │ │  Rule    │  │ CF Manager │  │ Cloud Sync   │
    │ Actors  │ │  Chain   │  │  Actor     │  │   Actor      │
    └─────────┘ │  Actors  │  └──────┬─────┘  └──────────────┘
                └────┬─────┘         │
                     │               ▼
               ┌─────┴─────┐  ┌──────────────┐
               ▼    ▼    ▼  │  │  CF Engine   │
             Rule Rule Rule  │  │   Actors     │
             Node Node Node  │  └──────────────┘
             Actors          │

Each actor type runs on a dedicated thread pool. This prevents one type of work from starving another — a burst of incoming telemetry does not block rule chain processing.

ACTORS_SYSTEM_THROUGHPUT (default 5) controls how many messages an actor processes in a single batch before yielding the thread to other actors:

• Low value (one to five): Each actor processes fewer messages per turn, giving all actors more equal access to the thread pool. Better when many devices send telemetry at the same time.
• High value (25–50): Actors process more messages per turn, reducing context-switch overhead. Better when a small number of devices send high-frequency telemetry.

The default of 5 works well for most Edge deployments.

Rule engine action nodes that perform I/O — database writes, HTTP calls, email, SMS — run on separate thread pools to avoid blocking the actor dispatchers:

ACTORS_MAX_CONCURRENT_SESSION_PER_DEVICE (default 1) limits how many simultaneous transport sessions a single device can hold. The default means that when a device opens a new MQTT connection, any existing session for that device closes automatically.

Increase this value only if devices on your Edge legitimately maintain multiple concurrent connections — for example, a gateway that manages several sub-connections simultaneously.

The actor system throttles error log output to prevent a misconfigured rule chain from flooding the log: