Tin DDS for C++

Tutorial 1 · about 20 minutes

Connect two processes through one topic

A participant is one application's membership in a DDS domain. It owns that application's topics, readers, writers, discovery state, histories, and status. Its runtime owns the sockets and protocol timers that connect those local objects to participants in other processes.

What exists in each process

Process A memory                       Process B memory
participant 1                         participant 2
├─ topic metadata                     ├─ topic metadata
├─ writer and writer history          ├─ reader and reader history
├─ discovered reader + match          ├─ discovered writer + match
└─ RTPS runtime + UDP sockets         └─ RTPS runtime + UDP sockets
          │                                      ▲
          └──────── CDR sample in RTPS DATA ─────┘

The two topic objects do not share an address or C++ lifetime. “The same topic” means that both processes independently declare the same distributed identity. SPDP discovers the participants; SEDP exchanges their writer and reader descriptions; RTPS carries the serialized sample after they match.

Share the data contract

Both executables include the same type definition and CDR mapping.

struct Temperature {
  static constexpr std::string_view tin_dds_type_name{
    "sensors.Temperature" };
  float degrees_celsius{};
};

template<typename Archive, typename Self>
  requires std::same_as<std::remove_cvref_t<Self>, Temperature>
bool tin_dds_serde(Archive& archive, Self& value) {
  return archive(value.degrees_celsius);
}

Process A: publish

auto config = tin::dds::static_peer_configuration::loopback(
  7U, 1U, 2U); // domain 7, this participant 1, peer 2
auto dds = tin::dds::participant_service::connect(*config);

auto topic = dds->create_topic<Temperature>(
  "sensors/temperature");
auto writer = dds->create_writer(topic);

if (!writer ||
    !writer->wait_for_reader(std::chrono::seconds{ 2 })) {
  return EXIT_FAILURE;
}

if (!writer->write_for(
      Temperature{ .degrees_celsius = 23.5F },
      std::chrono::milliseconds{ 100 })) {
  return EXIT_FAILURE;
}

Process B: receive

auto config = tin::dds::static_peer_configuration::loopback(
  7U, 2U, 1U); // domain 7, this participant 2, peer 1
auto dds = tin::dds::participant_service::connect(*config);

auto topic = dds->create_topic<Temperature>(
  "sensors/temperature");
auto reader = dds->create_reader(topic);

if (!reader ||
    !reader->wait_for_writer(std::chrono::seconds{ 2 })) {
  return EXIT_FAILURE;
}

auto sample = reader->take_for(
  std::chrono::milliseconds{ 100 });

What to verify

• The participant IDs differ, while the domain, topic name, type identity, and QoS agree.
• The writer and reader match without sharing a C++ object or memory address.
• write_for() serializes and sends the sample; take_for() returns it from Process B's reader history.
• Changing the domain, topic name, type identity, or QoS compatibility prevents the match.

Tutorial 2 · about 15 minutes

Represent many robots as instances of one topic

Use each robot's ID as its key on one topic. Configure a bounded transient-local history so a late reader receives recent state.

tin::dds::qos_profile qos{};
qos.reliability = tin::dds::reliability_kind::reliable;
qos.durability = tin::dds::durability_kind::transient_local;
qos.history = tin::dds::history_kind::keep_last;
qos.depth = 8U;
qos.max_samples = 64U;

auto topic = participant.create_topic<RobotPose>("fleet/pose", qos);
auto writer = participant.create_writer(topic, qos);

writer->write(pose, "robot-17");

// This reader may be created after the write. Transient-local durability
// replays retained state from the still-running writer.
auto reader = participant.create_reader(topic, qos);
auto sample = reader->take_instance("robot-17");

What to verify

• Another robot ID creates another independently managed object, not another topic.
• take_instance() selects only the requested robot.
• A late reader receives the retained sample with its original sequence metadata.

Tutorial 3 · about 20 minutes

Request reliable delivery

Reliable QoS makes delivery a writer-reader contract. The writer keeps bounded repair history while RTPS heartbeats and acknowledgements recover missing samples and fragments.

tin::dds::qos_profile reliable{};
reliable.reliability = tin::dds::reliability_kind::reliable;
reliable.history = tin::dds::history_kind::keep_last;
reliable.depth = 32U;
reliable.max_samples = 32U;

auto topic = participant.create_topic<Temperature>(
  "sensors/temperature", reliable);
