Pro Policy: Spec-Anker, Felder, Default-Werte, Mutability nach enable, RxO-Verhalten und ein Wenn-nutzen-Tipp. Plus eine vollständige Compatibility-Matrix der 9 RxO-Pairs aus DDS 1.4 §2.2.3 und die within-entity-Konsistenzregeln. Wer Rezepte sucht, findet sie im QoS Cookbook.
Jede DDS-Entity (DomainParticipant, Topic, Publisher/Subscriber, DataWriter/DataReader) trägt einen QoS-Block aus den anwendbaren Policies. Die Policies sind in drei Achsen organisiert:
OFFERED_INCOMPATIBLE_QOS/REQUESTED_INCOMPATIBLE_QOS. Betrifft 9 von 22 Policies (siehe Compatibility-Matrix).HistoryQos.depth ≤ ResourceLimits.max_samples_per_instance). set_qos() lehnt inkonsistente Sets mit InconsistentPolicy ab.enable() nicht mehr geändert werden (immutable). Setzen vor dem ersten Sample-Schreiben/-Lesen.Default-Werte folgen exakt der Spec (DDS 1.4 §2.2.3). Pro Policy-Block unten: Spec-§, Felder, Default, RxO-Verhalten, Mutability und Wenn-nutzen.
Reader „requests" einen Wert, Writer „offers" einen. Diese 9 Policies haben eine RxO-Rule aus DDS 1.4 §2.2.3 — alle anderen 13 Policies haben kein Compatibility-Verhalten.
| Policy | Spec § | Match-Rule (offered vs. requested) | RxO-Enum |
|---|---|---|---|
Reliability | §2.2.3.14 | Reliable offered ≥ BestEffort requested. Reader Reliable matched nur Writer Reliable. | IncompatibleReason::Reliability |
Durability | §2.2.3.4 | offered ≥ requested in Volatile < TransientLocal < Transient < Persistent. | IncompatibleReason::Durability |
Deadline | §2.2.3.7 | offered ≤ requested (Writer-Period muss ≤ Reader-Erwartung sein). | IncompatibleReason::Deadline |
LatencyBudget | §2.2.3.8 | offered ≤ requested. Hint-Charakter, aber RxO-relevant. | IncompatibleReason::LatencyBudget |
Liveliness | §2.2.3.11 | offered.kind ≥ requested.kind in Automatic < ManualByParticipant < ManualByTopic, UND offered.lease_duration ≤ requested.lease_duration. | IncompatibleReason::Liveliness |
DestinationOrder | §2.2.3.17 | offered ≥ requested in ByReceptionTimestamp < BySourceTimestamp. | IncompatibleReason::DestinationOrder |
Presentation | §2.2.3.6 | offered.access_scope ≥ requested in Instance < Topic < Group, plus coherent/ordered offered ⊇ requested. | IncompatibleReason::Presentation |
Ownership | §2.2.3.9 | offered.kind == requested.kind (Shared/Exclusive müssen identisch sein). | IncompatibleReason::Ownership |
Partition | §2.2.3.13 | mindestens eine Partition-Sequence muss zwischen Writer und Reader matchen (Glob-Pattern via POSIX-fnmatch). | IncompatibleReason::Partition |
Compute-Function im Code: crates/qos/src/compatibility.rs · compute_compatibility(offered, requested) -> CompatibilityResult
Manche Policy-Kombinationen sind innerhalb einer Entity inkonsistent — set_qos() lehnt sie mit InconsistentPolicy ab, bevor sie überhaupt am Wire landen.
| Regel | Spec § | Bedingung |
|---|---|---|
| History.depth ≤ ResourceLimits.max_samples_per_instance | §2.2.3.18 + §2.2.3.19 | Wenn History=KeepLast(N), darf N nicht max_samples_per_instance übersteigen. |
| History=KeepAll erfordert ResourceLimits.max_samples_per_instance=UNLIMITED | §2.2.3.18 | KeepAll kann ohne UNLIMITED in OutOfResources-State laufen. |
| OwnershipStrength gilt nur wenn Ownership=Exclusive | §2.2.3.10 | Setting Strength bei Ownership=Shared ist No-Op (kein Fehler). |
| LivelinessQos.lease_duration > 0 wenn kind≠Automatic | §2.2.3.11 | ManualByParticipant/Topic mit lease=0 ist degenerated. |
| DurabilityServiceQos.history_depth ≤ DurabilityServiceQos.max_samples_per_instance | §2.2.3.5 | Wie History/ResourceLimits, aber für den Persistence-Service. |
| ResourceLimits.max_samples_per_instance ≤ ResourceLimits.max_samples | §2.2.3.19 | Per-Instance-Cap darf nicht über das Total-Cap. |
enable()DDS 1.4 §2.2.3 markiert jede Policy als mutable (kann nach enable() via set_qos() geändert werden) oder immutable (nur vor enable() setzbar; danach wirft set_qos() einen ImmutablePolicy-Error).
| Policy | Mutable nach enable? | Grund |
|---|---|---|
UserData / TopicData / GroupData | ✓ mutable | Opaque Bytes, nur Discovery-Side-Effect. |
Durability | ✗ immutable | Beeinflusst Writer-Cache-Backing — kann nicht im Flug geändert werden. |
DurabilityService | ✗ immutable | Persistence-Service-Konfig. |
Presentation | ✗ immutable | Coherent/ordered-Modus an Topic gebunden. |
Deadline | ✓ mutable | Reine Status-Trigger-Logik. |
LatencyBudget | ✓ mutable | Scheduler-Hint. |
Ownership | ✗ immutable | Bestimmt Instance-Routing. |
OwnershipStrength | ✓ mutable | Dynamisches Strength-Voting. |
Liveliness | ✗ immutable | Lease-Watchdog kann nicht im Flug umgeschaltet werden. |
TimeBasedFilter | ✓ mutable | Reader-Side-Sampling-Filter. |
Partition | ✓ mutable | Dynamische Re-Matching mit anderen Partitionen. |
Reliability | ✗ immutable | Wire-Protokoll-Modus (RTPS Best-Effort vs. Reliable). |
TransportPriority | ✓ mutable | Hint für Transport-Scheduling. |
Lifespan | ✓ mutable | Gilt nur für nachfolgende Samples. |
DestinationOrder | ✗ immutable | Sample-Ordering-Modus. |
History | ✗ immutable | Cache-Backing-Strategie. |
ResourceLimits | ✗ immutable | Cache-Allokation. |
EntityFactory | ✓ mutable | Beeinflusst nur Neu-Erzeugung untergeordneter Entities. |
WriterDataLifecycle | ✓ mutable | Reine Verhaltens-Flag. |
ReaderDataLifecycle | ✓ mutable | Auto-Purge-Timer. |
Drei opaque sequence<octet>-Slots, die im Discovery ausgetauscht werden. Keine RxO-Compatibility, kein Match-Effekt — nutzbar für eigene Metadata-Übertragung am Discovery-Kanal.
Felder: value: Vec<u8> · Default: empty · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Application-spezifische Metadata, die der Discovery-Layer transportiert (Custom-Auth-Tokens, Build-Version, Deployment-Identifier). Aufpassen bei DDS-Security — der Inhalt ist sichtbar für jeden, der Discovery sehen darf.
Repo: crates/qos/src/policies/generic_data.rs (gemeinsam mit TopicData + GroupData)
Felder: value: Vec<u8> · Default: empty · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Topic-spezifische Metadata (z.B. Schema-Hash, OEM-Topic-ID). Wird mit dem Topic-Discovery-Eintrag propagiert.
Felder: value: Vec<u8> · Default: empty · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Group-Level-Metadata bei Coherent/Ordered Sets — z.B. Transaktions-ID einer kohärenten Sample-Gruppe.
Bestimmt, ob und wie Samples für Late-Joiner verfügbar bleiben.
Felder: kind: DurabilityKind (Volatile · TransientLocal · Transient · Persistent) · Default: Volatile · RxO: offered ≥ requested · Mutable: ✗ nein
Wenn nutzen: Volatile für Telemetry (Verlust OK). TransientLocal für State-Topics (Setpoints, Mode), damit Late-Joiner den letzten Wert sehen. Transient/Persistent liefert der eingebaute DurabilityService: Transient hält die History in-memory, Persistent on-disk (übersteht einen Neustart) — Late-Joiner-Replay ist für beide Stufen end-to-end getestet. Cross-Vendor-Replay von Transient/Persistent ist eine OMG-Spec-Lücke (RTPS spezifiziert dafür keine Wire-Mechanik), heute also ZeroDDS↔ZeroDDS.
Felder: service_cleanup_delay: Duration · history_kind: HistoryKind · history_depth: i32 · max_samples / max_instances / max_samples_per_instance: i32 · Default: KeepLast(1) + UNLIMITED · RxO: kein · Mutable: ✗ nein
Wenn nutzen: Konfiguriert den Persistence-Service hinter Transient/Persistent Durability. Wird nur ausgewertet, wenn Durability=Transient/Persistent gesetzt ist.
Failure-Detection: Reader will wissen, ob Writer noch "lebt". Deadline ist die Sample-Frequenz-Garantie.
Felder: kind: LivelinessKind (Automatic · ManualByParticipant · ManualByTopic) · lease_duration: Duration · Default: Automatic/INFINITE · RxO: offered.kind ≥ requested.kind UND offered.lease ≤ requested.lease · Mutable: ✗ nein
Wenn nutzen: Automatic für Telemetry (DDS-Stack pingt selbst). ManualByParticipant wenn die App durch assert_liveliness() oder regelmäßiges write() Liveness signalisieren will (Heartbeat-Modell). ManualByTopic für Failover-Patterns (siehe Cookbook §3).
Felder: period: Duration · Default: INFINITE · RxO: offered ≤ requested · Mutable: ✓ ja
Wenn nutzen: Control-Loops mit Frequenz-Garantie. Writer-Deadline-Miss triggert OfferedDeadlineMissedStatus, Reader-Side RequestedDeadlineMissedStatus. Listener-Callback (siehe DCPS) reagiert auf Misses.
Wire-Garantien: ob Samples ankommen müssen, in welcher Reihenfolge sie auf der Reader-Side liegen.
Felder: kind: ReliabilityKind (BestEffort · Reliable) · max_blocking_time: Duration · Default: Writer Reliable, Reader BestEffort · RxO: offered ≥ requested · Mutable: ✗ nein
Wenn nutzen: BestEffort für Telemetry (kein ACK, kein Retransmit). Reliable für Commands, State-Updates, Config-Topics — ACK/NACK über RTPS, Retransmit auf Daten-Loss. max_blocking_time ist die Wartezeit auf write() bei vollem Cache.
Felder: kind: DestinationOrderKind (ByReceptionTimestamp · BySourceTimestamp) · Default: ByReceptionTimestamp · RxO: offered ≥ requested · Mutable: ✗ nein
Wenn nutzen: ByReceptionTimestamp ist der Default — Sample-Order ergibt sich aus Reader-Ankunft. BySourceTimestamp wenn Writer-seitige Zeitstempel logisch korrekt sind (Clock-synced Cluster, Replay-Szenarien).
Felder: duration: Duration · Default: 0 ns · RxO: offered ≤ requested · Mutable: ✓ ja
Wenn nutzen: Hint für den Transport-Scheduler — wieviel Zeit der Sample-Pfad maximal nutzen darf. Kein direkter Wire-Effekt; eher Optimierungs-Indikator (Batching, Priorisierung).
Wer darf schreiben? Bei Exclusive: nur der stärkste Writer ist aktiv.
Felder: kind: OwnershipKind (Shared · Exclusive) · Default: Shared · RxO: offered.kind == requested.kind · Mutable: ✗ nein
Wenn nutzen: Shared erlaubt mehrere Writer pro Instance (Standard). Exclusive für Hot-Standby-Failover — nur der Writer mit höchster OwnershipStrength ist aktiv (siehe Cookbook §3).
Felder: value: i32 · Default: 0 · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Strength-Voting bei Ownership=Exclusive. Höchster Wert gewinnt. Mutable-Setter erlaubt dynamische Re-Election (Heartbeat-basiertes Promote/Demote).
Wie viele Samples werden im Writer/Reader-Cache gehalten?
Felder: kind: HistoryKind (KeepLast · KeepAll) · depth: i32 · Default: KeepLast(1) · RxO: kein · Mutable: ✗ nein
Wenn nutzen: KeepLast(N) für Sliding-Window (älteste werden überschrieben). KeepAll für Audit-Log-Pattern — alles bis ResourceLimits halten. Bei KeepAll + Reliable: Writer blockt bei vollem Cache (siehe Reliability.max_blocking_time).
Felder: max_samples: i32 · max_instances: i32 · max_samples_per_instance: i32 (UNLIMITED = -1) · Default: 1000 / 10 / 100 · RxO: kein · Mutable: ✗ nein
Wenn nutzen: Hard-Cap auf Cache-Allokation. Bei Reliable + KeepAll erreicht das Cache-Limit, blockt Writer (OutOfResources). Setze passend zur erwarteten Daten-Rate und Reader-Verzögerung.
Felder: access_scope: PresentationAccessScope (Instance · Topic · Group) · coherent_access: bool · ordered_access: bool · Default: Instance/false/false · RxO: offered.scope ≥ requested.scope, coherent/ordered offered ⊇ requested · Mutable: ✗ nein
Wenn nutzen: Coherent-Sets gruppieren Samples zu einer atomar-sichtbaren Einheit (alle oder keine). Ordered-Sets garantieren Sample-Order über mehrere Topics einer Group (Multi-Topic-Transaktion). Höhere Scopes (Topic, Group) sind teurer und erfordern Coordination-Overhead.
Felder: names: Vec<String> (POSIX-fnmatch-Glob-Pattern erlaubt) · Default: [""] (Default-Partition) · RxO: mindestens eine Partition muss zwischen Writer und Reader matchen · Mutable: ✓ ja
Wenn nutzen: Logische Mandantentrennung im selben Domain (z.B. customer-A/odom vs. customer-B/odom). Glob-Pattern wie customer-* erlauben dynamisches Subscriber-Matching ohne Topic-Umkonfiguration. Wichtig: Partition ist Match-Filter, kein Network-Isolation — Discovery sieht trotzdem alle.
Reader-seitige Sample-Filter (Time-Based) und Writer-seitige Sample-Verfallszeit.
Felder: minimum_separation: Duration · Default: 0 ns · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Reader-Side-Downsampling. Mindest-Abstand zwischen empfangenen Samples derselben Instance. Spart Reader-Verarbeitungs-CPU bei Hochfrequenz-Topics, wenn der Konsument nur eine Subset-Rate braucht.
Felder: duration: Duration · Default: INFINITE · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Samples, die älter als duration sind, werden automatisch aus dem Cache entfernt (Writer-Seite und Reader-Seite, wenn TransientLocal). Nützlich für State-Topics mit "stale data is bad data"-Semantik (z.B. Setpoint > 30s alt = ignorieren).
Auto-Enable-Verhalten und Instance-Lifecycle-Reaktionen.
Felder: autoenable_created_entities: bool · Default: true · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Wenn true, werden neu erzeugte Sub-Entities sofort enable'd. Wenn false, muss der Anwender manuell enable() rufen — nützlich um QoS-Sets vor dem ersten Discovery-Beacon zu finalisieren.
Felder: autodispose_unregistered_instances: bool · Default: true · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Wenn true, wird unregister_instance() implizit als dispose() behandelt (Reader sieht NOT_ALIVE_DISPOSED). Wenn false, nur NOT_ALIVE_NO_WRITERS ohne Dispose-Marker.
Felder: autopurge_nowriter_samples_delay: Duration · autopurge_disposed_samples_delay: Duration · Default: INFINITE / INFINITE · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Reader-seitige Auto-Purge-Timer für ungenutzte/disposed Samples. Verhindert, dass der Reader-Cache mit alten/toten Instances vollläuft. Standard-INFINITE = nie auto-purge.
Felder: value: i32 · Default: 0 · RxO: kein · Mutable: ✓ ja
Wenn nutzen: Hint für den Transport-Layer-Scheduler (z.B. UDP DSCP-Tag, TSN-Stream-Priorität). Implementierungs-spezifisch — Wert ohne Wire-Garantie. Wichtig in Mixed-Critical-Setups (Control + Telemetry auf gleichem Link).
Repo: crates/qos/src/policies/transport_priority.rs · Auswertung im Transport-Layer: zerodds-transport
Per policy: spec anchor, fields, default values, mutability after enable, RxO behaviour and a when-to-use tip. Plus a full compatibility matrix of the 9 RxO pairs from DDS 1.4 §2.2.3 and the within-entity consistency rules. If you're after recipes, find them in the QoS Cookbook.
Every DDS entity (DomainParticipant, Topic, Publisher/Subscriber, DataWriter/DataReader) carries a QoS block of the applicable policies. The policies are organised along three axes:
OFFERED_INCOMPATIBLE_QOS/REQUESTED_INCOMPATIBLE_QOS. Affects 9 of 22 policies (see the compatibility matrix).HistoryQos.depth ≤ ResourceLimits.max_samples_per_instance). set_qos() rejects inconsistent sets with InconsistentPolicy.enable() (immutable). Set them before the first sample write/read.Default values follow the spec exactly (DDS 1.4 §2.2.3). Per policy block below: spec §, fields, default, RxO behaviour, mutability and when-to-use.
The reader "requests" a value, the writer "offers" one. These 9 policies have an RxO rule from DDS 1.4 §2.2.3 — all the other 13 policies have no compatibility behaviour.
| Policy | Spec § | Match rule (offered vs. requested) | RxO enum |
|---|---|---|---|
Reliability | §2.2.3.14 | Reliable offered ≥ BestEffort requested. A Reliable reader matches only a Reliable writer. | IncompatibleReason::Reliability |
Durability | §2.2.3.4 | offered ≥ requested in Volatile < TransientLocal < Transient < Persistent. | IncompatibleReason::Durability |
Deadline | §2.2.3.7 | offered ≤ requested (the writer period must be ≤ the reader expectation). | IncompatibleReason::Deadline |
LatencyBudget | §2.2.3.8 | offered ≤ requested. Hint in character, but RxO-relevant. | IncompatibleReason::LatencyBudget |
Liveliness | §2.2.3.11 | offered.kind ≥ requested.kind in Automatic < ManualByParticipant < ManualByTopic, AND offered.lease_duration ≤ requested.lease_duration. | IncompatibleReason::Liveliness |
DestinationOrder | §2.2.3.17 | offered ≥ requested in ByReceptionTimestamp < BySourceTimestamp. | IncompatibleReason::DestinationOrder |
Presentation | §2.2.3.6 | offered.access_scope ≥ requested in Instance < Topic < Group, plus coherent/ordered offered ⊇ requested. | IncompatibleReason::Presentation |
Ownership | §2.2.3.9 | offered.kind == requested.kind (Shared/Exclusive must be identical). | IncompatibleReason::Ownership |
Partition | §2.2.3.13 | at least one partition sequence must match between writer and reader (glob patterns via POSIX fnmatch). | IncompatibleReason::Partition |
Compute function in the code: crates/qos/src/compatibility.rs · compute_compatibility(offered, requested) -> CompatibilityResult
Some policy combinations are inconsistent within one entity — set_qos() rejects them with InconsistentPolicy before they ever hit the wire.
| Rule | Spec § | Condition |
|---|---|---|
| History.depth ≤ ResourceLimits.max_samples_per_instance | §2.2.3.18 + §2.2.3.19 | With History=KeepLast(N), N must not exceed max_samples_per_instance. |
| History=KeepAll requires ResourceLimits.max_samples_per_instance=UNLIMITED | §2.2.3.18 | KeepAll can run into an OutOfResources state without UNLIMITED. |
| OwnershipStrength applies only when Ownership=Exclusive | §2.2.3.10 | Setting strength with Ownership=Shared is a no-op (no error). |
| LivelinessQos.lease_duration > 0 when kind≠Automatic | §2.2.3.11 | ManualByParticipant/Topic with lease=0 is degenerate. |
| DurabilityServiceQos.history_depth ≤ DurabilityServiceQos.max_samples_per_instance | §2.2.3.5 | Like History/ResourceLimits, but for the persistence service. |
| ResourceLimits.max_samples_per_instance ≤ ResourceLimits.max_samples | §2.2.3.19 | The per-instance cap must not exceed the total cap. |
enable()DDS 1.4 §2.2.3 marks each policy as mutable (can be changed after enable() via set_qos()) or immutable (settable only before enable(); after that set_qos() throws an ImmutablePolicy error).
| Policy | Mutable after enable? | Reason |
|---|---|---|
UserData / TopicData / GroupData | ✓ mutable | Opaque bytes, only a discovery side-effect. |
Durability | ✗ immutable | Affects writer cache backing — can't be changed in flight. |
DurabilityService | ✗ immutable | Persistence-service config. |
Presentation | ✗ immutable | Coherent/ordered mode bound to the topic. |
Deadline | ✓ mutable | Pure status-trigger logic. |
LatencyBudget | ✓ mutable | Scheduler hint. |
Ownership | ✗ immutable | Determines instance routing. |
OwnershipStrength | ✓ mutable | Dynamic strength voting. |
Liveliness | ✗ immutable | The lease watchdog can't be switched in flight. |
TimeBasedFilter | ✓ mutable | Reader-side sampling filter. |
Partition | ✓ mutable | Dynamic re-matching with other partitions. |
Reliability | ✗ immutable | Wire-protocol mode (RTPS best-effort vs. reliable). |
TransportPriority | ✓ mutable | Hint for transport scheduling. |
Lifespan | ✓ mutable | Applies only to subsequent samples. |
DestinationOrder | ✗ immutable | Sample-ordering mode. |
History | ✗ immutable | Cache-backing strategy. |
ResourceLimits | ✗ immutable | Cache allocation. |
EntityFactory | ✓ mutable | Only affects the creation of new sub-entities. |
WriterDataLifecycle | ✓ mutable | Pure behaviour flag. |
ReaderDataLifecycle | ✓ mutable | Auto-purge timer. |
Three opaque sequence<octet> slots exchanged during discovery. No RxO compatibility, no match effect — usable for your own metadata transfer on the discovery channel.
Fields: value: Vec<u8> · Default: empty · RxO: none · Mutable: ✓ yes
When to use: application-specific metadata carried by the discovery layer (custom auth tokens, build version, deployment identifier). Beware with DDS-Security — the content is visible to anyone allowed to see discovery.
Repo: crates/qos/src/policies/generic_data.rs (shared with TopicData + GroupData)
Fields: value: Vec<u8> · Default: empty · RxO: none · Mutable: ✓ yes
When to use: topic-specific metadata (e.g. a schema hash, OEM topic ID). Propagated with the topic discovery entry.
Fields: value: Vec<u8> · Default: empty · RxO: none · Mutable: ✓ yes
When to use: group-level metadata for coherent/ordered sets — e.g. the transaction ID of a coherent sample group.
Determines whether and how samples remain available for late joiners.
Fields: kind: DurabilityKind (Volatile · TransientLocal · Transient · Persistent) · Default: Volatile · RxO: offered ≥ requested · Mutable: ✗ no
When to use: Volatile for telemetry (loss OK). TransientLocal for state topics (setpoints, mode) so late joiners see the last value. Transient/Persistent are provided by the built-in DurabilityService: Transient keeps history in memory, Persistent on disk (survives a restart) — late-joiner replay is tested end-to-end for both levels. Cross-vendor replay of Transient/Persistent is an OMG spec gap (RTPS specifies no wire mechanics for it), so today it is ZeroDDS↔ZeroDDS.
Fields: service_cleanup_delay: Duration · history_kind: HistoryKind · history_depth: i32 · max_samples / max_instances / max_samples_per_instance: i32 · Default: KeepLast(1) + UNLIMITED · RxO: none · Mutable: ✗ no
When to use: configures the persistence service behind Transient/Persistent durability. Only evaluated when Durability=Transient/Persistent is set.
Failure detection: the reader wants to know whether the writer is still "alive". Deadline is the sample-frequency guarantee.
Fields: kind: LivelinessKind (Automatic · ManualByParticipant · ManualByTopic) · lease_duration: Duration · Default: Automatic/INFINITE · RxO: offered.kind ≥ requested.kind AND offered.lease ≤ requested.lease · Mutable: ✗ no
When to use: Automatic for telemetry (the DDS stack pings itself). ManualByParticipant when the app wants to signal liveness via assert_liveliness() or regular write() (heartbeat model). ManualByTopic for failover patterns (see Cookbook §3).
Fields: period: Duration · Default: INFINITE · RxO: offered ≤ requested · Mutable: ✓ yes
When to use: control loops with a frequency guarantee. A writer deadline miss triggers OfferedDeadlineMissedStatus, the reader side RequestedDeadlineMissedStatus. A listener callback (see DCPS) reacts to misses.
Wire guarantees: whether samples must arrive, and in what order they sit on the reader side.
Fields: kind: ReliabilityKind (BestEffort · Reliable) · max_blocking_time: Duration · Default: writer Reliable, reader BestEffort · RxO: offered ≥ requested · Mutable: ✗ no
When to use: BestEffort for telemetry (no ACK, no retransmit). Reliable for commands, state updates, config topics — ACK/NACK over RTPS, retransmit on data loss. max_blocking_time is the wait on write() when the cache is full.
Fields: kind: DestinationOrderKind (ByReceptionTimestamp · BySourceTimestamp) · Default: ByReceptionTimestamp · RxO: offered ≥ requested · Mutable: ✗ no
When to use: ByReceptionTimestamp is the default — sample order follows reader arrival. BySourceTimestamp when writer-side timestamps are logically correct (clock-synced cluster, replay scenarios).
Fields: duration: Duration · Default: 0 ns · RxO: offered ≤ requested · Mutable: ✓ yes
When to use: a hint for the transport scheduler — how much time the sample path may take at most. No direct wire effect; more of an optimisation indicator (batching, prioritisation).
Who may write? With Exclusive: only the strongest writer is active.
Fields: kind: OwnershipKind (Shared · Exclusive) · Default: Shared · RxO: offered.kind == requested.kind · Mutable: ✗ no
When to use: Shared allows multiple writers per instance (standard). Exclusive for hot-standby failover — only the writer with the highest OwnershipStrength is active (see Cookbook §3).
Fields: value: i32 · Default: 0 · RxO: none · Mutable: ✓ yes
When to use: strength voting with Ownership=Exclusive. Highest value wins. The mutable setter allows dynamic re-election (heartbeat-based promote/demote).
How many samples are kept in the writer/reader cache?
Fields: kind: HistoryKind (KeepLast · KeepAll) · depth: i32 · Default: KeepLast(1) · RxO: none · Mutable: ✗ no
When to use: KeepLast(N) for a sliding window (oldest get overwritten). KeepAll for an audit-log pattern — keep everything up to ResourceLimits. With KeepAll + Reliable: the writer blocks when the cache is full (see Reliability.max_blocking_time).
Fields: max_samples: i32 · max_instances: i32 · max_samples_per_instance: i32 (UNLIMITED = -1) · Default: 1000 / 10 / 100 · RxO: none · Mutable: ✗ no
When to use: a hard cap on cache allocation. With Reliable + KeepAll reaching the cache limit blocks the writer (OutOfResources). Set it to match the expected data rate and reader lag.
Fields: access_scope: PresentationAccessScope (Instance · Topic · Group) · coherent_access: bool · ordered_access: bool · Default: Instance/false/false · RxO: offered.scope ≥ requested.scope, coherent/ordered offered ⊇ requested · Mutable: ✗ no
When to use: coherent sets group samples into an atomically visible unit (all or none). Ordered sets guarantee sample order across multiple topics of a group (multi-topic transaction). Higher scopes (Topic, Group) are more expensive and require coordination overhead.
Fields: names: Vec<String> (POSIX fnmatch glob patterns allowed) · Default: [""] (default partition) · RxO: at least one partition must match between writer and reader · Mutable: ✓ yes
When to use: logical tenant separation within the same domain (e.g. customer-A/odom vs. customer-B/odom). Glob patterns like customer-* allow dynamic subscriber matching without reconfiguring topics. Important: partition is a match filter, not network isolation — discovery still sees everyone.
Reader-side sample filters (time-based) and writer-side sample expiry.
Fields: minimum_separation: Duration · Default: 0 ns · RxO: none · Mutable: ✓ yes
When to use: reader-side downsampling. A minimum gap between received samples of the same instance. Saves reader processing CPU on high-frequency topics when the consumer only needs a subset rate.
Fields: duration: Duration · Default: INFINITE · RxO: none · Mutable: ✓ yes
When to use: samples older than duration are automatically removed from the cache (writer side, and reader side if TransientLocal). Useful for state topics with "stale data is bad data" semantics (e.g. a setpoint > 30s old = ignore).
Auto-enable behaviour and instance-lifecycle reactions.
Fields: autoenable_created_entities: bool · Default: true · RxO: none · Mutable: ✓ yes
When to use: if true, newly created sub-entities are enable'd immediately. If false, the user must call enable() manually — useful to finalise QoS sets before the first discovery beacon.
Fields: autodispose_unregistered_instances: bool · Default: true · RxO: none · Mutable: ✓ yes
When to use: if true, unregister_instance() is implicitly treated as dispose() (the reader sees NOT_ALIVE_DISPOSED). If false, only NOT_ALIVE_NO_WRITERS without a dispose marker.
Fields: autopurge_nowriter_samples_delay: Duration · autopurge_disposed_samples_delay: Duration · Default: INFINITE / INFINITE · RxO: none · Mutable: ✓ yes
When to use: reader-side auto-purge timers for unused/disposed samples. Prevents the reader cache from filling up with old/dead instances. Default INFINITE = never auto-purge.
Fields: value: i32 · Default: 0 · RxO: none · Mutable: ✓ yes
When to use: a hint for the transport-layer scheduler (e.g. a UDP DSCP tag, TSN stream priority). Implementation-specific — a value with no wire guarantee. Important in mixed-critical setups (control + telemetry on the same link).
Repo: crates/qos/src/policies/transport_priority.rs · evaluated in the transport layer: zerodds-transport