VLink  2.3.0
A high-performance communication middleware
qos_profile.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2026 by Thun Lu. All rights reserved.
3  * Author: Thun Lu <thun.lu@zohomail.cn>
4  * Repo: https://github.com/thun-res/vlink
5  * _ __ __ _ __
6  * | | / / / / (_) ____ / /__
7  * | | / / / / / / / __ \ / //_/
8  * | |/ / / /___ / / / / / / / ,<
9  * |___/ /_____/ /_/ /_/ /_/ /_/|_|
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 
24 /**
25  * @file qos_profile.h
26  * @brief Curated catalogue of pre-built @c Qos instances for common VLink workloads.
27  *
28  * @details
29  * Picking the right @c Qos for a topic involves balancing reliability, history depth,
30  * durability, publish mode and priority. This file declares sixteen ready-to-use
31  * @c constexpr profiles inside @c vlink::QosProfile, each tuned for a specific class of
32  * traffic encountered in autonomy and embedded stacks. Every profile is constructed
33  * with @c valid set to @c true and can be passed straight to any VLink endpoint or
34  * registered with a transport (@c DdsConf::register_qos) before being referenced from
35  * a URL.
36  *
37  * Profile catalogue (use-case oriented):
38  *
39  * | Profile | Reliability | History | Durability | PublishMode | Priority |
40  * | -------------- | ---------------- | -------------- | --------------- | ----------- | ---------- |
41  * | @c kEvent | Reliable | KeepLast(5) | Volatile | Sync | RealTime |
42  * | @c kMethod | Reliable | KeepAll | Volatile | Sync | High |
43  * | @c kField | Reliable | KeepLast(1) | TransientLocal | Sync | High |
44  * | @c kSensor | BestEffort | KeepLast(10) | Volatile | ASync | Normal* |
45  * | @c kParameter | Reliable | KeepLast(500) | TransientLocal | Sync | Normal |
46  * | @c kService | Reliable | KeepLast(10) | TransientLocal | Sync | Normal |
47  * | @c kClock | BestEffort | KeepLast(1) | Volatile | Sync | Low* |
48  * | @c kStatic | Reliable | KeepAll | TransientLocal | Sync | Normal |
49  * | @c kLight | Reliable | KeepLast(1) | Volatile | ASync | High |
50  * | @c kPoor | BestEffort | KeepLast(5) | Volatile | ASync | Background |
51  * | @c kBetter | BestEffort | KeepLast(50) | Volatile | Sync | RealTime |
52  * | @c kBest | Reliable | KeepLast(10) | Volatile | Sync | RealTime |
53  * | @c kStream | Reliable (HB500) | KeepLast(100) | Volatile | Sync | Low |
54  * | @c kAlarm | Reliable | KeepAll | TransientLocal | Sync | RealTime* |
55  * | @c kCommand | Reliable | KeepLast(1) | Volatile | Sync | RealTime |
56  * | @c kLog | Reliable | KeepLast(100) | Volatile | ASync | Background |
57  *
58  * Profiles marked @c * (@c kSensor, @c kClock, @c kAlarm) are dispatched as express (the
59  * @c is_express flag is set). Use-case mapping:
60  * @c kEvent = discrete control events, @c kMethod = RPC, @c kField = latest-value state sync,
61  * @c kSensor = high-rate sensors, @c kParameter = slow config, @c kService = discovery,
62  * @c kClock = time sync, @c kStatic = maps / calibration, @c kLight = small frequent traffic,
63  * @c kPoor = low-priority telemetry, @c kBetter = best-effort throughput,
64  * @c kBest = reliable throughput, @c kStream = continuous large-payload streams (heartbeat 500 ms),
65  * @c kAlarm = safety-critical alarms, @c kCommand = actuator commands, @c kLog = log streams.
66  *
67  * @par Looking profiles up by name
68  * @code
69  * const auto& qos_map = vlink::QosProfile::get_available_qos_map();
70  *
71  * if (auto it = qos_map.find("sensor"); it != qos_map.end()) {
72  * vlink::DdsConf::register_qos("my_sensor_qos", it->second);
73  * }
74  * @endcode
75  *
76  * @par Using a profile by URL
77  * @code
78  * // Built-in names are recognised directly in URLs:
79  * auto pub = vlink::Publisher<MyMsg>::create_unique("dds://sensor_data?qos=sensor");
80  *
81  * // Or apply a profile programmatically:
82  * vlink::Qos qos = vlink::QosProfile::kField;
83  * qos.history.depth = 5; // tweak the depth before use
84  * vlink::DdsConf::register_qos("my_field_qos", qos);
85  * @endcode
86  */
87 
88 #pragma once
89 
90 #include <string>
91 #include <unordered_map>
92 
93 #include "../base/macros.h"
94 #include "./qos.h"
95 
96 namespace vlink {
97 
98 /**
99  * @namespace vlink::QosProfile
100  * @brief Pre-built @c Qos constants for common autonomy and embedded workloads.
101  *
102  * @details
103  * Every constant in this namespace carries @c valid = @c true and is safe to pass
104  * directly to any VLink endpoint or to register with a transport. Pick the closest
105  * profile for your traffic and customise a copy if you need finer control. All built-in
106  * profiles default-construct Deadline and Lifespan, leaving the Deadline period at @c -1
107  * (no constraint) and the Lifespan duration at @c -1 (infinite). Configure a finite
108  * Lifespan only when the hosts share a suitable clock-synchronisation contract.
109  *
110  * @see Qos, get_available_qos_map()
111  */
112 namespace QosProfile { // NOLINT(readability-identifier-naming)
113 
114 /**
115  * @brief Reliable, KeepLast(5), Volatile, Sync, RealTime priority.
116  *
117  * @details Designed for discrete control events where delivery must be guaranteed and
118  * a small backlog of late arrivals is acceptable. A 1000 ms automatic liveliness lease
119  * surfaces a dead writer quickly. Lifespan is infinite (-1), and no Deadline is imposed
120  * because control events are aperiodic.
121  */
122 [[maybe_unused]] static inline constexpr Qos kEvent{
123  "event",
124  true,
131  Qos::Ownership{},
132  Qos::Deadline{},
133  Qos::Lifespan{},
137 };
138 
139 /**
140  * @brief Reliable, KeepAll, Volatile, Sync, High priority.
141  *
142  * @details Designed for RPC-style request/response flows. KeepAll ensures no request
143  * is dropped even under sustained load. A 2000 ms liveliness lease detects a stalled
144  * peer. Lifespan is infinite (-1), and no Deadline is imposed because request arrival
145  * is demand-driven, not periodic.
146  */
147 [[maybe_unused]] static inline constexpr Qos kMethod{
148  "method",
149  true,
156  Qos::Ownership{},
157  Qos::Deadline{},
158  Qos::Lifespan{},
162 };
163 
164 /**
165  * @brief Reliable, KeepLast(1), TransientLocal, Sync, High priority.
166  *
167  * @details Designed for Field model traffic where only the latest value matters but
168  * late-joining subscribers must still receive that latest value on demand. A 2000 ms
169  * liveliness lease guards the writer; Lifespan is infinite (-1) so the latest state never
170  * expires, and no Deadline is imposed because state updates are change-driven.
171  */
172 [[maybe_unused]] static inline constexpr Qos kField{
173  "field",
174  true,
181  Qos::Ownership{},
182  Qos::Deadline{},
183  Qos::Lifespan{},
187 };
188 
189 /**
190  * @brief BestEffort, KeepLast(10), Volatile, ASync, Normal priority, express delivery.
191  *
192  * @details Designed for high-rate sensor streams (LiDAR, camera, IMU) where throughput
193  * dominates and a few dropped samples are preferable to back-pressure. A tight 500 ms
194  * liveliness lease detects loss of writer liveliness. Deadline is unconstrained (-1),
195  * and Lifespan is infinite (-1).
196  */
197 [[maybe_unused]] static inline constexpr Qos kSensor{
198  "sensor",
199  true,
206  Qos::Ownership{},
207  Qos::Deadline{},
208  Qos::Lifespan{},
212 };
213 
214 /**
215  * @brief Reliable, KeepLast(500), TransientLocal, Sync, Normal priority.
216  *
217  * @details Designed for configuration parameters that change rarely but must be delivered
218  * reliably. TransientLocal lets late-joining subscribers catch up on the retained history,
219  * and the KeepLast depth of 500 stays within the default @c max_samples_per_instance limit.
220  * A relaxed 5000 ms liveliness lease suits slow traffic; Lifespan is infinite (-1) so the
221  * configured values never expire, and no Deadline is imposed because changes are sporadic.
222  */
223 [[maybe_unused]] static inline constexpr Qos kParameter{
224  "parameter",
225  true,
232  Qos::Ownership{},
233  Qos::Deadline{},
234  Qos::Lifespan{},
238 };
239 
240 /**
241  * @brief Reliable, KeepLast(10), TransientLocal, Sync, Normal priority.
242  *
243  * @details Designed for service registration and discovery messages where late joiners
244  * must see the current set of advertised services. A 3000 ms liveliness lease lets a
245  * vanished provider be reaped; Lifespan is infinite (-1) so an advertisement persists
246  * until withdrawn, and no Deadline is imposed because registrations are event-driven.
247  */
248 [[maybe_unused]] static inline constexpr Qos kService{
249  "service",
250  true,
257  Qos::Ownership{},
258  Qos::Deadline{},
259  Qos::Lifespan{},
263 };
264 
265 /**
266  * @brief BestEffort, KeepLast(1), Volatile, Sync, Low priority, express delivery.
267  *
268  * @details Designed for periodic time synchronisation broadcasts where only the most
269  * recent tick has value and an occasional skipped tick is harmless. Synchronous express
270  * dispatch keeps tick jitter low, and a 1000 ms liveliness lease detects loss of writer
271  * liveliness. Deadline is unconstrained (-1), and Lifespan is infinite (-1) so host clock
272  * skew cannot discard synchronisation ticks prematurely.
273  */
274 [[maybe_unused]] static inline constexpr Qos kClock{
275  "clock",
276  true,
283  Qos::Ownership{},
284  Qos::Deadline{},
285  Qos::Lifespan{},
289 };
290 
291 /**
292  * @brief Reliable, KeepAll, TransientLocal, Sync, Normal priority.
293  *
294  * @details Designed for largely static datasets (HD maps, calibration tables) that any
295  * late-joining subscriber should receive in full (retained up to the configured
296  * @c ResourceLimits). A long 10000 ms liveliness lease
297  * tolerates a writer that publishes once and stays quiet; Lifespan is infinite (-1) so the
298  * dataset never expires, and no Deadline is imposed because the data is essentially static.
299  */
300 [[maybe_unused]] static inline constexpr Qos kStatic{
301  "static",
302  true,
309  Qos::Ownership{},
310  Qos::Deadline{},
311  Qos::Lifespan{},
315 };
316 
317 /**
318  * @brief Reliable, KeepLast(1), Volatile, ASync, High priority.
319  *
320  * @details Designed for small frequent messages where only the latest value matters
321  * and asynchronous delivery keeps CPU overhead low. A 1000 ms liveliness lease guards
322  * the writer. Lifespan is infinite (-1), and no Deadline is imposed so the profile stays
323  * usable for both periodic and bursty small-message traffic.
324  */
325 [[maybe_unused]] static inline constexpr Qos kLight{
326  "light",
327  true,
334  Qos::Ownership{},
335  Qos::Deadline{},
336  Qos::Lifespan{},
340 };
341 
342 /**
343  * @brief BestEffort, KeepLast(5), Volatile, ASync, Background priority.
344  *
345  * @details Designed for low-priority telemetry and diagnostics where any sample loss
346  * is acceptable and the goal is to minimise CPU and bandwidth impact. A relaxed 5000 ms
347  * liveliness lease keeps overhead low. Lifespan is infinite (-1), and no Deadline is
348  * imposed because telemetry cadence is not contractual.
349  */
350 [[maybe_unused]] static inline constexpr Qos kPoor{
351  "poor",
352  true,
359  Qos::Ownership{},
360  Qos::Deadline{},
361  Qos::Lifespan{},
365 };
366 
367 /**
368  * @brief BestEffort, KeepLast(50), Volatile, Sync, RealTime priority.
369  *
370  * @details Designed for high-throughput best-effort streams that benefit from a deeper
371  * buffer and real-time dispatch priority. A 1000 ms liveliness lease guards the writer
372  * and Lifespan is infinite (-1); no Deadline is imposed so the profile suits variable-rate
373  * throughput.
374  */
375 [[maybe_unused]] static inline constexpr Qos kBetter{
376  "better",
377  true,
384  Qos::Ownership{},
385  Qos::Deadline{},
386  Qos::Lifespan{},
390 };
391 
392 /**
393  * @brief Reliable, KeepLast(10), Volatile, Sync, RealTime priority.
394  *
395  * @details Designed for continuous high-throughput reliable traffic that requires
396  * predictable latency, pairing reliability with synchronous publishing and a shallow
397  * buffer that bounds queue build-up: on a saturated link a deep writer history keeps
398  * retransmitting samples the reader can no longer catch up with, which costs both latency
399  * and delivery. A 1000 ms liveliness lease guards the writer and Lifespan is infinite
400  * (-1); no Deadline is imposed so the profile suits variable-rate throughput. It differs
401  * from @c kEvent only in backlog depth: prefer @c kEvent for aperiodic control events
402  * where a five-sample backlog is enough, and this profile for sustained streams that
403  * benefit from a slightly deeper one. Switching to @c kStream also lowers the dispatch
404  * priority and changes the heartbeat and liveliness leases -- it is a different profile,
405  * not a deeper variant of this one.
406  */
407 [[maybe_unused]] static inline constexpr Qos kBest{
408  "best",
409  true,
416  Qos::Ownership{},
417  Qos::Deadline{},
418  Qos::Lifespan{},
422 };
423 
424 /**
425  * @brief Reliable, KeepLast(100), Volatile, Sync, Low priority with a shorter 500 ms heartbeat.
426  *
427  * @details Designed for continuous large-payload streams (maps, point clouds, images)
428  * carried at low dispatch priority, where a tighter 500 ms heartbeat (vs the 3000 ms
429  * default) triggers faster NACK-driven recovery of lost fragments over slower transport
430  * pipelines. A 3000 ms liveliness lease suits the slower cadence and Lifespan is
431  * infinite (-1); no Deadline is imposed because such streams are not necessarily
432  * periodic. The hundred-sample backlog only helps while the consumer can still drain
433  * it; on a saturated link it degenerates into retransmitting samples the reader has
434  * already fallen behind on, so prefer @c kBest (shallow backlog, real-time dispatch)
435  * whenever the producer can outrun the consumer.
436  */
437 [[maybe_unused]] static inline constexpr Qos kStream{
438  "stream",
439  true,
446  Qos::Ownership{},
447  Qos::Deadline{},
448  Qos::Lifespan{},
452 };
453 
454 /**
455  * @brief Reliable, KeepAll, TransientLocal, Sync, RealTime priority, express delivery.
456  *
457  * @details Designed for safety-critical alarms and fault events that must be delivered
458  * reliably and made available to late-joining subscribers. KeepAll plus TransientLocal
459  * latch the outstanding alarm set (retained up to the configured @c ResourceLimits — raise
460  * @c max_samples_per_instance for very bursty alarm sources), express + RealTime minimise
461  * dispatch latency, a tight 500 ms liveliness lease detects a dead annunciator, and Lifespan
462  * is infinite (-1) so an alarm stays valid until explicitly cleared; no Deadline is imposed
463  * because alarms are aperiodic.
464  */
465 [[maybe_unused]] static inline constexpr Qos kAlarm{
466  "alarm",
467  true,
474  Qos::Ownership{},
475  Qos::Deadline{},
476  Qos::Lifespan{},
480 };
481 
482 /**
483  * @brief Reliable, KeepLast(1), Volatile, Sync, RealTime priority.
484  *
485  * @details Designed for actuator and vehicle-control commands where only the most recent
486  * command is valid and delivery must be guaranteed with minimal latency. KeepLast(1) keeps
487  * just the latest order and a tight 500 ms liveliness lease detects a dead commander.
488  * Lifespan is infinite (-1), and no Deadline is imposed because commands are issued on
489  * demand rather than on a fixed cadence.
490  */
491 [[maybe_unused]] static inline constexpr Qos kCommand{
492  "command",
493  true,
500  Qos::Ownership{},
501  Qos::Deadline{},
502  Qos::Lifespan{},
506 };
507 
508 /**
509  * @brief Reliable, KeepLast(100), Volatile, ASync, Background priority.
510  *
511  * @details Designed for log and event streams that should be delivered reliably without
512  * stealing cycles from the data plane. KeepLast(100) buffers a short burst, asynchronous
513  * dispatch at Background priority keeps logging off the hot path, a relaxed 5000 ms
514  * liveliness lease suits the low cadence, and Lifespan is infinite (-1); no Deadline is
515  * imposed because log volume is bursty.
516  */
517 [[maybe_unused]] static inline constexpr Qos kLog{
518  "log",
519  true,
526  Qos::Ownership{},
527  Qos::Deadline{},
528  Qos::Lifespan{},
532 };
533 
534 /**
535  * @brief Returns the name-to-@c Qos lookup table containing every profile in this namespace.
536  *
537  * @details
538  * The map is keyed by profile name (e.g. @c "sensor", @c "event") and is safe to read
539  * concurrently from any thread once initialised.
540  *
541  * @return Constant reference to the global @c unordered_map<string, Qos>.
542  */
543 [[nodiscard]] VLINK_EXPORT const std::unordered_map<std::string, Qos>& get_available_qos_map() noexcept;
544 
545 } // namespace QosProfile
546 
547 } // namespace vlink
#define VLINK_EXPORT
Definition: macros.h:81
Quality of Service (QoS) policy aggregate for VLink publishers and subscribers.