Statistics
| Branch: | Revision:

urtware / doc / classdiagrams / rpc.uml @ 6c5df8c1

History | View | Annotate | Download (10.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**\nRemote Procedure Call System
27

    
28
!include ./functions.iuml
29

    
30
/'### ENTITIES ###############################################################'/
31

    
32
!startsub ENTITIES
33

    
34
$group("request") {
35
  /' Base request structure type. '/
36
  $structure("urt_baserequest_t") {
37
      'Pointer to the previous request in a queue.
38
    + {field} prev : urt_baserequest_t*
39
      'Pointer to the next request in a queue.
40
    + {field} next : urt_baserequest_t*
41
      'Lock for exclusive access.
42
    + {field} lock : urt_osMutex_t
43
      'Pointer to the owning service.
44
    + {field} owner : urt_service_t*
45
      'Time when the request was submitted.
46
    + {field} submissionTime : urt_osTime_t
47
      'Pointer to an optional payload of the service request.
48
    + {field} payload : void*
49
      'Source for service events.
50
    + {field} evtSource : urt_osEventSource_t
51
      'Listener to service events.
52
    + {field} evtListener : urt_osEventListener_t
53
    .. URT_CFG_RPC_PROFILING == true ..
54
      'Sum of all latencies.
55
    + {field} sumLatencies : uint64_t
56
      'Number of calls emitted.
57
    + {field} numCalls : uint64_t
58
      'Number of calls that were not processed successfully.
59
    + {field} numFails : uint64_t
60
  }
61

    
62
  /' NRT request type. '/
63
  $structure("urt_nrtrequest_t") {
64
    .. URT_CFG_RPC_PROFILING == true ..
65
      'Minimum latency ever detected.
66
    + {field} minLatency : urt_delay_t
67
      'Maximum latency ever detected.
68
    + {field} maxLatency : urt_delay_t
69
    __
70
      'Initializes a urt_nrtrequest_t object.
71
    + {method} urtNrtRequestInit (request : urt_nrtrequest_t*) : void
72
      'Acquire and lock an NRT request (blocking).
73
    + {method} urtNrtRequestAcquire (request : urt_nrtrequest_t*) : urt_status_t
74
      'Try to acquire and lock an NRT request (non blocking).
75
    + {method} urtNrtRequestTryAcquire (request : urt_nrtrequest_t*) : urt_status_t
76
      'Release an acquired/locked NRT request.
77
    + {method} urtNrtRequestRelease (request : urt_nrtrequest_t*) : urt_status_t
78
      'Submit an NRT request to the specified service.
79
    + {method} urtNrtRequestSubmit (request : urt_nrtrequest_t*, service : urt_service_t*) : urt_status_t
80
      'Retrieve an NRT request, thereby removing it from the service's request queue if required.
81
    + {method} urtNrtRequestRetrieve (request : urt_nrtrequest_t*) : urt_status_t
82
  }
83

    
84
  /' SRT request type. '/
85
  $structure("urt_srtrequest_t") {
86
    .. URT_CFG_RPC_PROFILING == true ..
87
      'Minimum latency ever detected.
88
    + {field} minLatency : urt_delay_t
89
      'Maximum latency ever detected.
90
    + {field} maxLatency : urt_delay_t
91
    __
92
      'Initializes a urt_srtrequest_t object.
93
    + {method} urtSrtRequestInit (request : urt_srtrequest_t*) : void
94
      'Acquire and lock an SRT request (blocking).
95
    + {method} urtSrtRequestAcquire (request : urt_srtrequest_t*) : urt_status_t
96
      'Try to acquire and lock an SRT request (non blocking).
97
    + {method} urtSrtRequestTryAcquire (request : urt_srtrequest_t*) : urt_status_t
98
      'Release an acquired/locked SRT request.
99
    + {method} urtSrtRequestRelease (request : urt_srtrequest_t*) : urt_status_t
100
      'Submit an SRT request to the specified service.
101
    + {method} urtSrtRequestSubmit (request : urt_srtrequest_t*, service : urt_service_t*) : urt_status_t
102
      'Retrieve an SRT request, thereby removing it from the service's request queue if required.
103
    + {method} urtSrtRequestRetrieve (request : urt_srtrequest_t*) : urt_status_t
104
      'Calculate the usefulness on an SRT RPC response.
105
    + {method} urtSrtCalculateUsefulness (request : urt_srtrequest_t*, usefulnesscb : urt_usefulness_f, cbparams : void*) : float
106
  }
107

    
108
  /' FRT request type. '/
109
  $structure("urt_frtrequest_t") {
110
    .. URT_CFG_RPC_QOS_DEADLINECHECKS == true ..
111
      'Maximum temporal offset between sending and consuming the FRT request.
112
    + {field} deadlineOffset : urt_delay_t
113
    .. URT_CFG_RPC_QOS_JITTERCHECKS == true ..
114
      'Maximum expected jitter.
115
    + {field} maxJitter : urt_delay_t
116
    .. URT_CFG_RPC_QOS_JITTERCHECKS == true || URT_CFG_RPC_PROFILING == true ..
117
      'Minimum latency ever detected (to calculate jitter).
118
    + {field} minLatency : urt_delay_t
119
      'Maximum latency ever detected (to calculate jitter).
120
    + {field} maxLatency : urt_delay_t
121
    __
122
      'Initializes a urt_frtrequest_t object.
123
    + {method} urtFrtRequestInit (request : urt_frtrequest_t*) : void
124
      'Acquire and lock an FRT request (blocking).
125
    + {method} urtFrtRequestAcquire (request : urt_frtrequest_t*) : urt_status_t
126
      'Try to acquire and lock an FRT request (non blocking).
127
    + {method} urtFrtRequestTryAcquire (request : urt_frtrequest_t*) : urt_status_t
128
      'Release an acquired/locked FRT request.
129
    + {method} urtFrtRequestRelease (request : urt_frtrequest_t*) : urt_status_t
130
      'Submit an FRT request to the specified service.
131
    + {method} urtFrtRequestSubmit (request : urt_frtrequest_t*, service : urt_service_t*, deadline : urt_delay_t) : urt_status_t
132
      'Retrieve an FRT request, thereby removing it from the service's request queue if required.
133
    + {method} urtFrtRequestRetrieve (request : urt_frtrequest_t*) : urt_status_t
134
      'Calculate the validity on an FRT RPC response.
135
    + {method} urtDrtCalculateValidity (request : urt_frtrequest_t) : bool
136
    .. URT_CFG_RPC_QOS_JITTERCHECKS == true ..
137
      'Get a pointer to the request's maximum jitter value.
138
    + {method} urtFrtRequestGetMaxJitter (request : urt_frtrequest_t*) : urt_delay_t* const
139
  }
140

    
141
  /' HRT request type. '/
142
  $structure("urt_hrtrequest_t") {
143
    .. URT_CFG_RPC_QOS_DEADLINECHECKS == true ..
144
      'Maximum temporal offset between sending and consuming the HRT request.
145
    + {field} deadlineOffset : urt_delay_t
146
    .. URT_CFG_RPC_QOS_JITTERCHECKS == true ..
147
      'Maximum expected jitter.
148
    + {field} maxJitter : urt_delay_t
149
    .. URT_CFG_RPC_QOS_DEADLINECHECKS == true || URT_CFG_RPC_QOS_JITTERCHECKS == true ..
150
      'QoS timer to detect missed deadlines and/or jitter.
151
    + {field} qosTimer : urt_osTimer_t
152
    .. URT_CFG_RPC_QOS_JITTERCHECKS == true || URT_CFG_RPC_PROFILING == true ..
153
      'Minimum latency ever detected (to calculate jitter).
154
    + {field} minLatency : urt_delay_t
155
      'Maximum latency ever detected (to calculate jitter).
156
    + {field} maxLatency : urt_delay_t
157
    __
158
      'Initializes a urt_hrtrequest_t object.
159
    + {method} urtHrtRequestInit (request : urt_hrtrequest_t*) : void
160
      'Acquire and lock an HRT request (blocking).
161
    + {method} urtHrtRequestAcquire (request : urt_hrtrequest_t*) : urt_status_t
162
      'Try to acquire and lock an HRT request (non blocking).
163
    + {method} urtHrtRequestTryAcquire (request : urt_hrtrequest_t*) : urt_status_t
164
      'Release an acquired/locked HRT request.
165
    + {method} urtHrtRequestRelease (request : urt_hrtrequest_t*) : urt_status_t
166
      'Submit an HRT request to the specified service.
167
    + {method} urtHrtRequestSubmit (request : urt_hrtrequest_t*, service : urt_service_t*, deadline : urt_delay_t) : urt_status_t
168
      'Retrieve an HRT request, thereby removing it from the service's request queue if required.
169
    + {method} urtHrtRequestRetrieve (request : urt_hrtrequest_t*) : urt_status_t
170
    .. URT_CFG_RPC_QOS_JITTERCHECKS == true ..
171
      'Get a pointer to the request's maximum jitter value.
172
    + {method} urtHrtRequestGetMaxJitter (request : urt_hrtrequest_t*) : urt_delay_t* const
173
  }
174
}
175

    
176
/' Service structure type. '/
177
$structure("urt_service_t") {
178
    'Pointer to the next service in a list.
179
  + {field} next : urt_service_t*
180
    'Identifier of the service.
181
  + {field} id : urt_serviceid_t
182
    'Mutex lock for exclusive access.
183
  + {field} lock : urt_osMutex_t
184
    'Pointer to the first element in a queue of pending requests.
185
  + {field} requestQueue_front : urt_baserequest_t*
186
    'Pointer to the last HRT request in a queue of pending requests.
187
  + {field} requestQueue_hrtBack : urt_hrtrequest_t*
188
    'Pointer to the last FRT/SRT request in a queue pf pending requests.
189
  + {field} requestQueue_fsrtBack : urt_baserequest_t*
190
    'Pointer to the last element in a queue of pending requests.
191
  + {field} requestQueue_back : urt_baserequest_t*
192
    'Event source to be fired by requests.
193
  + {field} evtSource : urt_osEventSource_t
194
    'Event listener to notify the service thread.
195
  + {field} evtListener : urt_osEventListener_t
196
  .. URT_CFG_RPC_PROFILING == true ..
197
    'Number of calls.
198
  + {field} numCalls : uint64_t
199
    'Number of lost ownerships.
200
  + {field} numOwnershipLost : uint64_t
201
  __
202
    'Initializes a urt_service_t object.
203
  + {method} urtServiceInit (service : urt_service_t*, id : urt_serviceid_t) : urt_status_t
204
    'Dispatch the next pending request.
205
  + {method} urtServiceDispatch (service : urt_service_t*, payload : void*, bytes : size_t) : urt_baserequest_t*
206
    'Acquire and lock the specified request (blocking).
207
  + {method} urtServiceAcquireRequest (service* urt_serviceid_t*, request : urt_baserequest_t*) : urt_status_t
208
    'Acquire and lock the specified request (non blocking).
209
  + {method} urtServiceTryAcquireRequest (service* urt_serviceid_t*, request : urt_baserequest_t*) : urt_status_t
210
    'Respond to a request.
211
  + {method} urtServiceRespond (request : urt_baserequest_t*) : urt_status_t
212
}
213

    
214
!endsub
215

    
216
/'### DEPENDENCIES & LAYOUT ##################################################'/
217

    
218
!startsub DEPENDENCIES
219

    
220
urt_baserequest_t "1" o- "0,1,2" urt_baserequest_t
221
urt_baserequest_t "1" o- "0,1" urt_service_t
222

    
223
urt_nrtrequest_t --|> urt_baserequest_t
224
urt_nrtrequest_t ..> urt_service_t
225

    
226
urt_srtrequest_t --|> urt_baserequest_t
227
urt_srtrequest_t ..> urt_service_t
228

    
229
urt_frtrequest_t --|> urt_baserequest_t
230
urt_frtrequest_t ..> urt_service_t
231

    
232
urt_hrtrequest_t --|> urt_baserequest_t
233
urt_hrtrequest_t ..> urt_service_t
234

    
235
urt_service_t "1" o- "0,1" urt_service_t
236
urt_service_t "1" o- "0,2,3" urt_baserequest_t
237
urt_service_t "1" o- "0,1" urt_hrtrequest_t
238

    
239
!endsub
240

    
241
/'### OUTRO ##################################################################'/
242

    
243
@enduml