Skip to main content
The transport layer handles message serialization, inproc delivery, and network routing. You interact with it primarily through Publisher and Subscriber handles returned by Unit::Advertise() / Unit::Subscribe(), or directly through TransportManager when building lower-level components.
All types live in the basis::core::transport namespace unless noted otherwise. Header paths are relative to cpp/core/transport/include/.

​
Publisher<T_MSG, T_CONVERTABLE_INPROC>

basis/core/transport/publisher.h A typed handle for publishing messages on a topic. Owns serialization callbacks and delegates to one or more underlying TransportPublisher instances (e.g. TCP) plus an optional inproc channel.
Publishers are [[nodiscard]] — always store the returned shared_ptr. Dropping it destroys the publisher and tears down the topic.

​
Template parameters

​
T_MSG
typename
required
The primary message type. Must be serializable via T_Serializer.
​
T_CONVERTABLE_INPROC
typename
default:"NoAdditionalInproc"
An optional secondary inproc-only type. When set, callers may also publish std::shared_ptr<const T_CONVERTABLE_INPROC> directly; the publisher converts it to T_MSG before network delivery.

​
Publish (primary message)

virtual void Publish(std::shared_ptr<const T_MSG> msg)
Publishes msg to all subscribers. The message is:
  1. Delivered directly (zero-copy) to inproc subscribers.
  2. Serialized and sent over all registered network transports if any transport subscribers exist.
  3. Written to the recorder if one is attached and the topic matches its filter.
​
msg
std::shared_ptr<const T_MSG>
required
The message to publish. Ownership is shared; inproc subscribers receive the same pointer.

​
Publish (convertable inproc type)

virtual void Publish(std::shared_ptr<const T_CONVERTABLE_INPROC> msg)
Only available when T_CONVERTABLE_INPROC != NoAdditionalInproc. Sends msg over the additional inproc channel immediately, then calls ConvertToMessage<T_MSG>(msg) and routes the result through the primary path if any transport or primary inproc subscribers are present.

​
PublishRaw (base class)

void PublishRaw(std::shared_ptr<MessagePacket> packet, basis::core::MonotonicTime now)
Protected helper on PublisherBase. Sends a pre-serialized MessagePacket to all transport publishers and, when a recorder is attached, writes the packet payload to disk.

​
SetMaxQueueSize

void SetMaxQueueSize(size_t max_queue_size)
Sets the maximum outgoing queue depth on every underlying transport publisher.
​
max_queue_size
size_t
required
Maximum number of serialized packets that may be queued per transport before back-pressure is applied.

​
GetTransportSubscriberCount

size_t GetTransportSubscriberCount()
Returns the total number of active network subscribers across all transports. Does not count inproc subscribers.

​
PublisherRaw

basis/core/transport/publisher.h A non-templated publisher that accepts pre-serialized MessagePacket objects. Useful when the serialized form is produced externally (e.g. during replay). 
class PublisherRaw : public PublisherBase {
public:
  PublisherRaw(std::string_view topic,
               serialization::MessageTypeInfo type_info,
               std::vector<std::shared_ptr<TransportPublisher>> transport_publishers,
               RecorderInterface* recorder);

  using PublisherBase::PublishRaw;
};

​
SubscriberCallback<T_MSG>

basis/core/transport/subscriber.h Type alias for the callback signature used by all typed subscribers. 
template <typename T_MSG>
using SubscriberCallback = std::function<void(std::shared_ptr<const T_MSG>)>;

​
Subscriber<T_MSG, T_ADDITIONAL_INPROC>

basis/core/transport/subscriber.h A typed subscriber handle. Created by TransportManager::Subscribe() or Unit::Subscribe(). Holds inproc channel subscriptions and a list of underlying TransportSubscriber objects for network transports.

​
Template parameters

​
T_MSG
typename
required
Primary message type. Callbacks receive std::shared_ptr<const T_MSG>.
​
T_ADDITIONAL_INPROC
typename
default:"NoAdditionalInproc"
Optional secondary inproc type. When set, a second callback fires with std::shared_ptr<const T_ADDITIONAL_INPROC> for messages delivered over the additional inproc channel.

​
Public members

​
MessageType
type alias
using MessageType = T_MSG. Convenience alias for the primary message type.

​
Inherited from SubscriberBase

void HandlePublisherInfo(const std::vector<PublisherInfo>& info)
Called by TransportManager when the coordinator reports new publishers. Routes each publisher to the appropriate transport. 
size_t GetPublisherCount()
Returns the number of publishers currently connected across all transports.