auto writer = participant.create_writer(topic, reliable);
auto reader = participant.create_reader(topic, reliable);

writer->write(Temperature{ .degrees_celsius = 23.5F });
auto sample = reader->take();

What to verify

• A reliable writer satisfies a reader requesting reliable delivery.
• A best-effort writer does not match that reader.
• Repair remains bounded by the configured writer history.

Tutorial 4 · about 10 minutes

Use shared memory without changing publish code

The application writes to a DDS topic. Tin DDS selects an eligible same-host shared-memory path or RTPS/UDP for each matched reader.

This sketch assumes a service configured for both transports and an eligible shared-memory attachment. The static-peer participant_service used in Tutorial 1 serves UDP only; placing those two processes on one host does not turn it into a SHM service. See transport and progress contracts.

if (!writer->write(sample)) {
  return EXIT_FAILURE;
}

// Same-host match  → shared-memory descriptor
// Remote match     → RTPS DATA or DATA_FRAG over UDP
// Mixed fanout     → one write, transport selected per reader

What to verify

• The C++ call is identical for shared-memory and UDP readers.
• An unavailable shared-memory path follows the configured policy: explicitly permitted UDP fallback or rejection, not an assumed fallback.
• Type matching and reliability remain DDS concerns on either transport.

Tutorial 5 · about 20 minutes

Authenticate and authorize a DDS peer

Bind signed governance and permissions policy to the participant, run bounded PKI-DH handshake progress, and admit the remote identity before activating protected communication.

This is the authentication stage, not a complete encrypted data path. For protected application traffic, use the participant_security_runtime owner in the Security API reference. Authentication alone does not establish endpoint permissions or install every required key.

using namespace tin::dds::security;

auto graph_admission = permissions_graph_admission::create(
  domain, signed_governance, signed_permissions);
graph_admission->set_authorization_time(authorization_time);

auto config = participant_authentication_runtime_configuration{}
  .with_graph_admission(*graph_admission)
  .with_remote_permissions_validator(remote_permissions);

auto security = participant_authentication_runtime::create(
  participant,
  *runtime,
  local_identity,
  trust_store,
  session_limits,
  config);

std::array<std::byte, 4096> discovery_buffer{};
std::array<std::byte, 4096> user_buffer{};

for (std::uint64_t tick{};
     !security->authenticated(peer_guid);
     ++tick) {
  security->progress(
    tick,
    participant_authentication_runtime::clock::now(),
    discovery_buffer,
    user_buffer);
}

What to verify

• An untrusted certificate or invalid handshake never produces an authenticated peer.
• Expired or unauthorized permissions fail before endpoints enter the match graph.
• Handshake sessions, retries, and message buffers remain within configured limits.

Tutorial 6 · about 20 minutes

Admit a teleoperation command

Give one operator session control authority, attach the resulting lease to the command reader, and accept only commands from that session and epoch that are fresh and strictly ordered.

using namespace tin::dds::teleop;

auto robot = robot_id::from_value(17U);
auto session = operator_session_id::from_value(42U);
auto sequence = command_sequence::from_value(1U);

endpoint_factory endpoints{ participant };
auto writer = endpoints.create_command_writer<MotionSetpoint>(
  "robot/motion");
auto reader = endpoints.create_command_reader<MotionSetpoint>(
  "robot/motion",
  command_admission_config{
    .robot = *robot,
    .freshness_limit_nanoseconds = 5'000'000U,
  });

control_authority authority{ control_authority_config{
  .robot = *robot,
  .lease_duration_ticks = 1'000U,
} };
auto grant = authority.grant(
  *session, monotonic_timestamp::from_ticks(10U));
reader->adopt_authority(grant.lease);

motion_command<MotionSetpoint> command{
  .robot = *robot,
  .session = *session,
  .epoch = grant.lease.epoch,
  .sequence = *sequence,
  .generated_at = synchronized_timestamp::from_tai_nanoseconds(1'000'000U),
  .requested_mode = operation_mode::enabled,
  .payload = setpoint,
};

writer->publish(command);
auto admitted = reader->take(
  synchronized_timestamp::from_tai_nanoseconds(2'000'000U),
  clock_quality::synchronized);
if (!admitted) {
  enter_safe_hold(admitted.error());
}

What to verify

• A command from a session without the active lease is rejected.
• Repeating the same sequence number is reported as duplicate or out of order.
• A command outside the freshness limit is rejected before the application receives it.