urtware / doc / classdiagrams / pubsub.uml @ 77bd2c61
History | View | Annotate | Download (12.8 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 | dd31cb03 | Thomas Schöpping | !include ./functions.iuml |
29 | 4d55cea4 | Thomas Schöpping | |
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 | dd31cb03 | Thomas Schöpping | + {method} urtMessageInit (message : urt_message_t*, payload : void*) : void |
50 | 4d55cea4 | Thomas Schöpping | } |
51 | |||
52 | $group("subscriber") { |
||
53 | ee83a495 | Thomas Schöpping | /' Base subscriber type. '/ |
54 | $structure("urt_basesubscriber_t") { |
||
55 | 4d55cea4 | Thomas Schöpping | 'Pointer to the topic, this subscriber subscribed to. |
56 | + {field} topic : urt_topic_t* |
||
57 | 'Event listener to notify the node about new messages. |
||
58 | + {field} evtListener : urt_osEventListener_t |
||
59 | 'Pointer to the message consumed most recently. |
||
60 | + {field} lastMessage : urt_message_t* |
||
61 | 'Copy of the origin time of the message consumed most recently. |
||
62 | + {field} lastMessageTime : urt_osTime_t |
||
63 | .. URT_CFG_PUBSUB_PROFILING == true .. |
||
64 | 'Sum of all latencies. |
||
65 | + {field} sumLatencies : uint64_t |
||
66 | 'Number of messages received. |
||
67 | + {field} numMessagesReceived : uint64_t |
||
68 | ee83a495 | Thomas Schöpping | } |
69 | |||
70 | /' NRT subscriber type. '/ |
||
71 | $structure("urt_nrtsubscriber_t") { |
||
72 | .. URT_CFG_PUBSUB_PROFILING == true .. |
||
73 | 'Minimum latency ever detected. |
||
74 | + {field} minLatency : urt_delay_t |
||
75 | 'Maximum latency ever detected. |
||
76 | + {field} maxLatency : urt_delay_t |
||
77 | __ |
||
78 | 'Initializes a urt_nrtsubscriber_t object. |
||
79 | dd31cb03 | Thomas Schöpping | + {method} urtNrtSubscriberInit (subscriber : urt_nrtsubscriber_t*) : void |
80 | ee83a495 | Thomas Schöpping | 'Tries to subscribe to a topic and optionally contributes a list of messages to the topic. |
81 | + {method} urtNrtSubscriberSubscribe (subscriber : urt_nrtsubscriber_t*, topic : urt_topic_t*, messages : urt_message_t*) : urt_status_t |
||
82 | 'Fetches the next message in the buffer, optionally copies the payload and optionally returns the latency. |
||
83 | + {method} urtNrtSubscriberFetchNextMessage (subscriber : urt_nrtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
||
84 | 'Fetches the latest message, optionally copies the payload and optionally returns the latency. |
||
85 | + {method} urtNrtSubscriberFetchLatestMessage (subscriber : urt_nrtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
||
86 | 'Unsubscribes from a topic. |
||
87 | + {method} urtNrtSubscriberUnsubscribe (subscriber : urt_nrtsubscriber_t*) : urt_status_t |
||
88 | } |
||
89 | |||
90 | /' SRT subscriber type. '/ |
||
91 | $structure("urt_srtsubscriber_t") { |
||
92 | 'Callback to calculate usefulness of a message |
||
93 | 2d315870 | Thomas Schöpping | + {field} usefulnesscb : urt_usefulness_f* |
94 | ee83a495 | Thomas Schöpping | 'Optional parameters for the usefulness callback function. |
95 | + {field} cbparams : void* |
||
96 | 056e40d2 | Thomas Schöpping | .. URT_CFG_PUBSUB_PROFILING == true .. |
97 | ee83a495 | Thomas Schöpping | 'Minimum latency ever detected. |
98 | + {field} minLatency : urt_delay_t |
||
99 | 'Maximum latency ever detected. |
||
100 | + {field} maxLatency : urt_delay_t |
||
101 | __ |
||
102 | 'Initializes a urt_srtsubscriber_t object. |
||
103 | dd31cb03 | Thomas Schöpping | + {method} urtSrtSubscriberInit (subscriber : urt_srtsubscriber_t*) : void |
104 | ee83a495 | Thomas Schöpping | 'Tries to subscribe to a topic, sets all parameters and optionally contributes a list of messages to the topic. |
105 | 2d315870 | Thomas Schöpping | + {method} urtSrtSubscriberSubscribe (subscriber : urt_srtsubscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, usefulnesscb : urt_usefulness_f*, cbparams : void*) : urt_status_t |
106 | ee83a495 | Thomas Schöpping | 'Fetches the next message in the buffer, optionally copies the payload and optionally returns the latency. |
107 | + {method} urtSrtSubscriberFetchNextMessage (subscriber : urt_srtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
||
108 | 'Fetches the latest message, optionally copies the payload and optionally returns the latency. |
||
109 | + {method} urtSrtSubscriberFetchLatestMessage (subscriber : urt_srtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
||
110 | 'Calculates the usefulness of a message after the specified delay. |
||
111 | + {method} urtSrtSubscriberCalculateUsefulness (subscriber : urt_srtsubscriber_t*, latency : urt_delay_t) : float |
||
112 | 'Unsubscribes from a topic. |
||
113 | + {method} urtSrtSubscriberUnsubscribe (subscriber : urt_srtsubscriber_t*) : urt_status_t |
||
114 | } |
||
115 | |||
116 | /' FRT subscriber type. '/ |
||
117 | $structure("urt_frtsubscriber_t") { |
||
118 | .. URT_CFG_PUBSUB_QOS_DEADLINECHECKS == true .. |
||
119 | 'Maximum temporal offset between creation and consumption of messages. |
||
120 | + {field} deadlineOffset : urt_delay_t |
||
121 | .. URT_CFG_PUBSUB_QOS_JITTERCHECKS == true .. |
||
122 | 'Maximum expected jitter. |
||
123 | + {field} maxJitter : urt_delay_t |
||
124 | .. URT_CFG_PUBSUB_QOS_JITTERCHECKS == true || URT_CFG_PUBSUB_PROFILING == true .. |
||
125 | 4d55cea4 | Thomas Schöpping | 'Minimum latency ever detected (to calculate jitter). |
126 | + {field} minLatency : urt_delay_t |
||
127 | 'Maximum latency ever detected (to calculate jitter). |
||
128 | + {field} maxLatency : urt_delay_t |
||
129 | __ |
||
130 | ee83a495 | Thomas Schöpping | 'Initializes a urt_frtsubscriber_t object. |
131 | dd31cb03 | Thomas Schöpping | + {method} urtFrtSubscriberInit (subscriber : urt_frtsubscriber_t*) : void |
132 | ee83a495 | Thomas Schöpping | 'Tries to subscribe to a topic, sets all parameters and optionally contributes a list of messages to the topic. |
133 | + {method} urtFrtSubscriberSubscribe (subscriber : urt_frtsubscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, deadline : urt_delay_t, jitter : urt_delay_t) : urt_status_t |
||
134 | 'Fetches the next message in the buffer, optionally copies the payload and optionally returns the latency. |
||
135 | + {method} urtFrtSubscriberFetchNextMessage (subscriber : urt_frtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
||
136 | 'Fetches the latest message, optionally copies the payload and optionally returns the latency. |
||
137 | + {method} urtFrtSubscriberFetchLatestMessage (subscriber : urt_frtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
||
138 | 'Checks whether a message is valid after the specified delay. |
||
139 | + {method} urtFrtSubscriberCalculateValidity (subscriber : urt_frtsubscriber_t*, latency : urt_delay_t) : bool |
||
140 | 4d55cea4 | Thomas Schöpping | 'Unsubscribes from a topic. |
141 | ee83a495 | Thomas Schöpping | + {method} urtFrtSubscriberUnsubscribe (subscriber : urt_frtsubscriber_t*) : urt_status_t |
142 | } |
||
143 | |||
144 | /' HRT subscriber type. '/ |
||
145 | $structure("urt_hrtsubscriber_t") { |
||
146 | 'Pointer to the next HRT subscriber in a list. |
||
147 | + {field} next : urt_hrtsubscriber_t* |
||
148 | .. URT_CFG_PUBSUB_QOS_DEADLINECHECKS == true .. |
||
149 | 'Maximum temporal offset between creation and consumption of messages. |
||
150 | + {field} deadlineOffset : urt_delay_t |
||
151 | 'QoS Timer to detect missed deadlines. |
||
152 | + {field} qosDeadlineTimer : urt_osTimer_t |
||
153 | .. URT_CFG_PUBSUB_QOS_JITTERCHECKS == true .. |
||
154 | 'Maximum expected jitter. |
||
155 | + {field} maxJitter : urt_delay_t |
||
156 | .. URT_CFG_PUBSUB_QOS_JITTERCHECKS == true || URT_CFG_PUBSUB_PROFILING == true.. |
||
157 | 'Minimum latency ever detected (to calculate jitter). |
||
158 | + {field} minLatency : urt_delay_t |
||
159 | 'Maximum latency ever detected (to calculate jitter). |
||
160 | + {field} maxLatency : urt_delay_t |
||
161 | .. URT_CFG_PUBSUB_QOS_RATECHECKS == true .. |
||
162 | 'Expected rate at which data is published. |
||
163 | + {field} expectedRate : urt_delay_t |
||
164 | __ |
||
165 | 'Initializes a urt_hrtsubscriber_t object. |
||
166 | dd31cb03 | Thomas Schöpping | + {method} urtHrtSubscriberInit (subscriber : urt_hrtsubscriber_t*) : void |
167 | ee83a495 | Thomas Schöpping | 'Tries to subscribe to a topic, sets all parameters and optionally contributes a list of messages to the topic. |
168 | + {method} urtHrtSubscriberSubscribe (subscriber : urt_hrtsubscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, deadline : urt_delay_t, rate : urt_delay_t, jitter : urt_delay_t) : urt_status_t |
||
169 | 4d55cea4 | Thomas Schöpping | 'Fetches the next message in the buffer, optionally copies the payload and optionally returns the latency. |
170 | ee83a495 | Thomas Schöpping | + {method} urtHrtSubscriberFetchNextMessage (subscriber : urt_hrtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
171 | 4d55cea4 | Thomas Schöpping | 'Fetches the latest message, optionally copies the payload and optionally returns the latency. |
172 | ee83a495 | Thomas Schöpping | + {method} urtHrtSubscriberFetchLatestMessage (subscriber : urt_hrtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t |
173 | 'Unsubscribes from a topic. |
||
174 | + {method} urtHrtSubscriberUnsubscribe (subscriber : urt_hrtsubscriber_t*) : urt_status_t |
||
175 | 4d55cea4 | Thomas Schöpping | } |
176 | } /'subscriber'/ |
||
177 | |||
178 | /' Publisher type. '/ |
||
179 | $structure("urt_publisher_t") { |
||
180 | 0de5bed8 | Thomas Schöpping | 'Flag, whether the publish() method supports timeout. |
181 | URT_PUBSUB_PUBLISHER_PUBLISH_TIMEOUT : bool |
||
182 | __ |
||
183 | 4d55cea4 | Thomas Schöpping | 'Pointer to the topic for publishing. |
184 | + {field} topic : urt_topic_t* |
||
185 | ee83a495 | Thomas Schöpping | .. URT_CFG_PUBSUB_PROFILING == true .. |
186 | 4d55cea4 | Thomas Schöpping | 'Counter of attempts to publish a message. |
187 | + {field} publishAttempts : uint64_t |
||
188 | 'Counter of failed attempts to publish a message. |
||
189 | + {field} publishFails : uint64_t |
||
190 | __ |
||
191 | 'Initializes a urt_publisher_t object and contributes an optional list of messages. |
||
192 | dd31cb03 | Thomas Schöpping | + {method} urtPublisherInit (publisher : urt_publisher_t*, topic : urt_topic_t*, messages : urt_message_t*) : void |
193 | 0de5bed8 | Thomas Schöpping | .. URT_PUBSUB_PUBLISHER_PUBLISH_TIMEOUT == false .. |
194 | 4d55cea4 | Thomas Schöpping | 'Publishes a message via the associated topic. |
195 | 0de5bed8 | Thomas Schöpping | + {method} urtPublisherPublish (publisher : urt_publisher_t*, payload : void*, bytes : size_t, t : urt_osTime_t) : urt_status_t |
196 | .. URT_PUBSUB_PUBLISHER_PUBLISH_TIMEOUT == true .. |
||
197 | 'Publishes a message via the associated topic with timeout. |
||
198 | dd31cb03 | Thomas Schöpping | + {method} urtPublisherPublish (publisher : urt_publisher_t*, payload : void*, bytes : size_t, t : urt_osTime_t, timeout : urt_delay_t) : urt_status_t |
199 | 4d55cea4 | Thomas Schöpping | } |
200 | |||
201 | /' Topic type. '/ |
||
202 | $structure("urt_topic_t") { |
||
203 | 'Pointer to the next topic in a list. |
||
204 | + {field} next : urt_topic_t* |
||
205 | 'Identifier of the topic. |
||
206 | + {field} id : urt_topicid_t |
||
207 | 'Mutex lock for exclusive access. |
||
208 | + {field} lock : urt_osMutex_t |
||
209 | 'Event source to inform all subscribers when a new message is published. |
||
210 | + {field} evtSource : urt_osEventSource_t |
||
211 | 'Number of HRT subscribers. |
||
212 | + {field} numHrtSubscribers : unsigned int |
||
213 | 056e40d2 | Thomas Schöpping | 'Condition variable to inform waiting publishers when a blocked message becomes available. |
214 | + {field} hrtReleased : urt_osCondvar_t |
||
215 | 4d55cea4 | Thomas Schöpping | 'Mandatory message, each Topic holds. |
216 | + {field} mandatoryMessage : urt_message_t |
||
217 | 'Pointer to the latest message. |
||
218 | + {field} latestMessage : urt_message_t* |
||
219 | .. URT_CFG_PUBSUB_QOS_RATECHECKS == true .. |
||
220 | dd31cb03 | Thomas Schöpping | 'List of HRT subscribers, orderd by their expected rate (most critical first). |
221 | + {field} hrtSubscribers : urt_hrtsubscriber_t* |
||
222 | 4d55cea4 | Thomas Schöpping | 'Timer to check for missed rates. |
223 | + {field} qosRateTimer : urt_osTimer_t |
||
224 | .. URT_CFG_PUBSUB_PROFILING == true .. |
||
225 | dd31cb03 | Thomas Schöpping | 'Number of overall published messages on this topic. |
226 | + {field} numMessagesPublished : uint64_t |
||
227 | 'Variable to count how often (non-hrt) subscribers did not fetch a message before it was reused. |
||
228 | + {field} numMessagesDiscarded : uint64_t |
||
229 | 4d55cea4 | Thomas Schöpping | 'Number of overall subscribers. |
230 | + {field} numSubscribers : unsigned int |
||
231 | __ |
||
232 | 'Initializes an urt_topic_t object. |
||
233 | 77bd2c61 | skenneweg | + {method} urtTopicInit (topic : urt_topic_t*, id : urt_topicid_t, mandatoryMessage: urt_message_t*) : urt_status_t |
234 | 4d55cea4 | Thomas Schöpping | } |
235 | |||
236 | !endsub |
||
237 | |||
238 | /'### DEPENDENCIES & LAYOUT ##################################################'/ |
||
239 | |||
240 | !startsub DEPENDENCIES |
||
241 | |||
242 | 2d315870 | Thomas Schöpping | urt_message_t "1" o- "0,1" urt_message_t |
243 | |||
244 | urt_basesubscriber_t "1" o-- "0,1" urt_message_t |
||
245 | 4d55cea4 | Thomas Schöpping | |
246 | ee83a495 | Thomas Schöpping | urt_nrtsubscriber_t --|> urt_basesubscriber_t |
247 | 4d55cea4 | Thomas Schöpping | |
248 | ee83a495 | Thomas Schöpping | urt_srtsubscriber_t --|> urt_basesubscriber_t |
249 | 4d55cea4 | Thomas Schöpping | |
250 | ee83a495 | Thomas Schöpping | urt_frtsubscriber_t --|> urt_basesubscriber_t |
251 | 4d55cea4 | Thomas Schöpping | |
252 | ee83a495 | Thomas Schöpping | urt_hrtsubscriber_t --|> urt_basesubscriber_t |
253 | 2d315870 | Thomas Schöpping | urt_hrtsubscriber_t "1" o- "0,1" urt_hrtsubscriber_t |
254 | 4d55cea4 | Thomas Schöpping | |
255 | urt_publisher_t "1" o- "1" urt_topic_t |
||
256 | urt_publisher_t ..> urt_message_t |
||
257 | |||
258 | 2d315870 | Thomas Schöpping | urt_topic_t "1" o- "0,1" urt_topic_t |
259 | urt_topic_t "1" o- "0,1" urt_hrtsubscriber_t |
||
260 | 4d55cea4 | Thomas Schöpping | urt_topic_t "1" *-- "1" urt_message_t |
261 | |||
262 | !endsub |
||
263 | |||
264 | /'### OUTRO ##################################################################'/ |
||
265 | |||
266 | @enduml |