docs/afb-events-guide.md

   1 # Guide for developing with events
   2
   3 Signaling agents are services that send events to any clients that
   4 subscribed for receiving it.
   5 The sent events carry any data.
   6
   7 To have a good understanding of how to:
   8
   9 - write a signaling agent.
  10 - actions of subscribing.
  11 - actions of unsubscribing.
  12 - actions of producing.
  13 - actions of sending and receiving.
  14
  15 Events must be described and explained.
  16
  17 ## Overview of events
  18
  19 The basis of a signaling agent is shown in the following figure:
  20
  21 ![scenario of using events](pictures/signaling-basis.svg)
  22
  23 This figure shows the main role of the signaling framework for the events
  24 propagation.
  25
  26 For people not familiar with the framework, a signaling agent and
  27 a “binding” are similar.
  28
  29 ### Subscribing and unsubscribing
  30
  31 - Subscribing is the action that makes a client able to receive
  32   data from a signaling agent.
  33
  34 Subscription must :
  35
  36 1. Create resources for generating the data.
  37 1. Delivering the data to the client.
  38
  39 These two aspects are not handled by the same piece of software.
  40
  41 1. Generating the data is the responsibility of the developer of the signaling agent
  42 1. Delivering the data is handled by the framework.
  43
  44 When a client subscribes for data, the agent must:
  45
  46 1. check that the subscription request is correct.
  47 1. establish the computation chain of the required data (if not already done).
  48 1. create a named event for the computed data (if not already done).
  49 1. ask the framework to establish the subscription to the event for the request.
  50 1. optionally give indications about the event in the reply to the client.
  51
  52 The first two steps are not involving the framework.
  53 They are linked to the business logic of the binding.
  54 The request can be any description of the requested data
  55 and the computing stream can be of any nature,
  56 this is specific to the binding.
  57
  58 As said before, the framework uses and integrates **libsystemd** and its event
  59 loop.
  60 Within the framework, **libsystemd** is the standard API/library for
  61 bindings expecting to setup and handle I/O, timer or signal events.
  62
  63 Steps 3 and 4 are bound to the framework.
  64
  65 The agent must create an object for handling the propagation of produced
  66 data to its clients.
  67 That object is called “event” in the framework.
  68 An event has a name that allows clients to distinguish it from other
  69 events.
  70
  71 Events are created using the ***afb\_daemon\_make\_event*** function
  72 that takes the name of the event.
  73 Example:
  74
  75 ```C
  76     event = afb_daemon_make_event(name);
  77 ```
  78
  79 Once created, the event can be used either to push data to its
  80 subscribers or to broadcast data to any listener.
  81
  82 The event must be used to establish the subscription for the requesting
  83 client.
  84 This is done using the ***afb\_req\_subscribe*** function
  85 that takes the current request object and event and associates them
  86 together.
  87 Example:
  88
  89 ```C
  90     rc = afb_req_subscribe(req, event);
  91 ```
  92
  93 When successful, this function make the connection between the event and
  94 the client that emitted the request.
  95 The client becomes a subscriber of the event until it unsubscribes or disconnects.
  96 The ***afb\_req\_subscribe*** function will fail:
  97
  98 - if the client connection is weak.
  99 - if the request comes from a HTTP link.
 100
 101 To receive signals, the client must be connected.
 102
 103 The AGL framework allows connections using WebSocket.
 104
 105 The name of the event is either a well known name or an ad hoc name
 106 forged for the use case.
 107
 108 Let's see a basic example:
 109
 110 - client A expects to receive the speed in km/h every second.
 111 - client B expects the speed in mph twice a second.
 112
 113 In that case, there are two different events because it is not the same
 114 unit and it is not the same frequency.
 115 Having two different events allows to associate clients to the correct event.
 116 But this doesn't tell any word about the name of these events.
 117 The designer of the signaling agent has two options for naming:
 118
 119 1. names can be the same (“speed” for example) with sent data
 120   self describing itself or having a specific tag (requiring from
 121   clients awareness about requesting both kinds of speed isn't safe).
 122 1. names of the event include the variations (by example:
 123   “speed-km/h-1Hz” and “speed-mph-2Hz”) and, in that case, sent data
 124   can self describe itself or not.
 125
 126 In both cases, the signaling agent might have to send the name of the
 127 event and/or an associated tag to its client in the reply of the
 128 subscription.
 129 This is part of the step 5 above.
 130
 131 The framework only uses the event (not its name) for:
 132
 133 - subscription
 134 - un-subscription
 135 - pushing
 136
 137 When the requested data is already generated and the event used for
 138 pushing it already exists, the signaling agent must not instantiate a
 139 new processing chain and must not create a new event object for pushing
 140 data.
 141 The signaling agent must reuse the existing chain and event.
 142
 143 Unsubscribing is made by the signaling agent on a request of its client.
 144 The ***afb\_req\_unsubscribe*** function tells the framework to
 145 remove the requesting client from the event's list of subscribers.
 146 Example:
 147
 148 ```C
 149     afb_req_unsubscribe(req, event);
 150 ```
 151
 152 Subscription count does not matter to the framework:
 153
 154 - Subscribing the same client several times has the same effect that subscribing only one time.
 155
 156 Thus, when unsubscribing is invoked, it becomes immediately effective.
 157
 158 #### More on naming events
 159
 160 - Within the AGL framework, a signaling agent is a binding that has an API prefix.
 161
 162 This prefix is meant to be unique and to identify the binding API.
 163 The names of the events that this signaling agent creates are
 164 automatically prefixed by the framework, using the API prefix of the
 165 binding.
 166
 167 Thus, if a signaling agent of API prefix ***api*** creates an event
 168 of name ***event*** and pushes data to that event, the subscribers
 169 will receive an event of name ***api/event***.
 170
 171 ### Generating and pushing signals and data
 172
 173 - This of the responsibility of the designer of the signaling agent to establish the processing chain for generating events.
 174
 175 In many cases, this can be achieved using I/O or timer or signal events inserted in the main loop.
 176 For this case, the AGL framework uses **libsystemd** and
 177 provide a way to integrates to the main loop of this library using
 178 afb\_daemon\_get\_event\_loop.
 179 Example:
 180
 181 ```C
 182     sdev = afb_daemon_get_event_loop();
 183     rc = sd_event_add_io(sdev, &source, fd, EPOLLIN, myfunction, NULL);
 184 ```
 185
 186 In some other cases, the events are coming from D-Bus.
 187 In that case, the framework also uses **libsystemd** internally to access D-Bus.
 188 It provides two methods to get the available D-Bus objects, already existing and
 189 bound to the main **libsystemd** event loop.
 190 Use either ***afb\_daemon\_get\_system\_bus*** or
 191 ***afb\_daemon\_get\_user\_bus*** to get the required instance.
 192 Then use functions of **libsystemd** to handle D-Bus.
 193
 194 In some rare cases, the generation of the data requires to start a new
 195 thread.
 196
 197 When a data is generated and ready to be pushed, the signaling agent
 198 should call the function ***afb\_event\_push***.
 199 Example:
 200
 201 ```C
 202     rc = afb_event_push(event, JSON);
 203     if (rc == 0) {
 204         stop_generating(event);
 205         afb_event_drop(event);
 206     }
 207 ```
 208
 209 The function ***afb\_event\_push*** pushes json data to all the subscribers.
 210 It then returns the count of subscribers.
 211 When the count is zero, there is no subscriber listening for the event.
 212 The example above shows that in that case, the signaling agent stops to generate data for the event and delete the event using afb\_event\_drop.
 213 This is one possible option.
 214 Other valuable options are:
 215
 216 - do nothing and continue to generate and push the event.
 217 - just stop to generate and push the data but keep the event existing.
 218
 219 ### Receiving the signals
 220
 221 Understanding what a client expects when it receives signals, events or
 222 data shall be the most important topic of the designer of a signaling
 223 agent.
 224 The good point here is that because JSON[^1] is the exchange
 225 format, structured data can be sent in a flexible way.
 226
 227 The good design is to allow as much as possible the client to describe
 228 what is needed with the goal to optimize the processing to the
 229 requirements only.
 230
 231 ### The exceptional case of wide broadcast
 232
 233 Some data or events have so much importance that they can be widely
 234 broadcasted to alert any listening client.
 235 Examples of such an alert are:
 236
 237 - system is entering/leaving “power safe” mode
 238 - system is shutting down
 239 - the car starts/stops moving
 240 - ...
 241
 242 An event can be broadcasted using one of the two following methods:
 243
 244 - ***afb\_daemon\_broadcast\_event***
 245 - ***afb\_event\_broadcast***
 246
 247 Example 1:
 248
 249 ```C
 250 afb_daemon_broadcast_event(name, json);
 251 ```
 252
 253 Example 2:
 254
 255 ```C
 256 event = afb_daemon_make_event(name);
 257 . . . .
 258 afb_event_broadcast(event, json);
 259 ```
 260
 261 As for other events, the name of events broadcasted using
 262 ***afb\_daemon\_broadcast\_event*** are automatically prefixed by
 263 the framework with API prefix of the binding (signaling agent).
 264
 265 ## Reference of functions
 266
 267 ### Function afb\_event afb\_daemon\_make\_event
 268
 269 The function ***afb\_daemon\_make\_event*** that is defined as below:
 270
 271 ```C
 272 /*
 273  * Creates an event of 'name' and returns it.
 274  */
 275 struct afb_event afb_daemon_make_event(const char *name);
 276 ```
 277
 278 The correct way to create the event at initialization is to call the function
 279 ***afb\_daemon\_make\_event*** within the initialization
 280 function referenced by the field ***init*** of the structure ***afbBindingV2***.
 281
 282 ### Function afb\_event\_push
 283
 284 The function ***afb\_event\_push*** is defined as below:
 285
 286 ```C
 287 /*
 288  * Pushes the 'event' with the data 'object' to its observers.
 289  * 'object' can be NULL.
 290  *
 291  * For convenience, the function calls 'json_object_put' for object'.
 292  * Thus, in the case where 'object' should remain available after
 293  * the function returns, the function 'json_object_get' shall be used.
 294  *
 295  * Returns the count of clients that received the event.
 296  */
 297 int afb_event_push(struct afb_event event, struct json_object *object);
 298 ```
 299
 300 As the function ***afb\_event\_push*** returns 0 when there is no
 301 more subscriber, a binding can remove such unexpected event using the
 302 function ***afb\_event\_drop***.
 303
 304 ### Function afb\_event\_drop
 305
 306 The function ***afb\_event\_drop*** is defined as below:
 307
 308 ```C
 309 /*
 310  * Drops the data associated to the event
 311  * After calling this function, the event
 312  * MUST NOT BE USED ANYMORE.
 313  */
 314 void afb_event_drop(struct afb_event event);
 315 ```
 316
 317 ### Function afb\_req\_subscribe
 318
 319 The function ***afb\_req\_subscribe*** is defined as below:
 320
 321 ```C
 322 /*
 323  * Establishes for the client link identified by 'req' a subscription
 324  * to the 'event'.
 325  * Returns 0 in case of successful subscription or -1 in case of error.
 326  */
 327 int afb_req_subscribe(struct afb_req req, struct afb_event event);
 328 ```
 329
 330 The subscription adds the client of the request to the list of subscribers
 331 to the event.
 332
 333 ### Function afb\_req\_unsubscribe
 334
 335 The function ***afb\_req\_unsubscribe*** is defined as
 336 below:
 337
 338 ```C
 339 /*
 340  * Revokes the subscription established to the 'event' for the client
 341  * link identified by 'req'.
 342  * Returns 0 in case of successful un-subscription or -1 in case of error.
 343  */
 344 int afb_req_unsubscribe(struct afb_req req, struct afb_event event);
 345 ```
 346
 347 The un-subscription removes the client of the request of the
 348 list of subscribers to the event.
 349 When the list of subscribers to the event becomes empty,
 350 the function ***afb\_event\_push*** will return zero.
 351
 352 ### Function afb\_event\_broadcast
 353
 354 The function ***afb\_event\_broadcast*** is defined as below:
 355
 356 ```C
 357 /*
 358  * Broadcasts widely the 'event' with the data 'object'.
 359  * 'object' can be NULL.
 360  *
 361  * For convenience, the function calls 'json_object_put' for 'object'.
 362  * Thus, in the case where 'object' should remain available after
 363  * the function returns, the function 'json_object_get' shall be used.
 364  *
 365  * Returns the count of clients that received the event.
 366  */
 367 int afb_event_broadcast(struct afb_event event, struct json_object *object);
 368 ```
 369
 370 This uses an existing event (created with ***afb\_daemon\_make\_event***)
 371 for broadcasting an event having its name.
 372
 373 ### Function afb\_daemon\_broadcast\_event
 374
 375 The function ***afb\_daemon\_broadcast\_event*** is defined as below:
 376
 377 ```C
 378 /*
 379  * Broadcasts widely the event of 'name' with the data 'object'.
 380  * 'object' can be NULL.
 381  *
 382  * For convenience, the function calls 'json_object_put' for 'object'.
 383  * Thus, in the case where 'object' should remain available after
 384  * the function returns, the function 'json_object_get' shall be used.
 385  *
 386  * Returns the count of clients that received the event.
 387  */
 388 int afb_daemon_broadcast_event(const char *name, struct json_object *object);
 389 ```
 390
 391 The name is given here explicitly.
 392 The name is automatically prefixed with the name of the binding.
 393 For example, a binding of prefix "xxx" would broadcast the event "xxx/name".
 394
 395 ### Function onevent (field of afbBindingV2)
 396
 397 Binding can designate an event handling function using the field **onevent**
 398 of the structure **afbBindingV2**.
 399 This function is called when an event is broadcasted or when an event the
 400 binding subscribed to is pushed.
 401 That allow a service to react to an event and do what it is to do if this is
 402 relevant for it.
 403 (ie: car back camera detects imminent collision and broadcast it, then
 404 appropriate service enable parking brake.).