Debian Codegraph @

docs/rst/scripting/lua_api/lua_gobject.rst

raw
1 .. _lua_gobject:
2
3 GObject Integration
4 ===================
5
6 The Lua engine that powers WirePlumber's scripts provides direct integration
7 with `GObject`_. Most of the objects that you will deal with in the lua scripts
8 are wrapping GObjects. In order to work with the scripts, you will first need
9 to have a basic understanding of GObject's basic concepts, such as signals and
10 properties.
11
12 Properties
13 ----------
14
15 All GObjects have the ability to have `properties`_.
16 In C we normally use `g_object_get`_ to retrieve them and `g_object_set`_
17 to set them.
18
19 In WirePlumber's lua engine, these properties are exposed as object members
20 of the Lua object.
21
22 For example:
23
24 .. code-block:: lua
25
26 -- read the "bound-id" GObject property from the proxy
27 local proxy = function_that_returns_a_wp_proxy()
28 local proxy_id = proxy["bound-id"]
29 print("Bound ID: " .. proxy_id)
30
31 Writable properties can also be set in a similar fashion:
32
33 .. code-block:: lua
34
35 -- set the "scale" GObject property to the enum value "cubic"
36 local mixer = ...
37 mixer["scale"] = "cubic"
38
39 Signals
40 -------
41
42 GObjects also have a generic mechanism to deliver events to external callbacks.
43 These events are called `signals`_.
44 To connect to a signal and handle it, you may use the *connect* method:
45
46 .. function:: GObject.connect(self, detailed_signal, callback)
47
48 Connects the signal to a callback. When the signal is emitted by the
49 underlying object, the callback will be executed.
50
51 The signature of the callback is expected to match the signature of the
52 signal, with the first parameter being the object itself.
53
54 **Example:**
55
56 .. code-block:: lua
57
58 -- connects the "bound" signal from WpProxy to a callback
59 local proxy = function_that_returns_a_wp_proxy()
60 proxy:connect("bound", function(p, id)
61 print("Proxy " .. tostring(p) .. " bound to " .. tostring(id))
62 end)
63
64 In this example, the ``p`` variable in the callback is the ``proxy`` object,
65 while ``id`` is the first parameter of the *"bound"* signal, as documented
66 in :c:struct:`WpProxy`
67
68 :param detailed_signal: the signal name to listen to
69 (of the form "signal-name::detail")
70 :param callback: a lua function that will be called when the signal is emitted
71
72 Signals may also be used as a way to have dynamic methods on objects. These
73 signals are meant to be called by external code and not handled. These signals
74 are called **action signals**.
75 You may call an action signal using the *call* method:
76
77 .. function:: GObject.call(self, action_signal, ...)
78
79 Calls an action signal on this object.
80
81 **Example:**
82
83 .. code-block:: lua
84
85 Core.require_api("default-nodes", "mixer", function(...)
86 local default_nodes, mixer = ...
87
88 -- "get-default-node" and "get-volume" are action signals of the
89 -- "default-nodes-api" and "mixer-api" plugins respectively
90 local id = default_nodes:call("get-default-node", "Audio/Sink")
91 local volume = mixer:call("get-volume", id)
92
93 -- the return value of "get-volume" is a GVariant(a{sv}),
94 -- which gets translated to a Lua table
95 Debug.dump_table(volume)
96 end)
97
98 :param action_signal: the signal name to call
99 :param ...: a list of arguments that will be passed to the signal
100 :returns: the return value of the action signal, if any
101
102 Type conversions
103 ----------------
104
105 When working with GObject properties and signals, variables need to be
106 converted from C types to Lua types and vice versa. The following tables
107 list the type conversions that happen automatically:
108
109 C to Lua
110 ^^^^^^^^
111
112 Conversion from C to lua is based on the C type.
113
114 ================================ ===============================================
115 C Lua
116 ================================ ===============================================
117 gchar, guchar, gint, guint integer
118 glong, gulong, gint64, guint64 integer
119 gfloat, gdouble number
120 gboolean boolean
121 gchar * string
122 gpointer lightuserdata
123 WpProperties * table (keys: string, values: string)
124 enum string containing the nickname (short name) of
125 the enum, or integer if the enum is not
126 registered with GType
127 flags integer (as in C)
128 GVariant * a native type, see below
129 other GObject, GInterface userdata holding reference to the object
130 other GBoxed userdata holding reference to the object
131 ================================ ===============================================
132
133 .. _lua_gobject_lua_to_c:
134
135 Lua to C
136 ^^^^^^^^
137
138 Conversion from Lua to C is based on the expected type in C.
139
140 ============================== ==================================================
141 Expecting Lua
142 ============================== ==================================================
143 gchar, guchar, gint, guint, convertible to integer
144 glong, gulong, gint64, guint64 convertible to integer
145 gfloat, gdouble convertible to number
146 gboolean convertible to boolean
147 gchar * convertible to string
148 gpointer must be lightuserdata
149 WpProperties * must be table (keys: string, values: convertible
150 to string)
151 enum must be string holding the nickname of the enum,
152 or convertible to integer
153 flags convertible to integer
154 GVariant * see below
155 other GObject, GInterface must be userdata holding a compatible GObject type
156 other GBoxed must be userdata holding the same GBoxed type
157 ============================== ==================================================
158
159 GVariant to Lua
160 ^^^^^^^^^^^^^^^
161
162 ============================= =============================================
163 GVariant Lua
164 ============================= =============================================
165 NULL or G_VARIANT_TYPE_UNIT nil
166 G_VARIANT_TYPE_INT16 integer
167 G_VARIANT_TYPE_INT32 integer
168 G_VARIANT_TYPE_INT64 integer
169 G_VARIANT_TYPE_UINT16 integer
170 G_VARIANT_TYPE_UINT32 integer
171 G_VARIANT_TYPE_UINT64 integer
172 G_VARIANT_TYPE_DOUBLE number
173 G_VARIANT_TYPE_BOOLEAN boolean
174 G_VARIANT_TYPE_STRING string
175 G_VARIANT_TYPE_VARIANT converted recursively
176 G_VARIANT_TYPE_DICTIONARY table (keys & values converted recursively)
177 G_VARIANT_TYPE_ARRAY table (children converted recursively)
178 ============================= =============================================
179
180 Lua to GVariant
181 ^^^^^^^^^^^^^^^
182
183 Conversion from Lua to GVariant is based on the lua type and is quite limited.
184
185 There is no way to recover an array, for instance, because there is no way
186 in Lua to tell if a table contains an array or a dictionary. All Lua tables
187 are converted to dictionaries and integer keys are converted to strings.
188
189 ========= ================================
190 Lua GVariant
191 ========= ================================
192 nil G_VARIANT_TYPE_UNIT
193 boolean G_VARIANT_TYPE_BOOLEAN
194 integer G_VARIANT_TYPE_INT64
195 number G_VARIANT_TYPE_DOUBLE
196 string G_VARIANT_TYPE_STRING
197 table G_VARIANT_TYPE_VARDICT (a{sv})
198 ========= ================================
199
200 Closures
201 --------
202
203 When a C function is expecting a GClosure, in Lua it is possible to pass
204 a Lua function directly. The function is then wrapped into a custom GClosure.
205
206 When this GClosure is invalidated, the reference to the Lua function is dropped.
207 Similarly, when the lua engine is stopped, all the GClosures that were
208 created by this engine are invalidated.
209
210 Reference counting
211 ------------------
212
213 GObject references in Lua always hold a reference to the underlying GObject.
214 When moving this reference around to other variables in Lua, the underlying
215 GObject reference is shared, but Lua reference counts the wrapper "userdata"
216 object.
217
218 .. code-block:: lua
219
220 -- creating a new FooObject instance; obj holds the GObject reference
221 local obj = FooObject()
222
223 -- GObject reference is dropped and FooObject is finalized
224 obj = nil
225
226 .. code-block:: lua
227
228 -- creating a new FooObject instance; obj holds the GObject reference
229 local obj = FooObject()
230
231 function store_global(o)
232 -- o is now stored in the global 'obj_global' variable
233 -- the GObject ref count is still 1
234 obj_global = o
235 end
236
237 -- obj userdata reference is passed to o, the GObject ref count is still 1
238 store_global(obj)
239
240 -- userdata reference dropped from obj, the GObject is still alive
241 obj = nil
242
243 -- userdata reference dropped from obj_global,
244 -- the GObject ref is dropped and FooObject is finalized
245 obj_global = nil
246
247 .. note::
248
249 When assigning a variable to nil, Lua may not immediately drop
250 the reference of the underlying object. This is because Lua uses a garbage
251 collector and goes through all the unreferenced objects to cleanup when
252 the garbage collector runs.
253
254 When a GObject that is already referenced in Lua re-appears somewhere else
255 through calling some API or because of a callback from C, a new reference is
256 added on the GObject.
257
258 .. code-block:: lua
259
260 -- ObjectManager is created in Lua, om holds 1 ref
261 local om = ObjectManager(...)
262 om:connect("objects-changed", function (om)
263 -- om in this scope is a local function argument that was created
264 -- by the signal's closure marshaller and holds a second reference
265 -- to the ObjectManager
266
267 do_some_stuff()
268
269 -- this second reference is dropped when the function goes out of scope
270 end)
271
272 .. danger::
273
274 Because Lua variables hold strong references to GObjects, it is dangerous
275 to create closures that reference such variables, because these closures
276 may create reference loops and **leak** objects
277
278 .. code-block:: lua
279
280 local om = ObjectManager(...)
281
282 om:connect("objects-changed", function (obj_mgr)
283 -- using 'om' here instead of the local 'obj_mgr'
284 -- creates a dangerous reference from the closure to 'om'
285 for obj in om:iterate() do
286 do_stuff(obj)
287 end
288 end)
289
290 -- local userdata reference dropped, but the GClosure that was generated
291 -- from the above function is still holding a reference and keeps
292 -- the ObjectManager alive; the GClosure is referenced by the ObjectManager
293 -- because of the signal connection, so the ObjectManager is leaked
294 om = nil
295
296 .. _GObject: https://developer.gnome.org/gobject/stable/
297 .. _properties: https://developer.gnome.org/gobject/stable/gobject-properties.html
298 .. _g_object_get: https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-get
299 .. _g_object_set: https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#g-object-set
300 .. _signals: https://developer.gnome.org/gobject/stable/signal.html