WPILibC++ 2024.3.2
UnitTopic.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#pragma once
6
7#include <stdint.h>
8
9#include <span>
10#include <string_view>
11#include <vector>
12
13#include <wpi/json_fwd.h>
14
15#include "networktables/Topic.h"
16#include "ntcore_cpp.h"
17
18namespace nt {
19
20template <typename T>
21class UnitTopic;
22
23/**
24 * Timestamped unit.
25 *
26 * @tparam T unit type, e.g. units::meter_t
27 */
28template <typename T>
30 TimestampedUnit() = default;
31 TimestampedUnit(int64_t time, int64_t serverTime, T value)
33
34 /**
35 * Time in local time base.
36 */
37 int64_t time = 0;
38
39 /**
40 * Time in server time base. May be 0 or 1 for locally set values.
41 */
42 int64_t serverTime = 0;
43
44 /**
45 * Value.
46 */
47 T value = {};
48};
49
50/**
51 * NetworkTables unit-typed subscriber.
52 *
53 * @tparam T unit type, e.g. units::meter_t
54 */
55template <typename T>
56class UnitSubscriber : public Subscriber {
57 public:
59 using ValueType = T;
60 using ParamType = T;
62
63 UnitSubscriber() = default;
64
65 /**
66 * Construct from a subscriber handle; recommended to use
67 * UnitTopic::Subscribe() instead.
68 *
69 * @param handle Native handle
70 * @param defaultValue Default value
71 */
72 UnitSubscriber(NT_Subscriber handle, ParamType defaultValue);
73
74 /**
75 * Get the last published value.
76 * If no value has been published, returns the stored default value.
77 *
78 * @return value
79 */
80 ValueType Get() const;
81
82 /**
83 * Get the last published value.
84 * If no value has been published, returns the passed defaultValue.
85 *
86 * @param defaultValue default value to return if no value has been published
87 * @return value
88 */
89 ValueType Get(ParamType defaultValue) const;
90
91 /**
92 * Get the last published value along with its timestamp
93 * If no value has been published, returns the stored default value and a
94 * timestamp of 0.
95 *
96 * @return timestamped value
97 */
99
100 /**
101 * Get the last published value along with its timestamp.
102 * If no value has been published, returns the passed defaultValue and a
103 * timestamp of 0.
104 *
105 * @param defaultValue default value to return if no value has been published
106 * @return timestamped value
107 */
108 TimestampedValueType GetAtomic(ParamType defaultValue) const;
109
110 /**
111 * Get an array of all value changes since the last call to ReadQueue.
112 * Also provides a timestamp for each value.
113 *
114 * @note The "poll storage" subscribe option can be used to set the queue
115 * depth.
116 *
117 * @return Array of timestamped values; empty array if no new changes have
118 * been published since the previous call.
119 */
120 std::vector<TimestampedValueType> ReadQueue();
121
122 /**
123 * Get the corresponding topic.
124 *
125 * @return Topic
126 */
127 TopicType GetTopic() const;
128
129 private:
130 ValueType m_defaultValue;
131};
132
133/**
134 * NetworkTables unit-typed publisher.
135 *
136 * @tparam T unit type, e.g. units::meter_t
137 */
138template <typename T>
139class UnitPublisher : public Publisher {
140 public:
142 using ValueType = T;
143 using ParamType = T;
144
146
147 UnitPublisher() = default;
148
149 /**
150 * Construct from a publisher handle; recommended to use
151 * UnitTopic::Publish() instead.
152 *
153 * @param handle Native handle
154 */
155 explicit UnitPublisher(NT_Publisher handle);
156
157 /**
158 * Publish a new value.
159 *
160 * @param value value to publish
161 * @param time timestamp; 0 indicates current NT time should be used
162 */
163 void Set(ParamType value, int64_t time = 0);
164
165 /**
166 * Publish a default value.
167 * On reconnect, a default value will never be used in preference to a
168 * published value.
169 *
170 * @param value value
171 */
172 void SetDefault(ParamType value);
173
174 /**
175 * Get the corresponding topic.
176 *
177 * @return Topic
178 */
179 TopicType GetTopic() const;
180};
181
182/**
183 * NetworkTables unit-typed entry.
184 *
185 * @note Unlike NetworkTableEntry, the entry goes away when this is destroyed.
186 *
187 * @tparam T unit type, e.g. units::meter_t
188 */
189template <typename T>
190class UnitEntry final : public UnitSubscriber<T>, public UnitPublisher<T> {
191 public:
195 using ValueType = T;
196 using ParamType = T;
197
199
200 UnitEntry() = default;
201
202 /**
203 * Construct from an entry handle; recommended to use
204 * UnitTopic::GetEntry() instead.
205 *
206 * @param handle Native handle
207 * @param defaultValue Default value
208 */
209 UnitEntry(NT_Entry handle, ParamType defaultValue);
210
211 /**
212 * Determines if the native handle is valid.
213 *
214 * @return True if the native handle is valid, false otherwise.
215 */
216 explicit operator bool() const { return this->m_subHandle != 0; }
217
218 /**
219 * Gets the native handle for the entry.
220 *
221 * @return Native handle
222 */
223 NT_Entry GetHandle() const { return this->m_subHandle; }
224
225 /**
226 * Get the corresponding topic.
227 *
228 * @return Topic
229 */
230 TopicType GetTopic() const;
231
232 /**
233 * Stops publishing the entry if it's published.
234 */
235 void Unpublish();
236};
237
238/**
239 * NetworkTables unit-typed topic. Publishers publish the type name (e.g.
240 * "meter") as the "unit" property. Type conversions are not performed--for
241 * correct behavior the publisher and subscriber must use the same unit type,
242 * but this can be checked at runtime using IsMatchingUnit().
243 *
244 * @tparam T unit type, e.g. units::meter_t
245 */
246template <typename T>
247class UnitTopic final : public Topic {
248 public:
252 using ValueType = T;
253 using ParamType = T;
255 /** The default type string for this topic type. */
256 static constexpr std::string_view kTypeString = "double";
257
258 UnitTopic() = default;
259
260 /**
261 * Construct from a topic handle.
262 *
263 * @param handle Native handle
264 */
265 explicit UnitTopic(NT_Topic handle) : Topic{handle} {}
266
267 /**
268 * Construct from a generic topic.
269 *
270 * @param topic Topic
271 */
272 explicit UnitTopic(Topic topic) : Topic{topic} {}
273
274 /**
275 * Verify the topic has a matching unit type (if the topic is published).
276 *
277 * @return True if unit matches, false if not matching or topic not published.
278 */
279 bool IsMatchingUnit() const;
280
281 /**
282 * Create a new subscriber to the topic.
283 *
284 * <p>The subscriber is only active as long as the returned object
285 * is not destroyed.
286 *
287 * @note Subscribers that do not match the published data type do not return
288 * any values. To determine if the data type matches, use the appropriate
289 * Topic functions.
290 *
291 * @param defaultValue default value used when a default is not provided to a
292 * getter function
293 * @param options subscribe options
294 * @return subscriber
295 */
296 [[nodiscard]]
298 ParamType defaultValue,
299 const PubSubOptions& options = kDefaultPubSubOptions);
300
301 /**
302 * Create a new subscriber to the topic, with specific type string.
303 *
304 * <p>The subscriber is only active as long as the returned object
305 * is not destroyed.
306 *
307 * @note Subscribers that do not match the published data type do not return
308 * any values. To determine if the data type matches, use the appropriate
309 * Topic functions.
310 *
311 * @param typeString type string
312 * @param defaultValue default value used when a default is not provided to a
313 * getter function
314 * @param options subscribe options
315 * @return subscriber
316 */
317 [[nodiscard]]
319 std::string_view typeString, ParamType defaultValue,
320 const PubSubOptions& options = kDefaultPubSubOptions);
321
322 /**
323 * Create a new publisher to the topic.
324 *
325 * The publisher is only active as long as the returned object
326 * is not destroyed.
327 *
328 * @note It is not possible to publish two different data types to the same
329 * topic. Conflicts between publishers are typically resolved by the
330 * server on a first-come, first-served basis. Any published values that
331 * do not match the topic's data type are dropped (ignored). To determine
332 * if the data type matches, use the appropriate Topic functions.
333 *
334 * @param options publish options
335 * @return publisher
336 */
337 [[nodiscard]]
339
340 /**
341 * Create a new publisher to the topic, with type string and initial
342 * properties.
343 *
344 * The publisher is only active as long as the returned object
345 * is not destroyed.
346 *
347 * @note It is not possible to publish two different data types to the same
348 * topic. Conflicts between publishers are typically resolved by the
349 * server on a first-come, first-served basis. Any published values that
350 * do not match the topic's data type are dropped (ignored). To determine
351 * if the data type matches, use the appropriate Topic functions.
352 *
353 * @param typeString type string
354 * @param properties JSON properties
355 * @param options publish options
356 * @return publisher
357 */
358 [[nodiscard]]
360 const wpi::json& properties,
361 const PubSubOptions& options = kDefaultPubSubOptions);
362
363 /**
364 * Create a new entry for the topic.
365 *
366 * Entries act as a combination of a subscriber and a weak publisher. The
367 * subscriber is active as long as the entry is not destroyed. The publisher
368 * is created when the entry is first written to, and remains active until
369 * either Unpublish() is called or the entry is destroyed.
370 *
371 * @note It is not possible to use two different data types with the same
372 * topic. Conflicts between publishers are typically resolved by the
373 * server on a first-come, first-served basis. Any published values that
374 * do not match the topic's data type are dropped (ignored), and the entry
375 * will show no new values if the data type does not match. To determine
376 * if the data type matches, use the appropriate Topic functions.
377 *
378 * @param defaultValue default value used when a default is not provided to a
379 * getter function
380 * @param options publish and/or subscribe options
381 * @return entry
382 */
383 [[nodiscard]]
384 EntryType GetEntry(ParamType defaultValue,
385 const PubSubOptions& options = kDefaultPubSubOptions);
386
387 /**
388 * Create a new entry for the topic, with specific type string.
389 *
390 * Entries act as a combination of a subscriber and a weak publisher. The
391 * subscriber is active as long as the entry is not destroyed. The publisher
392 * is created when the entry is first written to, and remains active until
393 * either Unpublish() is called or the entry is destroyed.
394 *
395 * @note It is not possible to use two different data types with the same
396 * topic. Conflicts between publishers are typically resolved by the
397 * server on a first-come, first-served basis. Any published values that
398 * do not match the topic's data type are dropped (ignored), and the entry
399 * will show no new values if the data type does not match. To determine
400 * if the data type matches, use the appropriate Topic functions.
401 *
402 * @param typeString type string
403 * @param defaultValue default value used when a default is not provided to a
404 * getter function
405 * @param options publish and/or subscribe options
406 * @return entry
407 */
408 [[nodiscard]]
409 EntryType GetEntryEx(std::string_view typeString, ParamType defaultValue,
410 const PubSubOptions& options = kDefaultPubSubOptions);
411};
412
413} // namespace nt
414
NetworkTables publisher.
Definition: Topic.h:364
NetworkTables subscriber.
Definition: Topic.h:309
NT_Subscriber m_subHandle
Definition: Topic.h:360
NetworkTables Topic.
Definition: Topic.h:28
NetworkTables unit-typed entry.
Definition: UnitTopic.h:190
UnitEntry()=default
void Unpublish()
Stops publishing the entry if it's published.
Definition: UnitTopic.inc:86
NT_Entry GetHandle() const
Gets the native handle for the entry.
Definition: UnitTopic.h:223
TopicType GetTopic() const
Get the corresponding topic.
Definition: UnitTopic.inc:81
UnitTopic< T > TopicType
Definition: UnitTopic.h:194
NetworkTables unit-typed publisher.
Definition: UnitTopic.h:139
UnitPublisher()=default
void Set(ParamType value, int64_t time=0)
Publish a new value.
Definition: UnitTopic.inc:62
void SetDefault(ParamType value)
Publish a default value.
Definition: UnitTopic.inc:67
TopicType GetTopic() const
Get the corresponding topic.
Definition: UnitTopic.inc:72
T ParamType
Definition: UnitTopic.h:143
T ValueType
Definition: UnitTopic.h:142
NetworkTables unit-typed subscriber.
Definition: UnitTopic.h:56
TopicType GetTopic() const
Get the corresponding topic.
Definition: UnitTopic.inc:53
TimestampedValueType GetAtomic() const
Get the last published value along with its timestamp If no value has been published,...
Definition: UnitTopic.inc:32
ValueType Get() const
Get the last published value.
Definition: UnitTopic.inc:22
std::vector< TimestampedValueType > ReadQueue()
Get an array of all value changes since the last call to ReadQueue.
Definition: UnitTopic.inc:43
UnitSubscriber()=default
T ValueType
Definition: UnitTopic.h:59
T ParamType
Definition: UnitTopic.h:60
NetworkTables unit-typed topic.
Definition: UnitTopic.h:247
UnitEntry< T > EntryType
Definition: UnitTopic.h:251
bool IsMatchingUnit() const
Verify the topic has a matching unit type (if the topic is published).
Definition: UnitTopic.inc:91
PublisherType Publish(const PubSubOptions &options=kDefaultPubSubOptions)
Create a new publisher to the topic.
Definition: UnitTopic.inc:110
SubscriberType Subscribe(ParamType defaultValue, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new subscriber to the topic.
Definition: UnitTopic.inc:96
static constexpr std::string_view kTypeString
The default type string for this topic type.
Definition: UnitTopic.h:256
PublisherType PublishEx(std::string_view typeString, const wpi::json &properties, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new publisher to the topic, with type string and initial properties.
Definition: UnitTopic.inc:116
T ValueType
Definition: UnitTopic.h:252
UnitTopic(NT_Topic handle)
Construct from a topic handle.
Definition: UnitTopic.h:265
SubscriberType SubscribeEx(std::string_view typeString, ParamType defaultValue, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new subscriber to the topic, with specific type string.
Definition: UnitTopic.inc:103
UnitTopic()=default
UnitTopic(Topic topic)
Construct from a generic topic.
Definition: UnitTopic.h:272
UnitSubscriber< T > SubscriberType
Definition: UnitTopic.h:249
T ParamType
Definition: UnitTopic.h:253
EntryType GetEntryEx(std::string_view typeString, ParamType defaultValue, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new entry for the topic, with specific type string.
Definition: UnitTopic.inc:133
EntryType GetEntry(ParamType defaultValue, const PubSubOptions &options=kDefaultPubSubOptions)
Create a new entry for the topic.
Definition: UnitTopic.inc:126
UnitPublisher< T > PublisherType
Definition: UnitTopic.h:250
basic_string_view< char > string_view
Definition: core.h:501
NT_Handle NT_Topic
Definition: ntcore_c.h:40
NT_Handle NT_Subscriber
Definition: ntcore_c.h:41
NT_Handle NT_Publisher
Definition: ntcore_c.h:42
NT_Handle NT_Entry
Definition: ntcore_c.h:35
constexpr PubSubOptions kDefaultPubSubOptions
Default publish/subscribe options.
Definition: ntcore_cpp.h:390
NetworkTables (ntcore) namespace.
Definition: ntcore_cpp.h:36
NetworkTables publish/subscribe options.
Definition: ntcore_cpp.h:305
Timestamped unit.
Definition: UnitTopic.h:29
int64_t time
Time in local time base.
Definition: UnitTopic.h:37
int64_t serverTime
Time in server time base.
Definition: UnitTopic.h:42
TimestampedUnit(int64_t time, int64_t serverTime, T value)
Definition: UnitTopic.h:31
TimestampedUnit()=default
T value
Value.
Definition: UnitTopic.h:47