docs/4_APIs_and_Services/4.3_Application_Framework_Binder/4_Binder_events_guide/Binder_events_guide.md

   1 ---
   2 edit_link: ''
   3 title: Binder events guide
   4 origin_url: >-
   5   https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-events-guide.md?h=master
   6 ---
   7
   8 <!-- WARNING: This file is generated by fetch_docs.js using /home/boron/Documents/AGL/docs-webtemplate/site/_data/tocs/apis_services/master/app-framework-binder-developer-guides-api-services-book.yml -->
   9
  10 # Guide for developing with events
  11
  12 Signaling agents are services that send events to any clients that
  13 are subscribed to receive it.
  14 The sent events carry any data.
  15
  16 To have a good understanding of how to:
  17
  18 - write a signaling agent.
  19 - actions of subscribing.
  20 - actions of unsubscribing.
  21 - actions of producing.
  22 - actions of sending and receiving.
  23
  24 Events must be described and explained.
  25
  26 ## Overview of events
  27
  28 The basis of a signaling agent is shown in the following figure:
  29
  30 ![scenario of using events](pictures/signaling-basis.svg)
  31
  32 This figure shows the main role of the signaling framework for the events
  33 propagation.
  34
  35 For people not familiar with the framework, a signaling agent and
  36 a “binding” are similar.
  37
  38 ### Subscribing and unsubscribing
  39
  40 - Subscribing is the action that makes a client able to receive
  41   data from a signaling agent.
  42
  43 Subscription must :
  44
  45 1. Create resources for generating the data.
  46 1. Deliver the data to the client.
  47
  48 These two aspects are not handled by the same piece of software.
  49
  50 1. Generating the data is the responsibility of the developer of the signaling agent
  51 1. Delivering the data is handled by the framework.
  52
  53 When a client subscribes for data, the agent must:
  54
  55 1. Check that the subscription request is correct.
  56 1. Establish the computation chain of the required data (if not already done).
  57 1. Create a named event for the computed data (if not already done).
  58 1. Ask the framework to establish the subscription to the event for the request.
  59 1. Optionally give indications about the event in the reply to the client.
  60
  61 The first two steps do not involve the framework.
  62 They are linked to the business logic of the binding.
  63 The request can be any description of the requested data
  64 and the computing stream can be of any nature,
  65 this is specific to the binding.
  66
  67 As said before, the framework uses and integrates **libsystemd** and its event
  68 loop.
  69 Within the framework, **libsystemd** is the standard API/library for
  70 bindings expecting to setup and handle I/O, timer or signal events.
  71
  72 Steps 3 and 4 are bound to the framework.
  73
  74 The agent must create an object for handling the propagation of produced
  75 data to its clients.
  76 That object is called “event” in the framework.
  77 An event has a name that allows clients to distinguish it from other
  78 events.
  79
  80 Events are created using the ***afb\_api\_make\_event*** function
  81 that takes the api that creates the event and the name of the event.
  82 Example:
  83
  84 ```C
  85     event = afb_api_make_event(api, name);
  86 ```
  87
  88 Once created, the event can be used either to push data to its
  89 subscribers or to broadcast data to any listener.
  90
  91 The event must be used to establish the subscription for the requesting
  92 client.
  93 This is done using the ***afb\_req\_subscribe*** function
  94 that takes the current request object and event and associates them
  95 together.
  96 Example:
  97
  98 ```C
  99     rc = afb_req_subscribe(req, event);
 100 ```
 101
 102 When successful, this function make the connection between the event and
 103 the client that emitted the request.
 104 The client becomes a subscriber of the event until it unsubscribes or disconnects.
 105 The ***afb\_req\_subscribe*** function will fail:
 106
 107 - if the client connection is weak.
 108 - if the request comes from a HTTP link.
 109
 110 To receive signals, the client must be connected.
 111
 112 The AGL framework allows connections using WebSocket.
 113
 114 The name of the event is either a well known name or an ad hoc name
 115 forged for the use case.
 116
 117 Let's see a basic example:
 118
 119 - client A expects to receive the speed in km/h every second.
 120 - client B expects the speed in mph twice a second.
 121
 122 In that case, there are two different events because it is not the same
 123 unit and it is not the same frequency.
 124 Having two different events allows to associate clients to the correct event.
 125 But this doesn't tell any word about the name of these events.
 126 The designer of the signaling agent has two options for naming:
 127
 128 1. names can be the same (“speed” for example) with sent data
 129   self describing itself or having a specific tag (requiring from
 130   clients awareness about requesting both kinds of speed isn't safe).
 131 1. names of the event include the variations (by example:
 132   “speed-km/h-1Hz” and “speed-mph-2Hz”) and, in that case, sent data
 133   can self describe itself or not.
 134
 135 In both cases, the signaling agent might have to send the name of the
 136 event and/or an associated tag to its client in the reply of the
 137 subscription.
 138 This is part of the step 5 above.
 139
 140 The framework only uses the event (not its name) for:
 141
 142 - subscription
 143 - un-subscription
 144 - pushing
 145
 146 When the requested data is already generated and the event used for
 147 pushing it already exists, the signaling agent must not instantiate a
 148 new processing chain and must not create a new event object for pushing
 149 data.
 150 The signaling agent must reuse the existing chain and event.
 151
 152 Unsubscribing is made by the signaling agent on a request of its client.
 153 The ***afb\_req\_unsubscribe*** function tells the framework to
 154 remove the requesting client from the event's list of subscribers.
 155 Example:
 156
 157 ```C
 158     afb_req_unsubscribe(req, event);
 159 ```
 160
 161 Subscription count does not matter to the framework:
 162
 163 - Subscribing the same client several times has the same effect that subscribing only one time.
 164
 165 Thus, when unsubscribing is invoked, it becomes immediately effective.
 166
 167 #### More on naming events
 168
 169 - Within the AGL framework, a signaling agent is a binding that has an API prefix.
 170
 171 This prefix is meant to be unique and to identify the binding API.
 172 The names of the events that this signaling agent creates are
 173 automatically prefixed by the framework, using the API prefix of the
 174 binding.
 175
 176 Thus, if a signaling agent of API prefix ***api*** creates an event
 177 of name ***event*** and pushes data to that event, the subscribers
 178 will receive an event of name ***api/event***.
 179
 180 ### Generating and pushing signals and data
 181
 182 - This of the responsibility of the designer of the signaling agent to establish the processing chain for generating events.
 183
 184 In many cases, this can be achieved using I/O or timer or signal events inserted in the main loop.
 185 For this case, the AGL framework uses **libsystemd** and
 186 provide a way to integrates to the main loop of this library using
 187 afb\_api\_get\_event\_loop.
 188 Example:
 189
 190 ```C
 191     sdev = afb_api_get_event_loop(api);
 192     rc = sd_event_add_io(sdev, &source, fd, EPOLLIN, myfunction, NULL);
 193 ```
 194
 195 In some other cases, the events are coming from D-Bus.
 196 In that case, the framework also uses **libsystemd** internally to access D-Bus.
 197 It provides two methods to get the available D-Bus objects, already existing and
 198 bound to the main **libsystemd** event loop.
 199 Use either ***afb\_api\_get\_system\_bus*** or
 200 ***afb\_api\_get\_user\_bus*** to get the required instance.
 201 Then use functions of **libsystemd** to handle D-Bus.
 202
 203 In some rare cases, the generation of the data requires to start a new
 204 thread.
 205
 206 When a data is generated and ready to be pushed, the signaling agent
 207 should call the function ***afb\_event\_push***.
 208 Example:
 209
 210 ```C
 211     rc = afb_event_push(event, JSON);
 212     if (rc == 0) {
 213         stop_generating(event);
 214         afb_event_unref(event);
 215     }
 216 ```
 217
 218 The function ***afb\_event\_push*** pushes json data to all the subscribers.
 219 It then returns the count of subscribers.
 220 When the count is zero, there is no subscriber listening for the event.
 221 The example above shows that in that case, the signaling agent stops to
 222 generate data for the event and tells that it doesn't use it anymore by calling
 223 **afb\_event\_unref**.
 224
 225 This is one possible option.
 226 Other valuable options are:
 227
 228 - do nothing and continue to generate and push the event.
 229 - just stop to generate and push the data but keep the event existing.
 230
 231 ### Receiving the signals
 232
 233 Understanding what a client expects when it receives signals, events or
 234 data shall be the most important topic of the designer of a signaling
 235 agent.
 236 The good point here is that because JSON[^1] is the exchange
 237 format, structured data can be sent in a flexible way.
 238
 239 The good design is to allow as much as possible the client to describe
 240 what is needed with the goal to optimize the processing to the
 241 requirements only.
 242
 243 ### The exceptional case of wide broadcast
 244
 245 Some data or events have so much importance that they can be widely
 246 broadcasted to alert any listening client.
 247 Examples of such an alert are:
 248
 249 - system is entering/leaving “power safe” mode
 250 - system is shutting down
 251 - the car starts/stops moving
 252 - ...
 253
 254 An event can be broadcasted using one of the two following methods:
 255
 256 - ***afb\_api\_broadcast\_event***
 257 - ***afb\_event\_broadcast***
 258
 259 Example 1:
 260
 261 ```C
 262 afb_api_broadcast_event(api, name, json);
 263 ```
 264
 265 Example 2:
 266
 267 ```C
 268 event = afb_api_make_event(api, name);
 269 . . . .
 270 afb_event_broadcast(event, json);
 271 ```
 272
 273 As for other events, the name of events broadcasted using
 274 ***afb\_api\_broadcast\_event*** are automatically prefixed by
 275 the framework with API prefix.
 276
 277 ## Reference of functions
 278
 279 See the [references for functions of class afb_event](reference-v3/func-event.html)
 280
 281 ### Function onevent (field of afbBindingExport)
 282
 283 Binding can designate an event handling function using the field **onevent**
 284 of the structure **afb_binding_t**.
 285
 286 This function is called when an event is broadcasted or when an event that the
 287 api subscribed to (through call or subcall mechanism) is pushed.
 288 That behavior allows a service to react to an event and do what it is to do if
 289 this is relevant for it.
 290 (ie: car back camera detects imminent collision and broadcast it, then
 291 appropriate service enable parking brake.).
 292
 293 ### Event handlers
 294
 295 The apis functions allow to declare event handling callbacks. These callbacks are
 296 called on reception of an  event matching a pattern and a receive in more that
 297 the event name and its companion JSON data, a user defiend closure and the api
 298 that is used to create it.