subscriber.h File Reference

Read-side primitive of the VLink event communication model. More...

#include <memory>
#include <string>
#include <type_traits>
#include "./base/functional.h"
#include "./impl/subscriber_impl.h"
#include "./node.h"
#include "./internal/subscriber-inl.h"

Include dependency graph for subscriber.h:

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

Go to the source code of this file.

Classes
class	vlink::Subscriber< MsgT, SecT >
	Type-safe topic listener for the VLink event communication model. More...
class	vlink::SecuritySubscriber< MsgT >
	Convenience alias of Subscriber with per-message decryption enabled. More...

Namespaces
	vlink

Detailed Description

Read-side primitive of the VLink event communication model.

Subscriber<MsgT, SecT> attaches a callback to a VLink topic. Each frame delivered by the transport back-end is deserialised into a MsgT instance and forwarded to the user callback registered via listen(). Unlike Getter, the subscriber retains no value history – it simply forwards every event in delivery order.

The class is a thin, header-only template wrapper around SubscriberImpl. Codec dispatch is fully resolved at compile time using the type detected by Serializer::get_type_of<MsgT>().

Event-model Delivery Path

*   Transport Back-end                    Subscriber<MsgT>
*   ------------------                    -----------------
*      | inbound frame                          |
*      |--------------------------------------> |
*      |                                        |  Serializer::deserialize
*      |                                        |  (thread-local scratch)
*      |                                        |
*      |                                        |  optional MessageLoop hop
*      |                                        |
*      |                                        v
*      |                                  user callback(const MsgT&)
* 

Supported Message Types

Category	Example C++ Type	Serializer::Type	Notes
Raw bytes	Bytes	kBytesType	Pass-through to callback.
Protobuf value	MyProto	kProtoType	ParseFromArray path.
Protobuf pointer	MyProto*	kProtoPtrType	Needs bind_proto_arena.
FlatBuffers obj	MyTableT (NativeTable)	kFlatTableType	Object API.
FlatBuffers ptr	MyTable*	kFlatPtrType	Zero-copy view of buffer.
DDS CDR	type with deserialize(Cdr&)	kCdrType	DDS fast path.
POD struct	trivial standard-layout type	kStandardType	sizeof(T) byte copy.
UTF-8 text	std::string	kStringType	Length-prefixed.
Custom	type with operator>>/<<	kCustomType	User-supplied codec.

Basic Listen Example

vlink::Subscriber<MyMsg> sub("dds://vehicle/speed");
sub.listen([](const MyMsg& msg) { handle(msg); });

Callback Dispatch via MessageLoop

vlink::MessageLoop loop;
vlink::Subscriber<MyMsg> sub("dds://vehicle/speed", vlink::InitType::kWithoutInit);
sub.attach(&loop);
sub.init();
sub.listen([](const MyMsg& m) { handle(m); });
loop.run();

Zero-copy Intra Transport

When MsgT is a shared pointer whose element_type derives from IntraDataType (generated via VLINK_INTRA_DATA_DECLARE) and the URL scheme is intra://, the shared pointer is forwarded zero-copy to the callback without serialisation:

VLINK_INTRA_DATA_DECLARE(MyProtoMsg, MyIntra)
vlink::Subscriber<MyIntra> sub("intra://my_topic");
sub.listen([](const MyIntra& data) { use(data); });

Latency and Sample-loss Tracking

vlink::Subscriber<MyMsg> sub("dds://my_topic");
sub.set_latency_and_lost_enabled(true);
auto latency_ns = sub.get_latency();
auto stats = sub.get_lost();

Warning

The deserialised callback argument is backed by thread_local scratch storage and is overwritten on the next delivery. Copy the value before storing it outside the callback scope. This warning does not apply to Bytes or IntraData arguments, which are owned by value or by shared pointer.

Note

Calling listen() more than once is a fatal error. The subscriber must be initialised (either by InitType::kWithInit or by explicit init()) before listen() is called.

See also

publisher.h, node.h, serializer.h, base/message_loop.h