plugin sdk threading

About plugin threading

Plugins use a dedicated engine thread for entity operations and lifecycle methods. Understanding the threading model is essential for writing correct, performant plugin code.

Threading overview

Plugin starts on engine thread
    ↓
OnPluginLoaded and OnPluginStart run on engine thread
    ↓
Engine write operations must run on engine thread
    ↓
External threads must queue work to engine thread

Key principles

• Write operations (create, update, delete entities) must run on the engine thread.
• Entity cache reads are thread-safe but have I/O considerations (see below).
• Lifecycle methods OnPluginLoaded and OnPluginStart run on the engine thread.
• Dispose may be called from any thread.
• EventReceived and ActionReceived handlers run on the engine thread, so entity writes from them do not need QueueUpdate.
• External callbacks (System.Timers.Timer, Task continuations, ThreadPool work items) run on different threads.

GetEntity and I/O

• GetEntity(guid) or GetEntity(guid, query: true) - May query the server if entity is not cached (I/O operation).
• GetEntity(guid, query: false) - Returns only from cache, returns null if not cached.

The engine thread

Every plugin has a dedicated engine thread where entity operations are performed. This thread:

• Executes lifecycle methods OnPluginLoaded and OnPluginStart.
• Processes entity updates and transactions.
• Does not have a System.Threading.SynchronizationContext.

In a plugin, EventReceived and ActionReceived handlers run on the engine thread. Engine.IsEngineThread returns true inside these handlers, so you can create, update, or delete entities directly from them without calling QueueUpdate. Callbacks that originate on other threads, such as System.Timers.Timer elapsed handlers, Task continuations, and ThreadPool work items, do not run on the engine thread; marshal entity writes from those with QueueUpdate or QueueUpdateAndWait.

Engine thread constraints

• Avoid blocking I/O operations (network calls, file operations, database queries).
• Avoid long-running computations.
• Use only for entity operations and configuration changes.
• Perform I/O and heavy processing on background threads.

Warning

If the engine thread is blocked for too long, Security Center will detect the plugin as unresponsive and terminate the GenetecPlugin.exe process. Keep engine thread operations brief.

QueueUpdate methods

Use these methods to marshal work from external threads to the engine thread.

Method	Behavior	Returns
QueueUpdate(Action)	Queues action to engine thread, returns immediately	IAsyncResult
QueueUpdateAndWait(Action)	Queues action and blocks until completed	IAsyncResult

QueueUpdate (Fire-and-Forget)

Use QueueUpdate when you do not need to wait for the result:

// Example: Timer callback runs on a ThreadPool thread
private void OnTimerElapsed(object sender, ElapsedEventArgs e)
{
    // Queue to engine thread - returns immediately
    Engine.QueueUpdate(() =>
    {
        var entity = Engine.GetEntity<CustomEntity>(m_entityGuid);
        entity.RunningState = State.Running;
    });

    // Execution continues immediately without waiting
}

QueueUpdateAndWait (Synchronous)

Use QueueUpdateAndWait when you need to wait for a write operation to complete before continuing:

// Example: External thread needs to update an entity and confirm success
private bool TryUpdateEntityState(Guid entityGuid, State newState)
{
    bool success = false;

    Engine.QueueUpdateAndWait(() =>
    {
        try
        {
            var entity = Engine.GetEntity<CustomEntity>(entityGuid);
            entity.RunningState = newState;
            success = true;
        }
        catch (Exception ex)
        {
            Logger.TraceError(ex, "Failed to update entity state");
        }
    });

    return success;
}

Checking thread context

Use the IsEngineThread property to determine if the current thread is the engine thread:

private void ProcessData(ExternalData data)
{
    if (Engine.IsEngineThread)
    {
        // Already on engine thread - safe to modify entities
        UpdateEntity(data);
    }
    else
    {
        // On external thread - must queue write operations to engine thread
        Engine.QueueUpdate(() => UpdateEntity(data));
    }
}

This check is required before code creates, updates, or deletes entities, and before it starts a transaction. If Engine.IsEngineThread is true, use the synchronous TransactionManager.ExecuteTransaction method; do not call TransactionManager.ExecuteTransactionAsync from the engine thread. Entity cache reads with GetEntity(guid, query: false) are thread-safe and do not require queueing. However, GetEntity(guid) with default behavior may trigger server I/O if the entity is not cached.

Exception handling

Since QueueUpdate returns immediately without waiting, exceptions thrown inside the queued action do not propagate to the calling code. Handle exceptions within the action itself:

Engine.QueueUpdate(() =>
{
    try
    {
        var entity = Engine.GetEntity<CustomEntity>(entityGuid);
        entity.RunningState = State.Running;
    }
    catch (Exception ex)
    {
        Logger.TraceError(ex, "Failed to update entity");
    }
});

Since QueueUpdateAndWait waits for completion, exceptions propagate to the caller:

try
{
    Engine.QueueUpdateAndWait(() =>
    {
        var entity = Engine.GetEntity<CustomEntity>(entityGuid);
        entity.RunningState = State.Running;
    });
}
catch (SdkException ex)
{
    Logger.TraceError(ex, "Operation failed");
}

Async/await considerations

The engine thread does not have a System.Threading.SynchronizationContext. This means that after an await, the continuation will not return to the engine thread automatically.

// WRONG - continuation runs on thread pool, not engine thread
private async void OnPluginLoaded()
{
    var data = await ExternalApi.GetDataAsync();
    ProcessData(data); // Runs on wrong thread!
}

// CORRECT - queue entity updates back to engine thread
protected override void OnPluginLoaded()
{
    Task.Run(async () =>
    {
        var data = await ExternalApi.GetDataAsync();
        Engine.QueueUpdate(() => ProcessData(data));
    });
}

See also

• Plugin SDK lifecycle: Plugin initialization, startup, and disposal phases.
• Plugin SDK events: Subscribing to events from a plugin role.
• Plugin SDK request manager: Request and response communication between plugin and config pages.
• About transactions: Batching multiple entity operations into one request.