Statistics
| Branch: | Revision:

urtware / doc / classdiagrams / pubsub.uml @ 77bd2c61

History | View | Annotate | Download (12.791 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*) : void
50
}
51

    
52
$group("subscriber") {
53
  /' Base subscriber type. '/
54
  $structure("urt_basesubscriber_t") {
55
      '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
  }
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
    + {method} urtNrtSubscriberInit (subscriber : urt_nrtsubscriber_t*) : void
80
      '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
    + {field} usefulnesscb : urt_usefulness_f*
94
      'Optional parameters for the usefulness callback function.
95
    + {field} cbparams : void*
96
    .. URT_CFG_PUBSUB_PROFILING == true ..
97
      '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
    + {method} urtSrtSubscriberInit (subscriber : urt_srtsubscriber_t*) : void
104
      'Tries to subscribe to a topic, sets all parameters and optionally contributes a list of messages to the topic.
105
    + {method} urtSrtSubscriberSubscribe (subscriber : urt_srtsubscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, usefulnesscb : urt_usefulness_f*, cbparams : void*) : urt_status_t
106
      '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
      '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
      'Initializes a urt_frtsubscriber_t object.
131
    + {method} urtFrtSubscriberInit (subscriber : urt_frtsubscriber_t*) : void
132
      '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
      'Unsubscribes from a topic.
141
    + {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
    + {method} urtHrtSubscriberInit (subscriber : urt_hrtsubscriber_t*) : void
167
      '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
      'Fetches the next message in the buffer, optionally copies the payload and optionally returns the latency.
170
    + {method} urtHrtSubscriberFetchNextMessage (subscriber : urt_hrtsubscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t
171
      'Fetches the latest message, optionally copies the payload and optionally returns the latency.
172
    + {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
  }
176
} /'subscriber'/
177

    
178
/' Publisher type. '/
179
$structure("urt_publisher_t") {
180
  'Flag, whether the publish() method supports timeout.
181
  URT_PUBSUB_PUBLISHER_PUBLISH_TIMEOUT : bool
182
  __
183
    'Pointer to the topic for publishing.
184
  + {field} topic : urt_topic_t*
185
  .. URT_CFG_PUBSUB_PROFILING == true ..
186
    '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
  + {method} urtPublisherInit (publisher : urt_publisher_t*, topic : urt_topic_t*, messages : urt_message_t*) : void
193
  .. URT_PUBSUB_PUBLISHER_PUBLISH_TIMEOUT == false ..
194
    'Publishes a message via the associated topic.
195
  + {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
  + {method} urtPublisherPublish (publisher : urt_publisher_t*, payload : void*, bytes : size_t, t : urt_osTime_t, timeout : urt_delay_t) : urt_status_t
199
}
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
    'Condition variable to inform waiting publishers when a blocked message becomes available.
214
  + {field} hrtReleased : urt_osCondvar_t
215
    '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
    'List of HRT subscribers, orderd by their expected rate (most critical first).
221
  + {field} hrtSubscribers : urt_hrtsubscriber_t*
222
    'Timer to check for missed rates.
223
  + {field} qosRateTimer : urt_osTimer_t
224
  .. URT_CFG_PUBSUB_PROFILING == true ..
225
    '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
    'Number of overall subscribers.
230
  + {field} numSubscribers : unsigned int
231
  __
232
    'Initializes an urt_topic_t object.
233
  + {method} urtTopicInit (topic : urt_topic_t*, id : urt_topicid_t, mandatoryMessage: urt_message_t*) : urt_status_t
234
}
235

    
236
!endsub
237

    
238
/'### DEPENDENCIES & LAYOUT ##################################################'/
239

    
240
!startsub DEPENDENCIES
241

    
242
urt_message_t "1" o- "0,1" urt_message_t
243

    
244
urt_basesubscriber_t "1" o-- "0,1" urt_message_t
245

    
246
urt_nrtsubscriber_t --|> urt_basesubscriber_t
247

    
248
urt_srtsubscriber_t --|> urt_basesubscriber_t
249

    
250
urt_frtsubscriber_t --|> urt_basesubscriber_t
251

    
252
urt_hrtsubscriber_t --|> urt_basesubscriber_t
253
urt_hrtsubscriber_t "1" o- "0,1" urt_hrtsubscriber_t
254

    
255
urt_publisher_t "1" o- "1" urt_topic_t
256
urt_publisher_t ..> urt_message_t
257

    
258
urt_topic_t "1" o- "0,1" urt_topic_t
259
urt_topic_t "1" o- "0,1" urt_hrtsubscriber_t
260
urt_topic_t "1" *-- "1" urt_message_t
261

    
262
!endsub
263

    
264
/'### OUTRO ##################################################################'/
265

    
266
@enduml
267