FastQueue

A high-performance, production-ready C/C++ job system and thread pool library (C99 and later).

Documentation | API Reference | Quick Start | Contributing

FastQueue is a modern, high-performance C/C++ library providing work-stealing thread pools, MPMC task queues, futures, and custom allocator support for building high-performance concurrent applications. Compatible with C99, C11, C17, C23, and C++.

Tip

If you build with FastQueue, make sure to give it a star.

Note

Cross-platform: FastQueue supports Linux (GCC, Clang), Windows (MSVC 2015+), and macOS (Clang) with zero external dependencies. C99 or later required, C++ fully supported.

---

Features (click to expand)

Feature	Description	Documentation
Thread Pool	Built-in work-stealing thread pool with configurable worker count and automatic load balancing.	https://muhammad-fiaz.github.io/FastQueue/api/thread_pool
Job Scheduler	Low-level scheduler with priority support, work stealing, and statistics tracking.	https://muhammad-fiaz.github.io/FastQueue/api/scheduler
MPMC Queue	Thread-safe multi-producer multi-consumer queue with mutex-protected push/pop/try_pop operations.	https://muhammad-fiaz.github.io/FastQueue/api/queue
Futures	Awaitable results with spin-then-wait strategy and completion callbacks.	https://muhammad-fiaz.github.io/FastQueue/api/future
Parallel For	Built-in parallel for-loop that distributes work across worker threads.	https://muhammad-fiaz.github.io/FastQueue/api/parallel
Time Utilities	High-resolution timer and monotonic clock for performance measurement.	https://muhammad-fiaz.github.io/FastQueue/api/time
Custom Allocators	Pluggable allocator interface for memory-constrained and embedded environments.	https://muhammad-fiaz.github.io/FastQueue/guide/memory
Cross-Platform	Runs on Linux, Windows (MSVC), and macOS with no external dependencies.	https://muhammad-fiaz.github.io/FastQueue/guide/installation
C99/C11/C17/C23	Compatible with all modern C standards. C++ ready with extern "C" guards.	https://muhammad-fiaz.github.io/FastQueue/guide/installation
C++ Compatible	All headers have extern "C" guards for direct use in C++ projects.	https://muhammad-fiaz.github.io/FastQueue/api/overview
Zero Dependencies	Uses only the C standard library and platform APIs.	https://muhammad-fiaz.github.io/FastQueue/guide/installation
Work Stealing	Configurable work-stealing: idle workers steal from busy workers, or disable for pinned assignment.	https://muhammad-fiaz.github.io/FastQueue/guide/scheduler
Priority Scheduling	High/urgent priority tasks routed to global queue for fastest pickup.	https://muhammad-fiaz.github.io/FastQueue/api/scheduler
Task Cancellation	Cancel pending tasks before execution; futures auto-cancel on task destroy.	https://muhammad-fiaz.github.io/FastQueue/api/task
Sanitizer Support	Built-in support for AddressSanitizer, UBSan, and ThreadSanitizer.	https://muhammad-fiaz.github.io/FastQueue/guide/installation
Package Managers	Supports CMake, xmake, Conan, and vcpkg package managers.	https://muhammad-fiaz.github.io/FastQueue/guide/installation

---

Prerequisites and Supported Platforms (click to expand)

Prerequisites

Before using FastQueue, ensure you have the following:

Requirement	Version	Notes
C Compiler	C99 or later (GCC 4.8+, Clang 3.0+, MSVC 2015+)	Supports C99, C11, C17, C23
CMake	3.20+	Build system
pthreads	Linux/macOS only	POSIX threads
Win32 API	Windows only	Thread primitives

---

Supported Platforms

FastQueue is validated on these architectures:

Platform	x86_64 (64-bit)	aarch64 (ARM64)
Linux	Yes	Yes
Windows	Yes	Yes
macOS	Yes	Yes (Apple Silicon)

---

Installation

Method 1: CMake (FetchContent)

include(FetchContent)
FetchContent_Declare(FastQueue
    GIT_REPOSITORY https://github.com/muhammad-fiaz/FastQueue.git
    GIT_TAG main)
FetchContent_MakeAvailable(FastQueue)
target_link_libraries(your_target PRIVATE FastQueue::fastqueue)

Method 2: CMake (Subdirectory)

git clone https://github.com/muhammad-fiaz/FastQueue.git

add_subdirectory(FastQueue)
target_link_libraries(your_target PRIVATE FastQueue::fastqueue)

Method 3: xmake

add_requires("fastqueue")
target("myapp")
    set_kind("binary")
    add_files("src/main.c")
    add_packages("fastqueue")

