Statistics
| Branch: | Revision:

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