urtware / doc / classdiagrams / pubsub.uml @ c22d21ad
History | View | Annotate | Download (11.655 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 |
'Counter of HRT subscribers that did not consume the message yet. |
43 |
+ {field} numHrtConsumersLeft : unsigned int |
44 |
.. URT_CFG_PUBSUB_PROFILING == true .. |
45 |
'Counter of overall subscribers that did not consume the message yet. |
46 |
+ {field} numConsumersLeft : unsigned int |
47 |
__ |
48 |
'Initializes a urt_message_t object. |
49 |
+ {method} urtMessageInit (message : urt_message_t*, payload : void*) : urt_status_t |
50 |
} |
51 |
|
52 |
$group("subscriber") { |
53 |
$group("real-time constraint data") { |
54 |
/' The top level RT constraints structure. '/ |
55 |
$structure("urt_rtdata_t") { |
56 |
'The actual RT constraint class. |
57 |
+ {field} class : urt_rtconstraintclass_t |
58 |
'Parameters of the RT constraints. |
59 |
+ {field} params : urt_rtconstraintsparams_t |
60 |
} |
61 |
|
62 |
/' Descriptor to distinguish the four RT classes. '/ |
63 |
$enumeration("urt_rtclass_t") { |
64 |
'Hard real-time. |
65 |
URT_RTCLASS_HARD = 0 |
66 |
'Firm real-time. |
67 |
URT_RTCLASS_FIRM = 1 |
68 |
'Soft real-time. |
69 |
URT_RTCLASS_SOFT = 2 |
70 |
'No real-time at all. |
71 |
URT_RTCLASS_NONE = 3 |
72 |
} |
73 |
|
74 |
/' Union structure, holding RT constraints parameters. '/ |
75 |
$union("urt_rtclassdata_t") { |
76 |
'Parameters for hard real-time. |
77 |
+ {field} hrt : urt_hrtparams_t |
78 |
'Parameters for firm real-time. |
79 |
+ {field} frt : urt_frtparams_t |
80 |
'Parameters for soft real-time. |
81 |
+ {field} srt : urt_srtparans_t |
82 |
'Parameters for non-real-time. |
83 |
+ {field} nrt : urt_nrtparams_t |
84 |
} |
85 |
|
86 |
/' Parameters for hard real-time. '/ |
87 |
$structure("urt_hrtdata_t") { |
88 |
'Pointer to the next HRT subscriber in a list. |
89 |
+ {field} next : urt_subscriber_t* |
90 |
.. URT_CFG_PUBSUB_QOS_DEADLINECHECKS == true .. |
91 |
'QoS Timer to detect missed deadlines. |
92 |
+ {field} qosDeadlineTimer : urt_osTimer_t |
93 |
'Maximum temporal offset between creation and consumption of messages. |
94 |
+ {field} deadlineOffset : urt_delay_t |
95 |
.. URT_CFG_PUBSUB_QOS_RATECHECKS == true .. |
96 |
'Expected rate at which data is published. |
97 |
+ {field} expectedRate : urt_delay_t |
98 |
.. URT_CFG_PUBSUB_PROFILING == true || URT_CFG_PUBSUB_QOS_JITTERCHECKS == true .. |
99 |
'Maximum expected jitter. |
100 |
+ {field} maxJitter : urt_delay_t |
101 |
'Minimum latency ever detected (to calculate jitter). |
102 |
+ {field} minLatency : urt_delay_t |
103 |
'Maximum latency ever detected (to calculate jitter). |
104 |
+ {field} maxLatency : urt_delay_t |
105 |
} |
106 |
|
107 |
/' Parameters for firm real-time. '/ |
108 |
$structure("urt_frtdata_t") { |
109 |
.. URT_CFG_PUBSUB_QOS_DEADLINECHECKS == true .. |
110 |
'Maximum temporal offset between creation and consumption of messages. |
111 |
+ {field} deadlineOffset : urt_delay_t |
112 |
.. URT_CFG_PUBSUB_QOS_RATECHECKS == true .. |
113 |
'Expected rate at which data is published. |
114 |
+ {field} expectedRate : urt_delay_t |
115 |
.. URT_CFG_PUBSUB_PROFILING == true || URT_CFG_PUBSUB_QOS_JITTERCHECKS == true .. |
116 |
'Maximum expected jitter. |
117 |
+ {field} maxJitter : urt_delay_t |
118 |
'Minimum latency ever detected (to calculate jitter). |
119 |
+ {field} minLatency : urt_delay_t |
120 |
'Maximum latency ever detected (to calculate jitter). |
121 |
+ {field} maxLatency : urt_delay_t |
122 |
} |
123 |
|
124 |
$group("SRT data") { |
125 |
/' Function type to be called when calculating the usefulness of a message. '/ |
126 |
$function("urt_srtusefulnessfunc_t") { |
127 |
'Takes a delay and optionally parameters as arguments and returns a float in [0, 1]. |
128 |
urt_srtusefulnessfunc_t (dt : urt_delay_t, params : void*) : float |
129 |
} |
130 |
|
131 |
/' Parameters for soft real-time. '/ |
132 |
$structure("urt_srtdata_t") { |
133 |
'Callback to calculate usefulness of a message |
134 |
+ {field} usefullnesscb : urt_srtusefulnessfunc_t* |
135 |
'Optional parameters for the callback function. |
136 |
+ {field} cbparams : void* |
137 |
} |
138 |
} /'SRT data'/ |
139 |
|
140 |
/' Parameters for non-real-time. '/ |
141 |
$structure("urt_nrtdata_t") { |
142 |
'There are nor parameters in this case. |
143 |
} |
144 |
} /'real-time constraint data'/ |
145 |
|
146 |
/' Subscriber type. '/ |
147 |
$structure("urt_subscriber_t") { |
148 |
'Pointer to the topic, this subscriber subscribed to. |
149 |
+ {field} topic : urt_topic_t* |
150 |
'Event listener to notify the node about new messages. |
151 |
+ {field} evtListener : urt_osEventListener_t |
152 |
'Real-time class descriptor. |
153 |
+ {field} rtdata : urt_rtdata_t |
154 |
'Pointer to the message consumed most recently. |
155 |
+ {field} lastMessage : urt_message_t* |
156 |
'Copy of the origin time of the message consumed most recently. |
157 |
+ {field} lastMessageTime : urt_osTime_t |
158 |
.. URT_CFG_PUBSUB_PROFILING == true .. |
159 |
'Sum of all latencies. |
160 |
+ {field} sumLatencies : uint64_t |
161 |
'Number of messages received. |
162 |
+ {field} numMessagesReceived : uint64_t |
163 |
.. URT_CFG_PUBSUB_PROFILING == true .. |
164 |
'Minimum latency ever detected (to calculate jitter). |
165 |
+ {field} minLatency : urt_delay_t |
166 |
'Maximum latency ever detected (to calculate jitter). |
167 |
+ {field} maxLatency : urt_delay_t |
168 |
__ |
169 |
'Initializes a urt_subscriber_t object. |
170 |
+ {method} urtSubscriberInit (subscriber : urt_subscriber_t*) : urt_status_t |
171 |
'Tries to subscribe to a topic as HRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic. |
172 |
+ {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 |
173 |
'Tries to subscribe to a topic as FRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic. |
174 |
+ {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 |
175 |
'Tries to subscribe to a topic as SRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic. |
176 |
+ {method} urtSubscriberSubscribeSrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, usefulnesscb : urt_srtusefulnessfunc_t*, cbparams : void*) : urt_status_t |
177 |
'Tries to subscribe to a topic as NRT subscriber and optionally contributes a list of messages to the topic. |
178 |
+ {method} urtSubscriberSubscribeNrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*) : urt_status_t |
179 |
'Unsubscribes from a topic. |
180 |
+ {method} urtSubscriberUnsubscribe (subscriber : urt_subscriber_t*) : urt_status_t |
181 |
'Fetches the next message in the buffer, optionally copies the payload and optionally returns the latency. |
182 |
+ {method} urtSubscriberFetchNextMessage (subscriber : urt_subscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
183 |
'Fetches the latest message, optionally copies the payload and optionally returns the latency. |
184 |
+ {method} urtSubscriberFetchLatestMessage (subscriber : urt_subscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
185 |
'Calculates the usefulness of a message after the specified delay depending on the SRT or FRT (or HRT) parameters. |
186 |
+ {method} urtSubscriberCalculateUsefulness (subscriber : urt_subscriber_t*, latency : urt_delay_t) : float |
187 |
} |
188 |
} /'subscriber'/ |
189 |
|
190 |
/' Publisher type. '/ |
191 |
$structure("urt_publisher_t") { |
192 |
'Pointer to the topic for publishing. |
193 |
+ {field} topic : urt_topic_t* |
194 |
.. URT_CFG_PROFILING == true .. |
195 |
'Counter of attempts to publish a message. |
196 |
+ {field} publishAttempts : uint64_t |
197 |
'Counter of failed attempts to publish a message. |
198 |
+ {field} publishFails : uint64_t |
199 |
__ |
200 |
'Initializes a urt_publisher_t object and contributes an optional list of messages. |
201 |
+ {method} urtPublisherInit (publisher : urt_publisher_t*, topic : urt_topic_t*, messages : urt_message_t*) : urt_status_t |
202 |
'Publishes a message via the associated topic. |
203 |
+ {method} urtPublisherPublish (publisher : urt_publisher_t*, payload : void*, n : size_t, t : urt_osTime_t, timeout : urt_delay_t) : urt_status_t |
204 |
} |
205 |
|
206 |
/' Topic type. '/ |
207 |
$structure("urt_topic_t") { |
208 |
'Pointer to the next topic in a list. |
209 |
+ {field} next : urt_topic_t* |
210 |
'Identifier of the topic. |
211 |
+ {field} id : urt_topicid_t |
212 |
'Mutex lock for exclusive access. |
213 |
+ {field} lock : urt_osMutex_t |
214 |
'Event source to inform all subscribers when a new message is published. |
215 |
+ {field} evtSource : urt_osEventSource_t |
216 |
'Number of HRT subscribers. |
217 |
+ {field} numHrtSubscribers : unsigned int |
218 |
'List of HRT subscribers, orderd by their expected rate (most critical first). |
219 |
+ {field} hrtSubscribers : urt_subscriber_t* |
220 |
'Condition variable to inform waiting publishers when a blocked message becomes available. |
221 |
+ {field} hrtReleased : urt_osCondvar_t |
222 |
'Mandatory message, each Topic holds. |
223 |
+ {field} mandatoryMessage : urt_message_t |
224 |
'Pointer to the latest message. |
225 |
+ {field} latestMessage : urt_message_t* |
226 |
.. URT_CFG_PUBSUB_QOS_RATECHECKS == true .. |
227 |
'Timer to check for missed rates. |
228 |
+ {field} qosRateTimer : urt_osTimer_t |
229 |
.. URT_CFG_PUBSUB_PROFILING == true .. |
230 |
'Variable to count how many (non-hrt) subscribers did not fetch a message before it was reused. |
231 |
+ {field} numDiscardedMessages : uint64_t |
232 |
'Number of overall subscribers. |
233 |
+ {field} numSubscribers : unsigned int |
234 |
__ |
235 |
'Initializes an urt_topic_t object. |
236 |
+ {method} urtTopicInit (topic : urt_topic_t*, id : urt_topicid_t) : urt_status_t |
237 |
} |
238 |
|
239 |
!endsub |
240 |
|
241 |
/'### DEPENDENCIES & LAYOUT ##################################################'/ |
242 |
|
243 |
!startsub DEPENDENCIES |
244 |
|
245 |
urt_srtdata_t "1" o-- "0..1" urt_srtusefulnessfunc_t |
246 |
|
247 |
urt_rtclassdata_t "1" *-- "0..1" urt_hrtdata_t |
248 |
urt_rtclassdata_t "1" *-- "0..1" urt_frtdata_t |
249 |
urt_rtclassdata_t "1" *-- "0..1" urt_srtdata_t |
250 |
urt_rtclassdata_t "1" *-- "0..1" urt_nrtdata_t |
251 |
|
252 |
urt_rtdata_t "1" *-- "1" urt_rtclass_t |
253 |
urt_rtdata_t "1" *-- "1" urt_rtclassdata_t |
254 |
|
255 |
urt_hrtdata_t "1" o-up- "0..1" urt_subscriber_t |
256 |
|
257 |
urt_message_t "1" o-- "0..1" urt_message_t |
258 |
|
259 |
urt_subscriber_t "1" *-- "1" urt_rtdata_t |
260 |
urt_subscriber_t "1" o- "0..1" urt_topic_t |
261 |
urt_subscriber_t "1" o-- "0..1" urt_message_t |
262 |
|
263 |
urt_publisher_t "1" o- "1" urt_topic_t |
264 |
urt_publisher_t ..> urt_message_t |
265 |
|
266 |
urt_topic_t "1" o-- "0..1" urt_topic_t |
267 |
urt_topic_t "1" o- "0..1" urt_subscriber_t |
268 |
urt_topic_t "1" o-- "1..1" urt_message_t |
269 |
urt_topic_t "1" *-- "1" urt_message_t |
270 |
|
271 |
!endsub |
272 |
|
273 |
/'### OUTRO ##################################################################'/ |
274 |
|
275 |
@enduml |
276 |
|