docs/afb-events-guide.md

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