urtware / doc / classdiagrams / pubsub.uml @ c22d21ad
History | View | Annotate | Download (11.655 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 | '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 | 056e40d2 | Thomas Schöpping | .. URT_CFG_PUBSUB_PROFILING == true || URT_CFG_PUBSUB_QOS_JITTERCHECKS == true .. |
99 | 4d55cea4 | Thomas Schöpping | '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 | 056e40d2 | Thomas Schöpping | .. URT_CFG_PUBSUB_PROFILING == true || URT_CFG_PUBSUB_QOS_JITTERCHECKS == true .. |
116 | 4d55cea4 | Thomas Schöpping | '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 | 056e40d2 | Thomas Schöpping | + {field} rtdata : urt_rtdata_t |
154 | 4d55cea4 | Thomas Schöpping | '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 | 056e40d2 | Thomas Schöpping | .. URT_CFG_PUBSUB_PROFILING == true .. |
164 | 4d55cea4 | Thomas Schöpping | '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 | 056e40d2 | Thomas Schöpping | 'Condition variable to inform waiting publishers when a blocked message becomes available. |
221 | + {field} hrtReleased : urt_osCondvar_t |
||
222 | 4d55cea4 | Thomas Schöpping | '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 |