Statistics
| Branch: | Revision:

urtware / doc / classdiagrams / pubsub.uml @ c22d21ad

History | View | Annotate | Download (11.7 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*) : 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
      .. URT_CFG_PUBSUB_PROFILING == true || URT_CFG_PUBSUB_QOS_JITTERCHECKS == true ..
99
        '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
      .. URT_CFG_PUBSUB_PROFILING == true || URT_CFG_PUBSUB_QOS_JITTERCHECKS == true ..
116
        '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
    + {field} rtdata : urt_rtdata_t
154
      '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
    .. URT_CFG_PUBSUB_PROFILING == true ..
164
      '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
    'Condition variable to inform waiting publishers when a blocked message becomes available.
221
  + {field} hrtReleased : urt_osCondvar_t
222
    '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
276