VLink  2.3.0
A high-performance communication middleware
shm2_conf.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 shm2_conf.h
26  * @brief Transport configuration for the @c shm2:// Iceoryx2 (next-generation) shared-memory transport.
27  *
28  * @details
29  * @c Shm2Conf binds the @c shm2:// URL scheme to the Iceoryx2 shared-memory
30  * transport, the next-generation successor to the @c shm:// Iceoryx backend.
31  * Iceoryx2 keeps the zero-copy semantics of its predecessor but eliminates the
32  * standalone RouDi daemon: every participating process maps the shared-memory
33  * service directly. This simplifies deployment in containerised and read-only
34  * root-filesystem environments while preserving the same loan / release flow.
35  *
36  * @par Shared-Memory Layout
37  * @code
38  * Iceoryx2 service (file-backed POSIX SHM segment)
39  * +-----------------------------------------------+
40  * | Per-publisher pool of dynamic payload slots |
41  * | +------+ +------+ +------+ +------+ +------+ |
42  * | | slot | | slot | | slot | | slot | | ... | |
43  * | +------+ +------+ +------+ +------+ +------+ |
44  * +--------^--------------------------^-----------+
45  * | loan() | release()
46  * | |
47  * Publisher process Subscriber process
48  * @endcode
49  *
50  * @par Loan / Release Flow
51  * @code
52  * Publisher: slot = loan(size); fill(slot); publish(slot);
53  * \
54  * \--> per-subscriber notification queue
55  * \
56  * Subscriber: slot = take(); \--> slot arrival
57  * consume(slot); release(slot);
58  * @endcode
59  *
60  * @par Supported Node Types
61  *
62  * | Publisher | Subscriber | Server | Client | Getter | Setter |
63  * | :-------: | :--------: | :----: | :----: | :----: | :----: |
64  * | yes | yes | yes | yes | yes | yes |
65  *
66  * @par URL Format
67  * @code
68  * shm2://<address>[?event=<name>&domain=<N>&depth=<N>&history=<N>&wait=<ms>][#<size>]
69  * @endcode
70  *
71  * | Component | Description |
72  * | ---------- | ---------------------------------------------------------------------- |
73  * | @c address | Iceoryx2 service/topic name (URL host concatenated with path) |
74  * | @c event | Optional secondary event name (@c ?event=) |
75  * | @c domain | Domain ID (@c ?domain=); defaults to @c 0 |
76  * | @c depth | Queue / loan capacity override; @c 0 uses the Iceoryx2 default |
77  * | @c history | History count; URL default @c 0, or @c 1 for field nodes |
78  * | @c wait | Blocking-wait timeout in ms; pub/sub only |
79  * | @c size | Initial payload capacity from URL fragment (see size syntax below) |
80  *
81  * @par Size Fragment Syntax
82  * The URL fragment selects the initial payload capacity. Dynamic allocation can
83  * accommodate larger messages; this is not a message-size limit. Supported
84  * suffixes are case-insensitive: @c B, @c K/@c KB, @c M/@c MB, @c G/@c GB. The
85  * value must fall in @c (0, @c kMaxMemSize].
86  * @code
87  * shm2://my_topic#1M // initial payload capacity: 1 MiB
88  * shm2://my_topic#512K // initial payload capacity: 512 KiB
89  * shm2://my_topic // initial payload capacity: 4 KiB
90  * @endcode
91  *
92  * @par Backend-Specific Options
93  *
94  * | Option | Purpose | Default |
95  * | ------------------- | -------------------------------------------------- | --------------- |
96  * | @c size | Initial payload capacity | @c 4 KiB |
97  * | @c kMaxMemSize | Hard upper bound on @c size | @c 32 MiB |
98  * | @c depth | Slot pool capacity | backend default |
99  * | @c history | Late-joining replay count | @c 0 / @c 1 |
100  *
101  * @note Compiled only when @c VLINK_SUPPORT_SHM2 is defined.
102  * @note @c address and @c event must each be at most 80 characters long.
103  * @note @c wait mode is only valid for @c kPublisher / @c kSubscriber endpoints;
104  * using it with RPC or field nodes causes @c parse_protocol() to return @c false.
105  * @note @c is_valid() additionally requires @c size in @c (0, @c kMaxMemSize] and
106  * @c domain, @c depth, @c history to be non-negative.
107  */
108 
109 #pragma once
110 
111 #ifdef VLINK_SUPPORT_SHM2
112 
113 #include <cstdint>
114 #include <string>
115 
116 #include "../impl/conf.h"
117 
118 namespace vlink {
119 
120 /**
121  * @struct Shm2Conf
122  * @brief Concrete @c Conf describing an Iceoryx2 endpoint addressed by an @c shm2:// URL.
123  *
124  * @details
125  * Extends the @c ShmConf field set with a @c size parameter that controls the
126  * initial payload capacity used by the Iceoryx2 dynamic allocator.
127  */
128 struct VLINK_EXPORT Shm2Conf final : public Conf {
129  std::string address; ///< Iceoryx2 service/topic address (URL host plus path); maximum 80 characters.
130  std::string event; ///< Optional secondary event name; maximum 80 characters.
131  int32_t domain{0}; ///< Domain identifier (non-negative).
132  int32_t depth{0}; ///< Queue / loan capacity override; @c 0 keeps the Iceoryx2 default.
133  int32_t history{0}; ///< History count; URL parsing defaults to @c 0, or @c 1 for setter / getter nodes.
134  int32_t wait{0}; ///< Blocking-wait timeout in milliseconds; positive values enable pub/sub wait mode.
135  uint64_t size{kDefaultMemSize}; ///< Initial shared-memory payload capacity in bytes.
136 
137  /**
138  * @brief Builds a @c Shm2Conf from its seven logical fields.
139  *
140  * @param _address Service/topic address string; maximum 80 characters.
141  * @param _event Optional event name; maximum 80 characters; empty by default.
142  * @param _domain Domain identifier; defaults to @c 0.
143  * @param _depth Queue / loan capacity override; defaults to @c 0.
144  * @param _history History count; defaults to @c 0.
145  * @param _wait Blocking-wait timeout in ms; defaults to @c 0 (disabled).
146  * @param _size Initial payload capacity in bytes; defaults to @c kDefaultMemSize (4 KiB).
147  */
148  explicit Shm2Conf(const std::string& _address, const std::string& _event = "", int32_t _domain = 0,
149  int32_t _depth = 0, int32_t _history = 0, int32_t _wait = 0, uint64_t _size = kDefaultMemSize);
150 
151  /**
152  * @brief Component-wise equality on all configuration fields.
153  *
154  * @param conf Configuration to compare with.
155  * @return @c true when all seven fields match.
156  */
157  [[nodiscard]] bool operator==(const Shm2Conf& conf) const noexcept;
158 
159  /**
160  * @brief Logical negation of @c operator==.
161  *
162  * @param conf Configuration to compare with.
163  * @return @c true when any field differs from @p conf.
164  */
165  [[nodiscard]] bool operator!=(const Shm2Conf& conf) const noexcept;
166 
167  /**
168  * @brief Reports this object's transport tag.
169  *
170  * @return @c TransportType::kShm2.
171  */
172  [[nodiscard]] TransportType get_transport_type() const override;
173 
174  static constexpr size_t kDefaultMemSize = 4096U; ///< Default initial payload capacity: 4 KiB.
175  static constexpr size_t kMaxMemSize = 1024UL * 1024UL * 32; ///< Upper bound on configured initial capacity: 32 MiB.
176 
177 #ifndef VLINK_ENABLE_C_INTERFACE
179 #endif
181  VLINK_CONF_IMPL(Shm2Conf)
182 };
183 
184 ////////////////////////////////////////////////////////////////
185 /// Details
186 ////////////////////////////////////////////////////////////////
187 
188 inline Shm2Conf::Shm2Conf(const std::string& _address, const std::string& _event, int32_t _domain, int32_t _depth,
189  int32_t _history, int32_t _wait, uint64_t _size)
190  : address(_address), event(_event), domain(_domain), depth(_depth), history(_history), wait(_wait), size(_size) {}
191 
192 inline bool Shm2Conf::operator==(const Shm2Conf& conf) const noexcept {
193  return address == conf.address && event == conf.event && domain == conf.domain && depth == conf.depth &&
194  history == conf.history && wait == conf.wait && size == conf.size;
195 }
196 
197 inline bool Shm2Conf::operator!=(const Shm2Conf& conf) const noexcept { return !(*this == conf); }
198 
199 inline TransportType Shm2Conf::get_transport_type() const { return TransportType::kShm2; }
200 
201 } // namespace vlink
202 
203 #endif
#define VLINK_CONF_IMPL(classname)
Convenience macro that emits the standard concrete conf boilerplate.
Definition: conf.h:250
#define VLINK_DECLARE_GLOBAL_PROPERTY()
Declares per-transport static configuration storage and access helpers.
Definition: conf.h:308
#define VLINK_ALLOW_IMPL_TYPE(type)
Records the bitmask of ImplType values supported by a conf.
Definition: conf.h:291
#define VLINK_EXPORT
Definition: macros.h:81