Implementation:CARLA simulator Carla MultiGPU Router

Knowledge Sources	CARLA
Domains	MultiGPU, Networking
Last Updated	2026-02-15 05:00 GMT

Overview

Router is the central coordinator for multi-GPU communication, managing TCP connections to secondary GPU servers and routing commands and data between the primary server and all connected secondaries.

Description

The Router class in carla::multigpu manages the lifecycle of connections to secondary GPU server processes. It inherits from std::enable_shared_from_this<Router> and maintains a list of active Primary sessions, a Listener for accepting connections, a ThreadPool for asynchronous I/O, and a PrimaryCommands instance for high-level command dispatching.

Construction and setup:

The constructor accepts a port number and creates a TCP endpoint bound to 0.0.0.0. SetCallbacks() must be called after construction (requiring shared_from_this) to configure the Listener with session open/close/response handlers. The open handler calls ConnectSession, the close handler calls DisconnectSession, and the response handler resolves pending promises from the _promises map.

Session management:

• ConnectSession: Adds a Primary session to _sessions vector under mutex protection and optionally fires an external new-connection callback.
• DisconnectSession: Removes a session using erase-remove idiom.
• ClearSessions: Clears all sessions during shutdown.

Write methods:

• Write(id, buffer): Broadcasts a command (MultiGPUCommand) with a CommandHeader and data to all connected sessions.
• WriteToNext(id, buffer): Sends to the next session in round-robin order (using _next counter) and returns a std::future<SessionInfo> for the response. A promise is stored in _promises keyed by the raw Primary pointer.
• WriteToOne(server, id, buffer): Sends to a specific session (identified by weak_ptr<Primary>) and returns a future for the response.

Round-robin selection:

GetNextServer() returns a weak_ptr<Primary> to the current next session without advancing the counter, allowing PrimaryCommands to track which server a sensor was activated on.

Stop() clears all sessions, stops the listener, and shuts down the thread pool.

Usage

The Router is created and managed by the CARLA server when multi-GPU rendering is enabled. It coordinates all communication with secondary rendering servers through its PrimaryCommands accessor (GetCommander()).

Code Reference

Source Location

• Repository: CARLA
• Files:
  • LibCarla/source/carla/multigpu/router.h
  • LibCarla/source/carla/multigpu/router.cpp

Signature

class Router : public std::enable_shared_from_this<Router> {
public:
    Router(void);
    explicit Router(uint16_t port);
    ~Router();

    void Write(MultiGPUCommand id, Buffer &&buffer);
    std::future<SessionInfo> WriteToNext(MultiGPUCommand id, Buffer &&buffer);
    std::future<SessionInfo> WriteToOne(std::weak_ptr<Primary> server,
                                         MultiGPUCommand id, Buffer &&buffer);
    void Stop();

    void SetCallbacks();
    void SetNewConnectionCallback(std::function<void(void)>);
    void AsyncRun(size_t worker_threads);

    boost::asio::ip::tcp::endpoint GetLocalEndpoint() const;
    bool HasClientsConnected();
    PrimaryCommands &GetCommander();
    std::weak_ptr<Primary> GetNextServer();
};

Import

#include "carla/multigpu/router.h"

I/O Contract

Inputs

Name	Type	Required	Description
port	uint16_t	Yes	TCP port to listen for secondary server connections
id	MultiGPUCommand	Yes (Write methods)	Command identifier for the message header
buffer	Buffer&&	Yes (Write methods)	Data payload to send with the command
server	std::weak_ptr<Primary>	Yes (WriteToOne)	Specific session to send to
worker_threads	size_t	Yes (AsyncRun)	Number of I/O worker threads

Outputs

Name	Type	Description
WriteToNext()	std::future<SessionInfo>	Future containing the response session and buffer
WriteToOne()	std::future<SessionInfo>	Future containing the targeted response session and buffer
GetCommander()	PrimaryCommands&	Reference to the high-level command interface
GetNextServer()	std::weak_ptr<Primary>	Weak pointer to the next secondary server in round-robin order
HasClientsConnected()	bool	Whether any secondary servers are currently connected
GetLocalEndpoint()	tcp::endpoint	The local TCP endpoint being listened on

Usage Examples

// Create and configure the router
auto router = std::make_shared<carla::multigpu::Router>(2002);
router->SetCallbacks();
router->AsyncRun(4);

// Set a callback for new connections
router->SetNewConnectionCallback([]() {
    log_info("New secondary server connected!");
});

// Broadcast frame data to all secondary servers
router->Write(MultiGPUCommand::SEND_FRAME, std::move(frameBuffer));

// Send a request to the next secondary and wait for response
auto future = router->WriteToNext(MultiGPUCommand::GET_TOKEN, std::move(requestBuffer));
auto response = future.get();  // blocks until response arrives

// Access the command layer
auto &commander = router->GetCommander();
auto token = commander.GetToken(sensorId);

// Shutdown
router->Stop();

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• CARLA_simulator_Carla_MultiGPU_Listener
• CARLA_simulator_Carla_MultiGPU_Primary
• CARLA_simulator_Carla_MultiGPU_PrimaryCommands
• CARLA_simulator_Carla_MultiGPU_Secondary