​
RateSubscriber

basis/core/transport/subscriber.h A timer-based trigger that fires a callback at a fixed rate, independent of any topic. Commonly used to implement periodic handlers in generated unit code.

​
Constructor

RateSubscriber(const Duration& tick_length,
               std::function<void(MonotonicTime)> callback)
Creates the subscriber and immediately starts the background thread.
​
tick_length
const Duration&
required
Period between invocations. The timer fires approximately every tick_length nanoseconds of monotonic time.
​
callback
std::function<void(MonotonicTime)>
required
Called on each tick with the current MonotonicTime. Runs on the rate subscriber’s internal thread.
The callback runs on a private background thread. If it accesses shared state, synchronize externally or use SingleThreadedUnit’s queue.

​
Start / Stop

void Start()
void Stop()
Start() is called automatically by the constructor. Stop() joins the internal thread and is called by the destructor. 
// 10 Hz timer
basis::core::transport::RateSubscriber rate{
    basis::core::Duration::FromSeconds(0.1),
    [](basis::core::MonotonicTime now) {
        // runs every ~100ms
    }
};

​
TransportManager

basis/core/transport/transport_manager.h Central coordinator for publishers and subscribers within a single process. Creates typed publish/subscribe handles, routes inproc messages, and aggregates publisher metadata for the coordinator.

​
Constructor

TransportManager(std::unique_ptr<InprocTransport> inproc = nullptr)
​
inproc
std::unique_ptr<InprocTransport>
default:"nullptr"
Optional inproc transport. When provided, messages published on a topic are delivered zero-copy to subscribers in the same process.
template <typename T_MSG,
          typename T_Serializer = SerializationHandler<T_MSG>::type,
          typename T_CONVERTABLE_INPROC = NoAdditionalInproc>
[[nodiscard]] std::shared_ptr<Publisher<T_MSG, T_CONVERTABLE_INPROC>>
Advertise(
    std::string_view topic,
    const serialization::MessageTypeInfo& message_type =
        T_Serializer::template DeduceMessageTypeInfo<T_MSG>())
Creates a typed Publisher. Registers the message schema, sets up inproc and network transport publishers, and optionally attaches the recorder.
​
T_MSG
typename
required
Message type to publish.
​
T_Serializer
typename
default:"SerializationHandler<T_MSG>::type"
Serializer for T_MSG.
​
T_CONVERTABLE_INPROC
typename
default:"NoAdditionalInproc"
Secondary inproc type, if any.
​
topic
std::string_view
required
Topic name.
​
message_type
const serialization::MessageTypeInfo&
Type metadata. Deduced when omitted.

​
AdvertiseRaw

std::shared_ptr<PublisherRaw>
AdvertiseRaw(std::string_view topic,
             const serialization::MessageTypeInfo& message_type,
             const serialization::MessageSchema& schema)
Creates a raw (non-typed) publisher. Used by the replayer to retransmit recorded messages without deserializing them.

​
Subscribe

template <typename T_MSG,
          typename T_Serializer = SerializationHandler<T_MSG>::type,
          typename T_ADDITIONAL_INPROC = NoAdditionalInproc>
[[nodiscard]] std::shared_ptr<Subscriber<T_MSG, T_ADDITIONAL_INPROC>>
Subscribe(
    std::string_view topic,
    SubscriberCallback<T_MSG> callback,
    basis::core::threading::ThreadPool* work_thread_pool,
    std::shared_ptr<basis::core::containers::SubscriberQueue> output_queue = nullptr,
    serialization::MessageTypeInfo message_type =
        T_Serializer::template DeduceMessageTypeInfo<T_MSG>(),
    SubscriberCallback<T_ADDITIONAL_INPROC> additional_callback = {})
Creates a typed subscriber with a std::function callback. Internally calls SubscribeCallable.
​
topic
std::string_view
required
Topic to subscribe to.
​
callback
SubscriberCallback<T_MSG>
required
Invoked with each received std::shared_ptr<const T_MSG>.
​
work_thread_pool
basis::core::threading::ThreadPool*
required
Thread pool for deserializing and dispatching callbacks from network transports.
​
output_queue
std::shared_ptr<basis::core::containers::SubscriberQueue>
default:"nullptr"
When set, callbacks are posted to this queue instead of being called directly. Enables serialized delivery in SingleThreadedUnit.
​
message_type
serialization::MessageTypeInfo
Type metadata. Deduced when omitted.
​
additional_callback
SubscriberCallback<T_ADDITIONAL_INPROC>
default:"{}"
Callback for the secondary inproc type, if any.

