ktsu.Invoker 1.5.1

ktsu.Invoker

A .NET library that ensures delegates are executed on the intended thread, simplifying thread management in UI and graphics applications.

Introduction

Invoker is a .NET library that provides methods to ensure delegates are executed on the intended thread. It is designed to simplify task execution and thread management in .NET applications where delegates are required to run within a specific context, such as the UI thread in WPF or WinForms applications, or the window thread in OpenGL or DirectX applications.

Features

• Thread-Safe Execution: Ensure delegates run on the intended thread
• Synchronous & Asynchronous Support: Both blocking and non-blocking invocation patterns
• Return Value Support: Easily retrieve results from cross-thread operations
• Immediate Execution: Auto-detect if already on the target thread for optimal performance
• Queue Management: Built-in task queue with controlled execution timing
• Thread Ownership: Clear ownership model for execution contexts
• Exception Propagation: Invoke/InvokeAsync rethrow a delegate's exception to its own caller; a throwing TryBeginInvoke action is reported through the BeginInvokeFailed event (or an AggregateException from DoInvokes when nothing handles it) without stopping the rest of the queue, whichever thread called TryBeginInvoke
• Lightweight Design: Minimal overhead for performance-critical applications

Installation

Package Manager Console

Install-Package ktsu.Invoker

.NET CLI

dotnet add package ktsu.Invoker

Package Reference

<PackageReference Include="ktsu.Invoker" Version="x.y.z" />

Usage Examples

Basic Example

// Initialize an instance on the owning thread
var invoker = new Invoker();

// Queue a task from a different thread, which blocks until the delegate has been executed via DoInvokes() on the owning thread
invoker.Invoke(() => Console.WriteLine("Hello, World!"));

// Call DoInvokes() on the owning thread to execute queued tasks
invoker.DoInvokes();

// NOTE: If you queue from the owning thread the delegate will be executed immediately, bypassing DoInvokes()

// Delegates with return values are supported
string result = invoker.Invoke(() => "Hello, World!");

WPF UI Thread Example

using System.Windows;
using ktsu.Invoker;

public partial class MainWindow : Window
{
    private readonly Invoker _invoker = new Invoker();
    
    public MainWindow()
    {
        InitializeComponent();
        
        // Start a background operation
        Task.Run(() => BackgroundOperation());
    }
    
    private async Task BackgroundOperation()
    {
        // Simulate work
        await Task.Delay(1000);
        
        // Update UI from background thread safely
        _invoker.Invoke(() => {
            StatusTextBlock.Text = "Operation Completed!";
            ResultListBox.Items.Add("Background task result");
        });
    }
    
    // Call this in your UI event loop or dispatcher
    private void ProcessEvents()
    {
        _invoker.DoInvokes();
    }
}

Asynchronous Invocation

using ktsu.Invoker;

// Create invoker on the main thread
var invoker = new Invoker();

// From background thread
Task background = Task.Run(async () => {
    // Queue task and continue without waiting. TryBeginInvoke returns false, and drops the
    // action, if the bounded queue is full.
    if (!invoker.TryBeginInvoke(() => Console.WriteLine("Processing in the background")))
    {
        Console.WriteLine("Queue full, message dropped");
    }
    
    // Queue task and get Task for completion
    Task<string> resultTask = invoker.InvokeAsync(() => "Result from main thread");
    
    // Await the result
    string result = await resultTask;
    Console.WriteLine($"Got result: {result}");
});

// On main thread, keep executing pending operations until the background work is done.
// Awaiting the background task first would hang: its InvokeAsync waits for a DoInvokes call.
while (!background.IsCompleted)
{
    invoker.DoInvokes();
}

Game Loop Integration

using ktsu.Invoker;

public class Game
{
    private readonly Invoker _invoker = new Invoker();
    
    public void Run()
    {
        // Start rendering on the main thread
        while (true)
        {
            // Execute any queued operations from other threads
            _invoker.DoInvokes();
            
            // Perform rendering
            Render();
            
            // Process events, etc.
        }
    }
    
    private void Render() 
    {
        // OpenGL/DirectX rendering code here
    }
    
    // Call this from other threads
    public void QueueTextureLoad(string texturePath)
    {
        // OpenGL/DirectX resources often need to be created on the main thread.
        // TryBeginInvoke returns false, and drops the action, if the bounded queue is full.
        if (!_invoker.TryBeginInvoke(() => LoadTextureOnMainThread(texturePath)))
        {
            // Retry next frame, or fall back to the awaitable InvokeAsync
        }
    }
    
    private void LoadTextureOnMainThread(string texturePath)
    {
        // Load texture using OpenGL/DirectX APIs
    }
}

API Reference

Invoker Class

The main class that manages execution of delegates on the intended thread.

Methods

Events

Advanced Usage

Thread Synchronization

Invoker provides a clean way to synchronize access to resources that must be accessed from a specific thread:

public class ResourceManager
{
    private readonly Invoker _invoker = new Invoker();
    private readonly Dictionary<string, Resource> _resources = new Dictionary<string, Resource>();
    
    // This method can be called from any thread
    public Resource GetResource(string id)
    {
        return _invoker.Invoke(() => {
            if (!_resources.TryGetValue(id, out var resource))
            {
                resource = new Resource(id);
                _resources[id] = resource;
            }
            return resource;
        });
    }
    
    // Call this regularly on the owner thread
    public void Update()
    {
        _invoker.DoInvokes(); // Process any pending resource requests
        
        // Update resources
        foreach (var resource in _resources.Values)
        {
            resource.Update();
        }
    }
}

Choosing the Owner Thread and Queue Capacity

The thread that constructs an Invoker owns it, and that can't be changed later. To own it from a different thread, such as a dedicated render thread, construct it on that thread. The optional constructor argument sets the capacity of the non-blocking TryBeginInvoke queue (default 1024, rounded up to the next power of two):

Invoker? renderInvoker = null;

Thread renderThread = new(() =>
{
    // This thread now owns the invoker, and is the one that must call DoInvokes()
    renderInvoker = new Invoker(beginInvokeCapacity: 4096);
    // ... render loop that calls renderInvoker.DoInvokes() each frame
});
renderThread.Start();

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure to update tests as appropriate and adhere to the existing coding style.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Acknowledgements

Special thanks to all contributors and the .NET community for their support.