Debian Codegraph @

docs/rst/design/events_and_hooks.rst

raw
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.