urtware / doc / classdiagrams / pubsub.uml @ 4d55cea4
History | View | Annotate | Download (12.3 KB)
1 |
/' |
---|---|
2 |
µRtWare is a lightweight publish/subscribe middleware for real-time |
3 |
applications. It was developed as part of the software habitat for the |
4 |
Autonomous Mini Robot [1] (AMiRo) but can be used for other purposes as well. |
5 |
|
6 |
Copyright (C) 2018..2020 Thomas Schöpping et al. |
7 |
|
8 |
This program is free software: you can redistribute it and/or modify |
9 |
it under the terms of the GNU General Public License as published by |
10 |
the Free Software Foundation, either version 3 of the License, or |
11 |
(at your option) any later version. |
12 |
|
13 |
This program is distributed in the hope that it will be useful, |
14 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
15 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
16 |
GNU General Public License for more details. |
17 |
|
18 |
You should have received a copy of the GNU General Public License |
19 |
along with this program. If not, see <http://www.gnu.org/licenses/>. |
20 |
'/ |
21 |
|
22 |
/'### INTRO ##################################################################'/ |
23 |
|
24 |
@startuml |
25 |
|
26 |
title **µRtWare**\nPublish-Subscribe System |
27 |
|
28 |
!include ../functions.iuml |
29 |
|
30 |
/'### ENTITIES ###############################################################'/ |
31 |
|
32 |
!startsub ENTITIES |
33 |
|
34 |
/' Message type. '/ |
35 |
$structure("urt_message_t") { |
36 |
'Pointer to the next message in a list. |
37 |
+ {field} next : urt_message_t* |
38 |
'Pointer to some arbitrary (reusable) payload object. |
39 |
+ {field} payload : void* |
40 |
'Origin time of the message. |
41 |
+ {field} originTime : urt_osTime_t |
42 |
'Mutex lock for exclusive access. |
43 |
+ {field} lock : urt_osMutex_t |
44 |
'Counter of HRT subscribers that did not consume the message yet. |
45 |
+ {field} numHrtConsumersLeft : unsigned int |
46 |
'Condition variable to inform waiting publishers when the message is available again. |
47 |
+ {field} hrtConsumersLeft : urt_osCondvar_t |
48 |
.. URT_CFG_PUBSUB_PROFILING == true .. |
49 |
'Counter of overall subscribers that did not consume the message yet. |
50 |
+ {field} numConsumersLeft : unsigned int |
51 |
__ |
52 |
'Initializes a urt_message_t object. |
53 |
+ {method} urtMessageInit (message : urt_message_t*, payload : void*) : urt_status_t |
54 |
} |
55 |
|
56 |
$group("subscriber") { |
57 |
$group("real-time constraint data") { |
58 |
/' The top level RT constraints structure. '/ |
59 |
$structure("urt_rtdata_t") { |
60 |
'The actual RT constraint class. |
61 |
+ {field} class : urt_rtconstraintclass_t |
62 |
'Parameters of the RT constraints. |
63 |
+ {field} params : urt_rtconstraintsparams_t |
64 |
} |
65 |
|
66 |
/' Descriptor to distinguish the four RT classes. '/ |
67 |
$enumeration("urt_rtclass_t") { |
68 |
'Hard real-time. |
69 |
URT_RTCLASS_HARD = 0 |
70 |
'Firm real-time. |
71 |
URT_RTCLASS_FIRM = 1 |
72 |
'Soft real-time. |
73 |
URT_RTCLASS_SOFT = 2 |
74 |
'No real-time at all. |
75 |
URT_RTCLASS_NONE = 3 |
76 |
} |
77 |
|
78 |
/' Union structure, holding RT constraints parameters. '/ |
79 |
$union("urt_rtclassdata_t") { |
80 |
'Parameters for hard real-time. |
81 |
+ {field} hrt : urt_hrtparams_t |
82 |
'Parameters for firm real-time. |
83 |
+ {field} frt : urt_frtparams_t |
84 |
'Parameters for soft real-time. |
85 |
+ {field} srt : urt_srtparans_t |
86 |
'Parameters for non-real-time. |
87 |
+ {field} nrt : urt_nrtparams_t |
88 |
} |
89 |
|
90 |
/' Parameters for hard real-time. '/ |
91 |
$structure("urt_hrtdata_t") { |
92 |
'Pointer to the next HRT subscriber in a list. |
93 |
+ {field} next : urt_subscriber_t* |
94 |
.. URT_CFG_PUBSUB_QOS_DEADLINECHECKS == true .. |
95 |
'QoS Timer to detect missed deadlines. |
96 |
+ {field} qosDeadlineTimer : urt_osTimer_t |
97 |
'Maximum temporal offset between creation and consumption of messages. |
98 |
+ {field} deadlineOffset : urt_delay_t |
99 |
.. URT_CFG_PUBSUB_QOS_RATECHECKS == true .. |
100 |
'Expected rate at which data is published. |
101 |
+ {field} expectedRate : urt_delay_t |
102 |
.. URT_CFG_PUBSUB_QOS_JITTERCHECKS == true .. |
103 |
'Maximum expected jitter. |
104 |
+ {field} maxJitter : urt_delay_t |
105 |
'Minimum latency ever detected (to calculate jitter). |
106 |
+ {field} minLatency : urt_delay_t |
107 |
'Maximum latency ever detected (to calculate jitter). |
108 |
+ {field} maxLatency : urt_delay_t |
109 |
} |
110 |
|
111 |
/' Parameters for firm real-time. '/ |
112 |
$structure("urt_frtdata_t") { |
113 |
.. URT_CFG_PUBSUB_QOS_DEADLINECHECKS == true .. |
114 |
'QoS Timer to detect missed deadlines. |
115 |
+ {field} qosDeadlineTimer : urt_osTimer_t |
116 |
'Maximum temporal offset between creation and consumption of messages. |
117 |
+ {field} deadlineOffset : urt_delay_t |
118 |
.. URT_CFG_PUBSUB_QOS_RATECHECKS == true .. |
119 |
'Expected rate at which data is published. |
120 |
+ {field} expectedRate : urt_delay_t |
121 |
.. URT_CFG_PUBSUB_QOS_JITTERCHECKS == true .. |
122 |
'Maximum expected jitter. |
123 |
+ {field} maxJitter : urt_delay_t |
124 |
'Minimum latency ever detected (to calculate jitter). |
125 |
+ {field} minLatency : urt_delay_t |
126 |
'Maximum latency ever detected (to calculate jitter). |
127 |
+ {field} maxLatency : urt_delay_t |
128 |
} |
129 |
|
130 |
$group("SRT data") { |
131 |
/' Function type to be called when calculating the usefulness of a message. '/ |
132 |
$function("urt_srtusefulnessfunc_t") { |
133 |
'Takes a delay and optionally parameters as arguments and returns a float in [0, 1]. |
134 |
urt_srtusefulnessfunc_t (dt : urt_delay_t, params : void*) : float |
135 |
} |
136 |
|
137 |
/' Parameters for soft real-time. '/ |
138 |
$structure("urt_srtdata_t") { |
139 |
'Callback to calculate usefulness of a message |
140 |
+ {field} usefullnesscb : urt_srtusefulnessfunc_t* |
141 |
'Optional parameters for the callback function. |
142 |
+ {field} cbparams : void* |
143 |
} |
144 |
} /'SRT data'/ |
145 |
|
146 |
/' Parameters for non-real-time. '/ |
147 |
$structure("urt_nrtdata_t") { |
148 |
'There are nor parameters in this case. |
149 |
} |
150 |
} /'real-time constraint data'/ |
151 |
|
152 |
/' Subscriber type. '/ |
153 |
$structure("urt_subscriber_t") { |
154 |
'Pointer to the topic, this subscriber subscribed to. |
155 |
+ {field} topic : urt_topic_t* |
156 |
'Event listener to notify the node about new messages. |
157 |
+ {field} evtListener : urt_osEventListener_t |
158 |
'Real-time class descriptor. |
159 |
+ {field} rtconstraints : urt_rtconstaints_t* |
160 |
'Pointer to the message consumed most recently. |
161 |
+ {field} lastMessage : urt_message_t* |
162 |
'Copy of the origin time of the message consumed most recently. |
163 |
+ {field} lastMessageTime : urt_osTime_t |
164 |
.. URT_CFG_PUBSUB_PROFILING == true .. |
165 |
'Sum of all latencies. |
166 |
+ {field} sumLatencies : uint64_t |
167 |
'Number of messages received. |
168 |
+ {field} numMessagesReceived : uint64_t |
169 |
.. URT_CFG_PUBSUB_PROFILING == true && URT_CFG_PUBSUB_QOS_JITTERCHECKS == false .. |
170 |
'Minimum latency ever detected (to calculate jitter). |
171 |
+ {field} minLatency : urt_delay_t |
172 |
'Maximum latency ever detected (to calculate jitter). |
173 |
+ {field} maxLatency : urt_delay_t |
174 |
__ |
175 |
'Initializes a urt_subscriber_t object. |
176 |
+ {method} urtSubscriberInit (subscriber : urt_subscriber_t*) : urt_status_t |
177 |
'Tries to subscribe to a topic as HRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic. |
178 |
+ {method} urtSubscriberSubscribeHrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, deadline : urt_delay_t, rate : urt_delay_t, jitter : urt_delay_t) : urt_status_t |
179 |
'Tries to subscribe to a topic as FRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic. |
180 |
+ {method} urtSubscriberSubscribeFrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, deadline : urt_delay_t, rate : urt_delay_t, jitter : urt_delay_t) : urt_status_t |
181 |
'Tries to subscribe to a topic as SRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic. |
182 |
+ {method} urtSubscriberSubscribeSrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, usefulnesscb : urt_srtusefulnessfunc_t*, cbparams : void*) : urt_status_t |
183 |
'Tries to subscribe to a topic as NRT subscriber and optionally contributes a list of messages to the topic. |
184 |
+ {method} urtSubscriberSubscribeNrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*) : urt_status_t |
185 |
'Unsubscribes from a topic. |
186 |
+ {method} urtSubscriberUnsubscribe (subscriber : urt_subscriber_t*) : urt_status_t |
187 |
'Fetches the next message in the buffer, optionally copies the payload and optionally returns the latency. |
188 |
+ {method} urtSubscriberFetchNextMessage (subscriber : urt_subscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
189 |
'Fetches the latest message, optionally copies the payload and optionally returns the latency. |
190 |
+ {method} urtSubscriberFetchLatestMessage (subscriber : urt_subscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
191 |
'Calculates the usefulness of a message after the specified delay depending on the SRT or FRT (or HRT) parameters. |
192 |
+ {method} urtSubscriberCalculateUsefulness (subscriber : urt_subscriber_t*, latency : urt_delay_t) : float |
193 |
} |
194 |
} /'subscriber'/ |
195 |
|
196 |
/' Publisher type. '/ |
197 |
$structure("urt_publisher_t") { |
198 |
'Pointer to the topic for publishing. |
199 |
+ {field} topic : urt_topic_t* |
200 |
.. URT_CFG_PROFILING == true .. |
201 |
'Counter of attempts to publish a message. |
202 |
+ {field} publishAttempts : uint64_t |
203 |
'Counter of failed attempts to publish a message. |
204 |
+ {field} publishFails : uint64_t |
205 |
__ |
206 |
'Initializes a urt_publisher_t object and contributes an optional list of messages. |
207 |
+ {method} urtPublisherInit (publisher : urt_publisher_t*, topic : urt_topic_t*, messages : urt_message_t*) : urt_status_t |
208 |
'Publishes a message via the associated topic. |
209 |
+ {method} urtPublisherPublish (publisher : urt_publisher_t*, payload : void*, n : size_t, t : urt_osTime_t, timeout : urt_delay_t) : urt_status_t |
210 |
} |
211 |
|
212 |
/' Topic type. '/ |
213 |
$structure("urt_topic_t") { |
214 |
'Pointer to the next topic in a list. |
215 |
+ {field} next : urt_topic_t* |
216 |
'Identifier of the topic. |
217 |
+ {field} id : urt_topicid_t |
218 |
'Mutex lock for exclusive access. |
219 |
+ {field} lock : urt_osMutex_t |
220 |
'Event source to inform all subscribers when a new message is published. |
221 |
+ {field} evtSource : urt_osEventSource_t |
222 |
'Number of HRT subscribers. |
223 |
+ {field} numHrtSubscribers : unsigned int |
224 |
'List of HRT subscribers, orderd by their expected rate (most critical first). |
225 |
+ {field} hrtSubscribers : urt_subscriber_t* |
226 |
'Mandatory message, each Topic holds. |
227 |
+ {field} mandatoryMessage : urt_message_t |
228 |
'Pointer to the latest message. |
229 |
+ {field} latestMessage : urt_message_t* |
230 |
.. URT_CFG_PUBSUB_QOS_RATECHECKS == true .. |
231 |
'Timer to check for missed rates. |
232 |
+ {field} qosRateTimer : urt_osTimer_t |
233 |
.. URT_CFG_PUBSUB_PROFILING == true .. |
234 |
'Variable to count how many (non-hrt) subscribers did not fetch a message before it was reused. |
235 |
+ {field} numDiscardedMessages : uint64_t |
236 |
'Number of overall subscribers. |
237 |
+ {field} numSubscribers : unsigned int |
238 |
__ |
239 |
'Initializes an urt_topic_t object. |
240 |
+ {method} urtTopicInit (topic : urt_topic_t*, id : urt_topicid_t) : urt_status_t |
241 |
} |
242 |
|
243 |
/' Publish-Subscribe core structure. '/ |
244 |
$structure("urt_pubsub_t") { |
245 |
'List of topics ordered by their identifiers. |
246 |
- {field} {static} _topics : urt_topic_t* |
247 |
__ |
248 |
'Initializes the urt_core_t object. |
249 |
+ {method} urtPubsubInit (void) : urt_status_t |
250 |
'Retrieves a topic given an identifier. |
251 |
+ {method} urtPubsubRetrieveTopic (id : urt_topicid_t) : urt_topic_t* |
252 |
} |
253 |
|
254 |
!endsub |
255 |
|
256 |
/'### DEPENDENCIES & LAYOUT ##################################################'/ |
257 |
|
258 |
!startsub DEPENDENCIES |
259 |
|
260 |
urt_srtdata_t "1" o-- "0..1" urt_srtusefulnessfunc_t |
261 |
|
262 |
urt_rtclassdata_t "1" *-- "0..1" urt_hrtdata_t |
263 |
urt_rtclassdata_t "1" *-- "0..1" urt_frtdata_t |
264 |
urt_rtclassdata_t "1" *-- "0..1" urt_srtdata_t |
265 |
urt_rtclassdata_t "1" *-- "0..1" urt_nrtdata_t |
266 |
|
267 |
urt_rtdata_t "1" *-- "1" urt_rtclass_t |
268 |
urt_rtdata_t "1" *-- "1" urt_rtclassdata_t |
269 |
|
270 |
urt_hrtdata_t "1" o-up- "0..1" urt_subscriber_t |
271 |
|
272 |
urt_message_t "1" o-- "0..1" urt_message_t |
273 |
|
274 |
urt_subscriber_t "1" *-- "1" urt_rtdata_t |
275 |
urt_subscriber_t "1" o- "0..1" urt_topic_t |
276 |
urt_subscriber_t "1" o-- "0..1" urt_message_t |
277 |
|
278 |
urt_publisher_t "1" o- "1" urt_topic_t |
279 |
urt_publisher_t ..> urt_message_t |
280 |
|
281 |
urt_topic_t "1" o-- "0..1" urt_topic_t |
282 |
urt_topic_t "1" o- "0..1" urt_subscriber_t |
283 |
urt_topic_t "1" o-- "1..1" urt_message_t |
284 |
urt_topic_t "1" *-- "1" urt_message_t |
285 |
|
286 |
urt_pubsub_t "1" o-- "0..1" urt_topic_t |
287 |
urt_pubsub_t -[hidden]-> urt_publisher_t |
288 |
|
289 |
!endsub |
290 |
|
291 |
/'### OUTRO ##################################################################'/ |
292 |
|
293 |
@enduml |
294 |
|