| 1 |
.. _design_events_and_hooks: |
| 2 |
|
| 3 |
Events and Hooks |
| 4 |
================ |
| 5 |
|
| 6 |
Session management is all about reacting to events and taking necessary |
| 7 |
actions. This is why WirePlumber's logic is all built on events and hooks. |
| 8 |
|
| 9 |
Events |
| 10 |
------ |
| 11 |
|
| 12 |
Events are objects that represent a change that has just happened on a PipeWire |
| 13 |
object, or just a trigger for making a decision and potentially taking some |
| 14 |
action. |
| 15 |
|
| 16 |
Every event has a source, a subject and some properties, which include the |
| 17 |
event type. |
| 18 |
|
| 19 |
* The ``source`` is a reference to the GObject that created this event. |
| 20 |
Typically, this is the ``WpStandardEventSource`` plugin. |
| 21 |
* The ``subject`` is an *optional* reference to the object that this event |
| 22 |
is about. For example, in a ``node-added`` event, the ``subject`` would be |
| 23 |
a reference to the ``WpNode`` object that was just added. Some events, |
| 24 |
especially those which are used only to trigger actions, do not have a |
| 25 |
subject. |
| 26 |
* The ``properties`` is a dictionary that contains information about the event, |
| 27 |
including the event type, and also includes all the PipeWire properties of the |
| 28 |
``subject``, if there is one. |
| 29 |
* The ``event.type`` property describes the nature of the event, for example |
| 30 |
``node-added`` or ``metadata-changed`` are some valid event types. |
| 31 |
|
| 32 |
Every event also has a priority. Events with a higher priority are processed |
| 33 |
before events with a lower priority. When two or more events have the same |
| 34 |
priority, they are processed in a first-in-first-out manner. This logic |
| 35 |
is defined in the *event dispatcher*. |
| 36 |
|
| 37 |
Events are short-lived objects. They are created at the time that something is |
| 38 |
happening and they are destroyed after they get processed. Processing an event |
| 39 |
means executing all the hooks that are associated with it. The next section |
| 40 |
explains what hooks are and how they are associated with events. |
| 41 |
|
| 42 |
Hooks |
| 43 |
----- |
| 44 |
|
| 45 |
Hooks are objects that represent a runnable action that needs to be executed |
| 46 |
when a certain event is processed. Every hook, therefore, consists of a |
| 47 |
function - synchronous or asynchronous - that can be executed. Additionally, |
| 48 |
every hook has a means to associate itself with specific events. This is |
| 49 |
normally done by declaring *interest* to specific event properties or |
| 50 |
combinations of them. |
| 51 |
|
| 52 |
There are two main types of hooks: ``SimpleEventHook`` and ``AsyncEventHook``. |
| 53 |
|
| 54 |
* ``SimpleEventHook`` contains a single, synchronous function. As soon as this |
| 55 |
function is executed, the hook is completed. |
| 56 |
* ``AsyncEventHook`` contains multiple functions, combined together in a state |
| 57 |
machine using ``WpTransition`` underneath. The hook is completed only after |
| 58 |
the state machine reaches its final state and this can take any amount of time |
| 59 |
necessary. |
| 60 |
|
| 61 |
Every hook also has a name, which can be an arbitrary string of characters. |
| 62 |
Additionally, it has two arrays of names, which declare dependencies between |
| 63 |
this hook and others. One array is called ``before`` and the other is called |
| 64 |
``after``. The hook names in the ``before`` array specify that this hook must |
| 65 |
be executed *before* those other hooks. Similarly, the hook names in the |
| 66 |
``after`` array specify that this hook must be executed *after* those other |
| 67 |
hooks. Using this mechanism, it is possible to define the order in which |
| 68 |
hooks will be executed, for a specific event. |
| 69 |
|
| 70 |
Hooks are long-lived objects. They are created once, registered in the |
| 71 |
*event dispatcher*, they are attached on events and detached after their |
| 72 |
execution. They don't maintain any internal state, so the actions of the hook |
| 73 |
depend solely on the event itself. |
| 74 |
|
| 75 |
The Event Dispatcher |
| 76 |
-------------------- |
| 77 |
|
| 78 |
The event dispatcher is a (per core) singleton object that processes all events |
| 79 |
and also maintains a list of all the registered hooks. It has a method to |
| 80 |
*push* events on it, which causes them to be scheduled for processing. |
| 81 |
|
| 82 |
Scheduling of events and hooks |
| 83 |
------------------------------ |
| 84 |
|
| 85 |
The main idea and reasoning behind this architecture is to have everything |
| 86 |
execute in a predefined order and always wait for an action to finish before |
| 87 |
executing the next one. |
| 88 |
|
| 89 |
Every event has a *priority* and every hook also has an order of execution that |
| 90 |
derives from the inter-dependencies between hooks, which are defined with |
| 91 |
``before`` and ``after`` (see above). When an event is pushed on the dispatcher, |
| 92 |
the dispatcher goes through all the registered hooks and checks which hooks are |
| 93 |
configured to run on this event (their event interest matches the event). |
| 94 |
It then makes a list of them, sorted by their order of execution, and stores it |
| 95 |
on the event. The event is then added on the dispatcher's list of events, which |
| 96 |
is sorted by priority. |
| 97 |
|
| 98 |
For example:: |
| 99 |
|
| 100 |
List of events |
| 101 |
| event1 (prio 99) -> hook1, hook2, hook3 |
| 102 |
| event2 (prio 50) -> hook5, hook2, hook4 |
| 103 |
v |
| 104 |
|
| 105 |
The dispatcher has an internal ``GSource`` that is registered with |
| 106 |
``G_PRIORITY_HIGH_IDLE`` priority. When there is at least one event in the |
| 107 |
list of events, the source is dispatched. Every time it gets dispatched, |
| 108 |
it takes the top-most event (the highest priority one) and executes the highest |
| 109 |
priority hook in that event. If the hook executes synchronously, it then takes |
| 110 |
the next hook and continues until there are no more hooks on this event; |
| 111 |
then it goes to the next event, and so on. If the hook, however, executes |
| 112 |
asynchronously, processing stops until the hook finishes; after finishing, |
| 113 |
processing resumes like before. |
| 114 |
|
| 115 |
It is important to notice here that the list of events may be modified while |
| 116 |
events are getting processed. For example, a device is added; that's a |
| 117 |
``device-added`` event. Then a hook is executed to set the profile. That creates |
| 118 |
nodes, so a couple of ``node-added`` events... But there is also another hook to |
| 119 |
set the route, which was attached on the ``device-added`` event for the device. |
| 120 |
Suppose that we give the ``node-added`` events lower priority than the |
| 121 |
``device-added`` events, then the ``set-route`` hook will execute right after |
| 122 |
the ``set-profile`` and before any ``node-added`` events are processed. |
| 123 |
|
| 124 |
Visually, with sample priorities:: |
| 125 |
|
| 126 |
List of events |
| 127 |
| "device-added" (prio 20) -> set-profile, set-route |
| 128 |
| "node-added" (prio 10) -> restore-stream, create-session-item |
| 129 |
v |
| 130 |
|
| 131 |
Obviously, there can also be a case where a newly added event has higher |
| 132 |
priority than the event that was being processed before. In that case, |
| 133 |
processing the hooks of the original event is stopped until all the hooks from |
| 134 |
the higher priority event have been processed. For example, a capture stream |
| 135 |
node being added may trigger the "bluetooth autoswitch" hook, which will then |
| 136 |
change the profile of a device. Changing the profile also has to trigger setting |
| 137 |
a new route and also handling the new device nodes, creating session items for |
| 138 |
them... After all this is done, processing the original capture stream |
| 139 |
``node-added`` event can continue. |