​
SubscribeCallable

template <typename T_MSG,
          typename T_Serializer = SerializationHandler<T_MSG>::type,
          typename T_ADDITIONAL_INPROC = NoAdditionalInproc>
[[nodiscard]] std::shared_ptr<Subscriber<T_MSG, T_ADDITIONAL_INPROC>>
SubscribeCallable(
    std::string_view topic,
    auto callback,
    basis::core::threading::ThreadPool* work_thread_pool,
    std::shared_ptr<basis::core::containers::SubscriberQueue> output_queue = nullptr,
    serialization::MessageTypeInfo message_type =
        T_Serializer::template DeduceMessageTypeInfo<T_MSG>(),
    SubscriberCallback<T_ADDITIONAL_INPROC> additional_callback = {})
Like Subscribe but accepts any callable (lambda, function pointer, etc.), which avoids the overhead of std::function construction. T_MSG must be specified explicitly.

​
SubscribeRaw

[[nodiscard]] std::shared_ptr<SubscriberBase>
SubscribeRaw(
    std::string_view topic,
    TypeErasedSubscriberCallback callback,
    basis::core::threading::ThreadPool* work_thread_pool,
    std::shared_ptr<basis::core::containers::SubscriberQueue> output_queue,
    serialization::MessageTypeInfo message_type)
Does not subscribe to inproc messages — inproc messages are not serialized, so they are invisible to raw subscribers.

​
RegisterTransport

void RegisterTransport(std::string_view transport_name,
                       std::unique_ptr<Transport> transport)
Registers a named network transport (e.g. TCP). All subsequent Advertise and Subscribe calls will include this transport.

​
Update

void Update()
Pumps all registered transports and rebuilds the publisher summary used by GetLastPublisherInfo(). Called by StandardUpdate() on every unit tick.

​
SetRecorder

void SetRecorder(basis::RecorderInterface* recorder)
Attaches a recorder. Must be called before any Advertise calls and only once.
​
recorder
basis::RecorderInterface*
required
Recorder that will receive serialized message payloads.

​
HandleNetworkInfo

void HandleNetworkInfo(const proto::NetworkInfo& network_info)
Called by the coordinator connector when new network topology arrives. Routes publisher info to the matching subscribers so they can connect over the appropriate transport.

​
CoordinatorConnector

basis/core/coordinator/include/basis/core/coordinator_connector.h Maintains a TCP connection to the Basis coordinator process and handles topology updates (publisher discovery) and schema registration.

​
Factory: Create

static std::unique_ptr<CoordinatorConnector>
Create(uint16_t port = BASIS_PUBLISH_INFO_PORT)
Attempts a non-blocking TCP connection to 127.0.0.1 on port. Returns nullptr if the coordinator is not yet available.
​
port
uint16_t
default:"BASIS_PUBLISH_INFO_PORT"
Port the coordinator is listening on. Uses the compile-time default when omitted.
// Retry until connected (use Unit::WaitForCoordinatorConnection() for units)
std::unique_ptr<basis::core::transport::CoordinatorConnector> cc;
while (!cc) {
    cc = basis::core::transport::CoordinatorConnector::Create();
}

​
Update

void Update()
Reads any pending messages from the coordinator socket and updates internal state (last_network_info, network_schemas, errors_from_coordinator). Call this on every tick.

​
SendTransportManagerInfo

void SendTransportManagerInfo(const proto::TransportManagerInfo& info)
Sends the local process’s current publisher list to the coordinator so other processes can discover it.

​
SendSchemas

void SendSchemas(const std::vector<basis::core::serialization::MessageSchema>& schemas)
Registers message schemas with the coordinator for introspection and tooling.

​
GetLastNetworkInfo

proto::NetworkInfo* GetLastNetworkInfo()
Returns the most recent network topology received from the coordinator, or nullptr if none has arrived yet.

​
Free function: WaitForCoordinator

std::unique_ptr<basis::core::transport::CoordinatorConnector> WaitForCoordinator()
Blocks, retrying every second, until CoordinatorConnector::Create() succeeds. Equivalent to the loop inside Unit::WaitForCoordinatorConnection().

Build docs developers (and LLMs) love

Get started for freeTalk to us