Method 4: Conan

[requires]
fastqueue/0.1.0

Method 5: vcpkg

vcpkg install fastqueue

Method 6: Build from Source

git clone https://github.com/muhammad-fiaz/FastQueue.git
cd FastQueue
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
cmake --install build

Quick Start

Thread Pool

#include <fastqueue/fastqueue.h>
#include <stdio.h>

static void my_task(void *arg) {
    printf("Task %d executed\n", *(int *)arg);
}

int main(void) {
    fq_thread_pool_t *pool = NULL;
    fq_thread_pool_create_ex(&pool, 4);

    for (int i = 0; i < 100; ++i) {
        int *id = malloc(sizeof(int));
        *id = i;
        fq_thread_pool_submit_fn(pool, my_task, id);
    }

    fq_thread_pool_wait_idle(pool);
    fq_thread_pool_shutdown(pool);
    return 0;
}

Scheduler with Futures

#include <fastqueue/fastqueue.h>
#include <stdio.h>

static void compute(void *arg) {
    long *result = (long *)arg;
    *result = (*result) * (*result);
}

int main(void) {
    fq_scheduler_t *scheduler = NULL;
    fq_scheduler_config_t cfg;
    fq_scheduler_config_default(&cfg);
    cfg.thread_count = 4;
    fq_scheduler_create(&scheduler, &cfg);

    long value = 42;
    fq_task_t *task = NULL;
    fq_future_t *future = NULL;
    fq_task_create(&task, compute, &value, NULL);
    fq_scheduler_submit_with_future(scheduler, task, &future);

    fq_future_wait(future);
    printf("42 squared = %ld\n", value);

    fq_future_destroy(future);
    fq_scheduler_shutdown(scheduler);
    return 0;
}

C++ Usage

#include <fastqueue/fastqueue.h>
#include <cstdio>

int main() {
    fq_thread_pool_t *pool = nullptr;
    fq_thread_pool_create_ex(&pool, 4);

    for (int i = 0; i < 50; ++i) {
        int *id = new int(i);
        fq_thread_pool_submit_fn(pool, [](void *arg) {
            std::printf("Task %d\n", *static_cast<int *>(arg));
        }, id);
    }

    fq_thread_pool_wait_idle(pool);
    fq_thread_pool_shutdown(pool);
    return 0;
}

Examples

The examples/ directory contains 6 comprehensive, runnable examples demonstrating all features:

Example	Description	Documentation
basic_jobs	Submit and execute tasks with thread pool	https://muhammad-fiaz.github.io/FastQueue/examples/basic-jobs
futures	Awaitable task results	https://muhammad-fiaz.github.io/FastQueue/examples/futures
parallel_for	Parallel data processing	https://muhammad-fiaz.github.io/FastQueue/examples/parallel-for
custom_allocator	Pluggable allocator interface	https://muhammad-fiaz.github.io/FastQueue/examples/custom-allocator
graceful_shutdown	Clean shutdown patterns	https://muhammad-fiaz.github.io/FastQueue/examples/graceful-shutdown
error_handling	Error handling best practices	https://muhammad-fiaz.github.io/FastQueue/examples/error-handling

To run any example:

cmake -B build -DFQ_BUILD_EXAMPLES=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
./build/examples/Release/fq_example_basic_jobs

Build Options

Option	Default	Description
FQ_BUILD_TESTS	OFF	Build unit tests
FQ_BUILD_EXAMPLES	OFF	Build examples
FQ_BUILD_BENCHMARKS	OFF	Build benchmarks
FQ_SHARED	OFF	Build shared library
FQ_ENABLE_ASAN	OFF	AddressSanitizer
FQ_ENABLE_UBSAN	OFF	UndefinedBehaviorSanitizer
FQ_ENABLE_TSAN	OFF	ThreadSanitizer

Performance

Run benchmarks:

cmake -B build -DFQ_BUILD_BENCHMARKS=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
./build/benchmarks/Release/fq_benchmark

Benchmark Results

Average throughput across multiple runs:

Configuration	Jobs	Throughput
1 thread, 10K jobs	10,000	~1.4M jobs/s
2 threads, 10K jobs	10,000	~1.1M jobs/s
4 threads, 10K jobs	10,000	~1.3M jobs/s
4 threads, 100K jobs	100,000	~1.0M jobs/s
4 threads, 1M jobs	1,000,000	~1.0M jobs/s

Testing

Run the full test suite (38 tests):

cmake -B build -DFQ_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug
ctest --test-dir build --output-on-failure

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.