Implementation:CARLA simulator Carla ThreadPool

Knowledge Sources	CARLA
Domains	Concurrency, Infrastructure
Last Updated	2026-02-15 05:00 GMT

Overview

ThreadPool is a Boost.Asio-based thread pool that provides asynchronous task execution with support for both synchronous blocking and timed execution modes.

Description

The ThreadPool class in the carla namespace wraps a boost::asio::io_context with a ThreadGroup to provide a general-purpose thread pool. It inherits from NonCopyable.

Internal structure:

• _io_context: The Boost.Asio I/O context that drives the event loop and task scheduling
• _work_to_do: A boost::asio::io_context::work guard object that prevents the io_context from stopping when no tasks are queued (ensures the pool stays alive until explicitly stopped)
• _workers: A ThreadGroup that manages the pool's worker threads

Key methods:

• io_context(): Returns a reference to the underlying boost::asio::io_context, allowing direct posting of work or integration with Boost.Asio networking operations.

• Post(functor): Posts a task to the pool using boost::asio::post wrapped in a std::packaged_task. Returns a std::future<ResultT> where ResultT is deduced from the functor's return type using std::invoke_result_t. The functor is wrapped in a carla::MoveHandler to support move-only callables.

• AsyncRun(size_t worker_threads): Creates the specified number of worker threads, each running _io_context.run(). An overload without arguments uses std::thread::hardware_concurrency() for the thread count.

• Run(): Blocks the calling thread and runs the io_context event loop synchronously.

• RunFor(time_duration): Runs the io_context for a specific duration, then returns. Uses _io_context.run_for with chrono conversion.

• Stop(): Stops the io_context (breaking out of any Run calls) and joins all worker threads.

The destructor calls Stop() to ensure clean shutdown.

Usage

ThreadPool is used throughout CARLA's infrastructure as the I/O and task execution backbone. It powers the streaming::Client, streaming::Server, multigpu::Router, and multigpu::Secondary classes, providing both network I/O context and general-purpose task scheduling.

Code Reference

Source Location

• Repository: CARLA
• File: LibCarla/source/carla/ThreadPool.h

Signature

class ThreadPool : private NonCopyable {
public:
    ThreadPool();
    ~ThreadPool();

    auto &io_context();

    template <typename FunctorT,
              typename ResultT = std::invoke_result_t<FunctorT()>>
    std::future<ResultT> Post(FunctorT &&functor);

    void AsyncRun(size_t worker_threads);
    void AsyncRun();  // uses hardware_concurrency

    void Run();
    void RunFor(time_duration duration);
    void Stop();
};

Import

#include "carla/ThreadPool.h"

I/O Contract

Inputs

Name	Type	Required	Description
functor	FunctorT&&	Yes (Post)	Callable task to execute on the thread pool
worker_threads	size_t	No (AsyncRun)	Number of worker threads (defaults to hardware concurrency)
duration	time_duration	Yes (RunFor)	Maximum duration to run the event loop

Outputs

Name	Type	Description
Post()	std::future<ResultT>	Future for the task's return value
io_context()	boost::asio::io_context&	Reference to the underlying I/O context for direct integration

Usage Examples

carla::ThreadPool pool;

// Run with 4 worker threads
pool.AsyncRun(4);

// Post a task and get a future
auto future = pool.Post([]() -> int {
    // Perform computation
    return 42;
});
int result = future.get();  // blocks until task completes

// Use io_context for Boost.Asio networking
boost::asio::ip::tcp::socket socket(pool.io_context());

// Run synchronously for a limited duration
pool.RunFor(carla::time_duration::seconds(5));

// Clean shutdown
pool.Stop();

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• CARLA_simulator_Carla_StreamingClient
• CARLA_simulator_Carla_StreamingServer
• CARLA_simulator_Carla_MultiGPU_Router
• CARLA_simulator_Carla_MultiGPU_Secondary