urtware / doc / classdiagrams / pubsub.uml @ 4d55cea4
History | View | Annotate | Download (12.252 KB)
1 | 4d55cea4 | Thomas Schöpping | /' |
---|---|---|---|
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 |