Implementation:CARLA simulator Carla MultiGPU Primary

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

Overview

Primary represents a TCP server session with a connected secondary GPU server, handling bidirectional data exchange with timeout management and asynchronous read/write operations.

Description

The Primary class in carla::multigpu represents one active connection from the primary CARLA server to a secondary GPU rendering server. It inherits from std::enable_shared_from_this<Primary>, profiler::LifetimeProfiled (for debugging session lifetimes), and NonCopyable.

Each Primary instance maintains a unique session ID from a global atomic counter, a TCP socket, a deadline timer for timeout management, and an io_context::strand for serialized asynchronous operations. A BufferPool is used for efficient memory recycling during reads.

Key methods:

• Open(on_opened, on_closed, on_response): Initializes the session by disabling Nagle's algorithm (TCP_NODELAY) for improved synchronous-mode performance, stores the close and response callbacks, invokes the on_opened callback, and begins reading data.

• Write(message) and Write(text): Two overloads for sending data. The message-based overload sends a pre-built tcp::Message with proper buffer sequencing. The text-based overload sends a size-prefixed string by first writing the integer size, then the character data.

• ReadData(): Implements a two-phase asynchronous read protocol: first reads the message header to determine the incoming buffer size, then reads the full data payload. On success, the response callback is invoked and ReadData is called recursively for continuous reading. On header read failure, the session is closed.

• Close() and CloseNow(): Close posts a deferred close to the strand; CloseNow cancels the deadline timer, shuts down the socket, and invokes the on_closed callback.

• StartTimer(): Manages the inactivity deadline timer, closing the session if the deadline has passed.

Usage

Primary sessions are created by the Listener when secondary servers connect. They are managed by the Router which stores them in a session list and routes commands through them.

Code Reference

Source Location

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

Signature

class Primary
    : public std::enable_shared_from_this<Primary>,
      private profiler::LifetimeProfiled,
      private NonCopyable {
public:
    using socket_type = boost::asio::ip::tcp::socket;

    explicit Primary(boost::asio::io_context &io_context,
                     time_duration timeout, Listener &server);
    ~Primary();

    void Open(Listener::callback_function_type on_opened,
              Listener::callback_function_type on_closed,
              Listener::callback_function_type_response on_response);

    template <typename... Buffers>
    static auto MakeMessage(Buffers... buffers);

    void Write(std::shared_ptr<const tcp::Message> message);
    void Write(std::string text);
    void ReadData();

    template <typename... Buffers>
    void Write(Buffers... buffers);

    void Close();
};

Import

#include "carla/multigpu/primary.h"

I/O Contract

Inputs

Name	Type	Required	Description
io_context	boost::asio::io_context&	Yes	I/O context for asynchronous socket operations
timeout	time_duration	Yes	Inactivity timeout before session closure
server	Listener&	Yes	Reference to the parent listener
on_opened	callback_function_type	Yes	Called when the session is successfully opened
on_closed	callback_function_type	Yes	Called when the session is closed
on_response	callback_function_type_response	Yes	Called when data is received from the secondary
message	shared_ptr<const tcp::Message>	Yes (Write)	Pre-built message to send over TCP
text	std::string	Yes (Write text)	Text string to send as size-prefixed data

Outputs

Name	Type	Description
MakeMessage()	shared_ptr<const tcp::Message>	Constructs a TCP message from BufferView arguments
(callback invocations)	void	Session events and data delivered via stored callbacks

Usage Examples

// Primary sessions are typically created by the Listener, not directly
// The Router uses them to send commands to secondary servers:

// Build a message from buffer views
auto view_header = BufferView::CreateFrom(std::move(headerBuf));
auto view_data = BufferView::CreateFrom(std::move(dataBuf));
auto message = Primary::MakeMessage(view_header, view_data);

// Write to a specific session
session->Write(message);

// Write a text command
session->Write("load_map Town01");

// Close the session
session->Close();

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• CARLA_simulator_Carla_MultiGPU_Listener
• CARLA_simulator_Carla_MultiGPU_Router
• CARLA_simulator_Carla_BufferPool
• CARLA_simulator_Carla_BufferView