status.h File Reference

DDS-aligned status event hierarchy delivered to publisher and subscriber callbacks. More...

#include <cstdint>
#include <iostream>
#include <memory>
#include <string>
#include <type_traits>
#include "../base/exception.h"
#include "../base/macros.h"

Include dependency graph for status.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	vlink::Status::Base
	Polymorphic base for every concrete status event delivered to a callback. More...
struct	vlink::Status::Unknown
	Placeholder event emitted when the transport reports a status the runtime cannot map. More...

Namespaces
	vlink
	vlink::Status
	DDS-aligned status enumeration, base event class, and helper predicates.

Typedefs
using	vlink::Status::InstanceHandle = const void *
	Opaque transport-defined identifier for a matched publication or subscription. More...
using	vlink::Status::BasePtr = std::shared_ptr< Status::Base >
	Shared-pointer alias used as the parameter type of every status callback. More...

Enumerations
enum	vlink::Status::Type : uint8_t {   vlink::Status::kUnknown = 0 , vlink::Status::kPublicationMatched = 1 , vlink::Status::kOfferedDeadlineMissed = 2 , vlink::Status::kOfferedIncompatibleQos = 3 ,   vlink::Status::kLivelinessLost = 4 , vlink::Status::kSubscriptionMatched = 5 , vlink::Status::kRequestedDeadlineMissed = 6 , vlink::Status::kLivelinessChanged = 7 ,   vlink::Status::kSampleRejected = 8 , vlink::Status::kRequestedIncompatibleQos = 9 , vlink::Status::kSampleLost = 10 }
	Discriminator that identifies the concrete Base subclass carried by an event. More...

Functions
VLINK_EXPORT std::ostream &	vlink::Status::operator<< (std::ostream &ostream, const BasePtr &status) noexcept
	Writes the human-readable description of status to ostream. More...

Detailed Description

DDS-aligned status event hierarchy delivered to publisher and subscriber callbacks.

The Status namespace exposes a polymorphic, shared-pointer based event model that mirrors the DDS status change notification system. When the underlying transport (DDS, intra, shm, zenoh, etc.) detects an interesting condition it constructs a concrete Base subclass and forwards it to the user-registered StatusCallback. Callers use Base::as<T>() to safely narrow the pointer to the concrete type carried by the event.

Status codes

Value	Enumerator	Side	Triggered when
0	kUnknown	-	transport reports an unrecognised status type
1	kPublicationMatched	writer	matching subscriber appeared or disappeared
2	kOfferedDeadlineMissed	writer	offered publication deadline missed
3	kOfferedIncompatibleQos	writer	discovered subscriber with incompatible QoS
4	kLivelinessLost	writer	writer failed to assert liveliness within lease
5	kSubscriptionMatched	reader	matching publisher appeared or disappeared
6	kRequestedDeadlineMissed	reader	reader missed its requested deadline
7	kLivelinessChanged	reader	matched publisher liveliness state changed
8	kSampleRejected	reader	inbound sample dropped (resource limit)
9	kRequestedIncompatibleQos	reader	discovered publisher with incompatible QoS
10	kSampleLost	reader	sample lost before delivery

Severity matrix

Status	Severity	Action recommended
kPublicationMatched	informational	log peer count change
kSubscriptionMatched	informational	log peer count change
kLivelinessChanged	informational	track alive_count delta
kOfferedDeadlineMissed	warning	investigate slow publisher loop
kRequestedDeadlineMissed	warning	investigate dropped traffic
kOfferedIncompatibleQos	warning	reconcile QoS profile with peer
kRequestedIncompatibleQos	warning	reconcile QoS profile with peer
kSampleRejected	error	enlarge ResourceLimits or drop sources
kSampleLost	error	enlarge History depth or upgrade reliability
kLivelinessLost	error	peer considers writer dead; restore heartbeats

Concrete event structs and their counter / handle fields live in status_detail.h.

Example

auto sub = vlink::Subscriber<MyMsg>::create("dds://my/topic");
 
sub->register_status_callback([](vlink::Status::BasePtr status) {
  switch (status->get_type()) {
    case vlink::Status::kSubscriptionMatched: {
      auto detail = status->as<vlink::Status::SubscriptionMatched>();
      VLOG_I("matched publishers: ", detail->current_count);
      break;
    }
    case vlink::Status::kSampleLost: {
      auto detail = status->as<vlink::Status::SampleLost>();
      VLOG_W("samples lost so far: ", detail->total_count);
      break;
    }
    default:
      break;
  }
});