VLink  2.0.0
A high-performance communication middleware
vlink.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 vlink.h
26  * @brief Single umbrella entry point for the public VLink communication SDK.
27  *
28  * @details
29  * Including @c <vlink/vlink.h> pulls in every primitive of the three VLink
30  * communication models together with the @c MessageLoop dispatcher and a small
31  * set of base utilities. Application code should rarely need to include any
32  * other VLink header directly; transport-specific configuration types are
33  * brought in transitively through the primitive headers.
34  *
35  * @par Pulled-in Headers and Mapped Primitives
36  * | Header | Public Primitive(s) | Model | Role |
37  * | ----------------------- | ---------------------------------- | --------- | -------------------------- |
38  * | @c client.h | @c Client<ReqT,RespT> | Method | RPC caller side |
39  * | @c server.h | @c Server<ReqT,RespT> | Method | RPC handler side |
40  * | @c publisher.h | @c Publisher<MsgT> | Event | Topic emitter |
41  * | @c subscriber.h | @c Subscriber<MsgT> | Event | Topic listener |
42  * | @c getter.h | @c Getter<ValueT> | Field | Latest-value reader |
43  * | @c setter.h | @c Setter<ValueT> | Field | Latest-value writer |
44  * | @c base/message_loop.h | @c MessageLoop | Dispatch | Callback re-routing |
45  * | @c base/utils.h | @c sleep_for, env helpers, etc. | Utilities | General-purpose helpers |
46  *
47  * @par Three Communication Models Side-by-side
48  * @verbatim
49  * +----------------------+ +-----------------------+ +-------------------------+
50  * | EVENT MODEL | | METHOD MODEL | | FIELD MODEL |
51  * | (pub/sub stream) | | (request/response) | | (latest-value sync) |
52  * +----------------------+ +-----------------------+ +-------------------------+
53  * | Publisher<MsgT> | | Client<Req,Resp> | | Setter<ValueT> |
54  * | | | | | | | | |
55  * | v publish() | | v invoke() | | v set() |
56  * | transport | | transport | | transport |
57  * | | | | | | | (retains latest) |
58  * | v | | v | | | |
59  * | Subscriber<MsgT> | | Server<Req,Resp> | | v |
60  * | on each msg | | handler fills resp | | Getter<ValueT> |
61  * | | | | | | get() / listen() |
62  * | | | v reply | | |
63  * | | | Client receives | | |
64  * +----------------------+ +-----------------------+ +-------------------------+
65  * @endverbatim
66  *
67  * @par Transport Selection via URL Prefix
68  * The transport back-end is selected by the URL scheme. All API calls remain
69  * identical when the prefix is changed; this is the central design tenet of
70  * VLink.
71  *
72  * | Prefix | Back-end | Typical use case |
73  * | -------------- | --------------------------------- | -------------------------------------- |
74  * | @c intra:// | In-process pub/sub | Same-process zero-copy fan-out |
75  * | @c shm:// | Iceoryx shared memory | Inter-process zero-copy on one host |
76  * | @c shm2:// | Native VLink shared memory | Lightweight inter-process IPC |
77  * | @c dds:// | FastDDS (CDR) | Standards-compliant DDS distribution |
78  * | @c ddsc:// | CycloneDDS | CycloneDDS-based deployments |
79  * | @c ddsr:// | RTI Connext DDS | RTI-licensed deployments |
80  * | @c ddst:// | TravoDDS | TravoDDS-based deployments |
81  * | @c zenoh:// | Eclipse Zenoh | Pub/sub-storage-query, edge to cloud |
82  * | @c someip:// | SOME/IP | Automotive AUTOSAR adaptive services |
83  * | @c fdbus:// | FDBus | Linux/Android service bus |
84  * | @c qnx:// | QNX native IPC | QNX safety-critical platforms |
85  * | @c mqtt:// | MQTT | Telemetry to cloud brokers |
86  *
87  * @par Quick-start Example -- one process, three models
88  * @code
89  * #include <vlink/vlink.h>
90  *
91  * // ---- Event model ---------------------------------------------------------
92  * vlink::Subscriber<MyMsg> sub("dds://vehicle/speed");
93  * sub.listen([](const MyMsg& msg) { handle_event(msg); });
94  *
95  * vlink::Publisher<MyMsg> pub("dds://vehicle/speed");
96  * pub.publish(MyMsg{100});
97  *
98  * // ---- Method model (synchronous RPC) -------------------------------------
99  * vlink::Server<Req, Resp> svr("dds://compute/sum");
100  * svr.listen([](const Req& q, Resp& r) { r.value = q.a + q.b; });
101  *
102  * vlink::Client<Req, Resp> cli("dds://compute/sum");
103  * Resp r;
104  * if (cli.invoke(Req{1, 2}, r)) { use(r); }
105  *
106  * // ---- Field model (latest-value sync) ------------------------------------
107  * vlink::Setter<int> setter("shm://vehicle/gear");
108  * setter.set(3);
109  *
110  * vlink::Getter<int> getter("shm://vehicle/gear");
111  * if (auto gear = getter.get()) { use(*gear); }
112  * @endcode
113  *
114  * @note Each primitive has a @c Security* counterpart (@c SecurityPublisher,
115  * @c SecuritySubscriber, @c SecurityClient, @c SecurityServer,
116  * @c SecuritySetter, @c SecurityGetter) that transparently encrypts and
117  * decrypts the payload using a @c Security::Config aggregate.
118  *
119  * @see publisher.h, subscriber.h, client.h, server.h, getter.h, setter.h
120  */
121 
122 #pragma once
123 
124 // NOLINTBEGIN
125 
126 // method
127 #include "./client.h"
128 #include "./server.h"
129 
130 // event
131 #include "./publisher.h"
132 #include "./subscriber.h"
133 
134 // field
135 #include "./getter.h"
136 #include "./setter.h"
137 
138 // message_loop
139 #include "./base/message_loop.h"
140 
141 // utils
142 #include "./base/utils.h"
143 
144 // NOLINTEND
client.h
Caller-side primitive of the VLink method (RPC) communication model.
getter.h
Read-side primitive of the VLink field communication model.
message_loop.h
Single-threaded task dispatcher with three queue backends, timers and scheduling envelopes.
publisher.h
Write-side primitive of the VLink event communication model.
server.h
Handler-side primitive of the VLink method (RPC) communication model.
setter.h
Write-side primitive of the VLink field communication model.
subscriber.h
Read-side primitive of the VLink event communication model.
utils.h
Portable host-system utility surface used across the VLink runtime.