GCC Code Coverage Report

Directory: ./
File: include/pdcom5/Subscription.h
Date: 2024-03-27 13:09:52
Exec Total Coverage
Lines: 4 4 100.0%
Branches: 0 0 -%
Line Branch Exec Source
1 /*****************************************************************************
2 * vim:tw=78
3 *
4 * Copyright (C) 2021 Richard Hacker (lerichi at gmx dot net),
5 * Florian Pose (fp at igh dot de),
6 * Bjarne von Horn (vh at igh dot de).
7 *
8 * This file is part of the PdCom library.
9 *
10 * The PdCom library is free software: you can redistribute it and/or modify
11 * it under the terms of the GNU Lesser General Public License as published by
12 * the Free Software Foundation, either version 3 of the License, or (at your
13 * option) any later version.
14 *
15 * The PdCom library is distributed in the hope that it will be useful, but
16 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
17 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
18 * License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public License
21 * along with the PdCom library. If not, see <http://www.gnu.org/licenses/>.
22 *
23 ****************************************************************************/
24
25 /** @file */
26
27 #ifndef PDCOM5_SUBSCRIPTION_H
28 #define PDCOM5_SUBSCRIPTION_H
29
30 #include "DataDeserializer.h"
31 #include "Exception.h"
32 #include "Selector.h"
33 #include "Variable.h"
34 #include "details.h"
35
36 #include <memory>
37 #include <pdcom5_export.h>
38 #include <string>
39 #include <vector>
40
41 namespace PdCom {
42
43 namespace impl {
44 class Subscription;
45 } // namespace impl
46
47 class Process;
48 class Variable;
49 class Subscriber;
50
51 /** PdCom Subscription interface.
52 *
53 * This class represents a subscription to a variable. It is updated either
54 * on a periodic base, on an external event (e.g. the value has changed) or as
55 * requested with poll(). The type of transmission can be selected by
56 * creating an appropriate Subscriber object.
57 *
58 * To cancel a subscription, you have to delete the corresponding subscription
59 * instance.
60 *
61 * Calling getState() is always allowed, the other member functions need the
62 * subscription to be Active.
63 */
64 106 class PDCOM5_PUBLIC Subscription : public DataDeserializer<Subscription>
65 {
66 public:
67 enum class State {
68 Invalid = 0,
69 Pending,
70 Active,
71 };
72
73 /// Default constructor for an empty subscription.
74 8 Subscription() = default;
75 Subscription(Subscription &&) noexcept;
76 Subscription &operator=(Subscription &&) noexcept;
77
78 /** Constructor for a known variable.
79 * @param subscriber Subscriber which will recieve the status updates.
80 * @param variable The variable to subscribe.
81 * @param selector Select parts of multi-dimensional variables.
82 * @throw invalid_subscription Subscription is already known to be
83 * invalid.
84 */
85 Subscription(
86 Subscriber &subscriber,
87 const Variable &variable,
88 const Selector &selector = {});
89
90 /** Constructor for an unknown variable.
91 * @param subscriber Subscriber which will recieve the status updates.
92 * @param process The process.
93 * @param path Path of the variable to subscribe.
94 * @param selector Select parts of multi-dimensional variables.
95 * @throw invalid_subscription Subscription is already known to be
96 * invalid.
97 */
98 Subscription(
99 Subscriber &subscriber,
100 Process &process,
101 const std::string &path,
102 const Selector &selector = {});
103
104 /** Poll values from the server.
105 *
106 * The subscription has to be \c Active.
107 */
108 void poll();
109
110 /** Get the data Pointer.
111 *
112 * The subscription has to be \c Active.
113 *
114 * \return Pointer to the internal storage.
115 */
116 const void *getData() const;
117
118 /** Access the subscribed variable.
119 *
120 * The subscription must not be empty().
121 * \return The subscribed variable.
122 */
123 Variable getVariable() const;
124
125 /** Print the value(s).
126 *
127 * \param os Stream to print into.
128 * \param delimiter Delimiter which separates the values.
129 */
130 void print(std::ostream &os, char delimiter) const;
131
132 /** Check whether the subscription is default-constructed.
133 * \return false The subscription is populated.
134 */
135 1 bool empty() const noexcept { return !(pimpl); }
136
137 /** Get the current state.
138 * \return The state.
139 */
140 231 State getState() const noexcept { return state_; }
141
142 /** Get the assigned Process.
143 * \return The Process.
144 */
145 Process *getProcess() const;
146
147 /** Get the path of the subscribed variable.
148 *
149 * This also works in Pending and Invalid state.
150 * \return Path of the subscribed variable.
151 */
152 std::string getPath() const;
153
154 private:
155 friend impl::Subscription;
156
157 std::shared_ptr<impl::Subscription> pimpl = {};
158
159 State state_ = State::Invalid;
160 };
161
162 } // namespace PdCom
163
164 #endif // PDCOM5_SUBSCRIPTION_H
165