Debian Codegraph @

src/scripts/linking/README.rst

raw
1 Linking Scripts
2 ===============
3
4 These scripts contain all the logic for creating links between nodes.
5 This involves, to a large extent, deciding which links to create.
6
7 Hooks
8 -----
9
10 The hooks in this section are organized in 3 sub-categories. The first category
11 includes hooks that are triggered by changes in the graph. Some of them are tasked
12 to schedule a "rescan-for-linking" event, which is the lowest priority linking event and
13 its purpose is to scan through all the linkable session items and link them
14 to a particular target. The "rescan-for-linking" event is always scheduled to run
15 once for all the graph changes in a cycle. This is achieved by flagging the event
16 as already scheduled in the module-standard-event-source; this flag is then cleared
17 by a hook that runs on this event.
18
19 Selecting a target for each linkable and linking to it is deferred to another
20 set of hooks by pushing a "select-target" event for each linkable. This event
21 is the highest priority event and therefore no other changes in the graph are
22 processed while targets are being selected.
23
24 .. list-table:: Hooks triggered by changes in the graph
25 :header-rows: 1
26
27 * - Hook name
28 - File
29 - Triggered by
30 - Action
31
32 * - linking/rescan-trigger
33 - rescan.lua
34 - linkable SI added|removed or metadata-changed
35 - schedules rescan-for-linking event
36
37 * - linking/linkable-removed
38 - rescan.lua
39 - linkable SI removed
40 - destroys links related to the removed linkable
41
42 * - linking/follow
43 - move-follow.lua
44 - metadata-changed
45 - schedules rescan-for-linking when the configured default sources/sinks are changed by the user
46
47 * - linking/move
48 - move-follow.lua
49 - metadata-changed
50 - schedules rescan-for-linking when node target metadata properties are changed
51
52 * - linking/rescan-media-role-links
53 - rescan-media-role-links.lua
54 - link SI added, removed or metadata-changed
55 - activates or deactivates role-based links based on role priorities and actions
56
57 .. list-table:: rescan-for-linking hooks, in order of execution
58 :header-rows: 1
59 :width: 100%
60 :widths: 20 20 60
61
62 * - Hook name
63 - File
64 - Description
65
66 * - m-standard-event-source/rescan-done
67 - module-standard-event-source.c
68 - clears the rescan_scheduled flag
69
70 * - linking/rescan
71 - rescan.lua
72 - schedules select-target for each linkable session item
73
74 .. list-table:: select-target hooks, in order of execution
75 :header-rows: 1
76 :width: 100%
77 :widths: 20 20 60
78
79 * - Hook name
80 - File
81 - Description
82
83 * - linking/find-defined-target
84 - find-defined-target.lua
85 - Select the target that has been defined explicitly by the 'target.object' property or metadata
86
87 * - linking/find-filter-target
88 - find-filter-target.lua
89 - Select the target of a filter node, if the subject is a filter node
90
91 * - linking/find-media-role-target
92 - find-media-role-target.lua
93 - Select the target based on the stream's media.role and the target's device.intended-roles
94
95 * - linking/find-default-target
96 - find-default-target.lua
97 - Select the default source/sink as target
98
99 * - linking/find-best-target
100 - find-best-target.lua
101 - Select target based on priority.session
102
103 * - linking/get-filter-from-target
104 - get-filter-from-target.lua
105 - Translate the found target to a filter target that should be linked instead
106
107 * - linking/prepare-link
108 - prepare-link.lua
109 - Break existing link if needed, check if the target is available for linking; send error to the client if needed
110
111 * - linking/link-target
112 - link-target.lua
113 - Create si-standard-link session item to create links between the subject linkable and the selected target