Statistics
| Branch: | Revision:

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