Debian Codegraph @

libs/gst/check/gstharnesslink.c

raw
1 /* GstHarnessLink - A ref counted class arbitrating access to a
2 * pad harness in a thread-safe manner.
3 *
4 * Copyright (C) 2023 Igalia S.L.
5 * Copyright (C) 2023 Metrological
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
21 */
22
23 #ifdef HAVE_CONFIG_H
24 #include "config.h"
25 #endif
26
27 #include "gstharnesslink.h"
28
29 /* The HARNESS_LINK association inside a GstPad will store a pointer to
30 * GstHarnessLink, which can be used to read and atomically lock the harness
31 * while in use. */
32 #define HARNESS_LINK "harness-link"
33
34 struct _GstHarnessLink
35 {
36 /* rw_lock will be locked for writing for tearing down the harness,
37 * and locked for reading for any other use. The goal is to allow simultaneous
38 * access to the harness from multiple threads while guaranteeing that the
39 * resources of harness won't be freed during use. */
40 GRWLock rw_lock;
41 GstHarness *harness;
42 };
43
44 static void
45 gst_harness_link_init (GstHarnessLink * link)
46 {
47 g_rw_lock_init (&link->rw_lock);
48 }
49
50 static void
51 gst_harness_link_dispose (GstHarnessLink * link)
52 {
53 gboolean lock_acquired = g_rw_lock_writer_trylock (&link->rw_lock);
54 if (lock_acquired)
55 g_rw_lock_writer_unlock (&link->rw_lock);
56 else
57 g_critical
58 ("GstHarnessLink was about to be disposed while having the lock in use.");
59
60 g_rw_lock_clear (&link->rw_lock);
61 }
62
63 static GstHarnessLink *
64 gst_harness_link_new (void)
65 {
66 GstHarnessLink *link = g_atomic_rc_box_new0 (GstHarnessLink);
67 gst_harness_link_init (link);
68 return link;
69 }
70
71 static GstHarnessLink *
72 gst_harness_link_ref (GstHarnessLink * link)
73 {
74 return g_atomic_rc_box_acquire (link);
75 }
76
77 static void
78 gst_harness_link_unref (GstHarnessLink * link)
79 {
80 g_atomic_rc_box_release_full (link,
81 (GDestroyNotify) gst_harness_link_dispose);
82 }
83
84 /**
85 * gst_harness_pad_link_set: (skip)
86 * @pad: (transfer none): The pad that will be associated with a #GstHarness.
87 * @harness: (transfer none): The #GstHarness that will be associated with the
88 * pad.
89 *
90 * Creates a new #GstHarnessLink pointing to the provided @harness and
91 * associates it to the provided @pad.
92 *
93 * Once this association is set, the #GstHarness can be obtained using
94 * @gst_harness_pad_link_lock, which will also lock it until
95 * @gst_harness_link_unlock is called to prevent the #GstHarness from being
96 * destroyed while in use.
97 */
98 void
99 gst_harness_pad_link_set (GstPad * pad, GstHarness * harness)
100 {
101 GstHarnessLink *link = gst_harness_link_new ();
102 link->harness = harness;
103 // The pad will own a reference to GstHarnessLink.
104 g_object_set_data_full (G_OBJECT (pad), HARNESS_LINK,
105 link, (GDestroyNotify) gst_harness_link_unref);
106 }
107
108 static gpointer
109 _gst_harness_link_dup_func (gpointer harness_link, gpointer user_data)
110 {
111 if (harness_link)
112 gst_harness_link_ref (harness_link);
113 return harness_link;
114 }
115
116 /**
117 * gst_harness_pad_link_lock: (skip)
118 * @pad: (transfer none): A #GstPad that has been at one point associated to a
119 * #GstHarness.
120 * @dst_harness: (transfer none): An address where the pointer to #GstHarness
121 * will be placed.
122 *
123 * Find a #GstHarness associated with this @pad and place a pointer to it on
124 * @dst_harness, locking it to prevent it being destroyed while in use.
125 *
126 * Both @dst_harness and the return value will be set to %NULL if the @pad is no
127 * longer linked to a GstHarness. Generally user code will need to handle this
128 * gracefully.
129 *
130 * Call @gst_harness_link_unlock once you're done using #GstHarness.
131 *
132 * Locking the link in this manner is reentrant: it is valid to lock the pad
133 * link more than once from the same thread as long as @gst_harness_link_unlock
134 * is called after exactly that many times.
135 *
136 * Returns: (transfer full) (nullable): a #GstHarnessLink object that you must
137 * pass to @gst_harness_link_unlock after being done with the #GstHarness, or
138 * %NULL if the link has been torn down at this point.
139 */
140 GstHarnessLink *
141 gst_harness_pad_link_lock (GstPad * pad, GstHarness ** dst_harness)
142 {
143 // g_object_dup_data() will call _gst_harness_link_dup_func() while holding
144 // the mutex of the GObject association table. This guarantees that the
145 // GstHarnessLink is not destroyed between the time we get the pointer to it
146 // and increase its refcount.
147 GstHarnessLink *link = g_object_dup_data (G_OBJECT (pad), HARNESS_LINK,
148 _gst_harness_link_dup_func, NULL);
149 if (!link) {
150 // There is no longer a link between this pad and a GstHarness, as there is
151 // no associated GstHarnessLink.
152 *dst_harness = NULL;
153 return NULL;
154 }
155 g_rw_lock_reader_lock (&link->rw_lock);
156 if ((*dst_harness = link->harness)) {
157 // This GstHarnessLink has a valid link to GstHarness and will remain valid
158 // for at least as long as the user holds the lock.
159 return link;
160 } else {
161 // This GstHarnessLink has been torn down, it no longer points to a
162 // GstHarness. This will happen if we lock the link just after another
163 // thread torn it down. The GstHarnessLink will stay alive for a little
164 // longer until its refcount runs out.
165 g_rw_lock_reader_unlock (&link->rw_lock);
166 gst_harness_link_unref (link);
167 return NULL;
168 }
169 }
170
171 /**
172 * gst_harness_link_unlock: (skip)
173 * @link: (nullable) (transfer full): A #GstHarnessLink.
174 *
175 * Release the lock of the harness link for this particular thread.
176 *
177 * Whenever @gst_harness_pad_link_lock returns non-NULL this function must be
178 * called after the caller has finished use of the #GstHarness.
179 *
180 * The harness data must not be accessed after this function is called, as it is
181 * no longer guaranteed not to be destroyed.
182 *
183 * For convenience, the function will accept %NULL, in which case it will do
184 * nothing.
185 */
186 void
187 gst_harness_link_unlock (GstHarnessLink * link)
188 {
189 if (!link)
190 return;
191
192 g_rw_lock_reader_unlock (&link->rw_lock);
193 gst_harness_link_unref (link);
194 }
195
196 /**
197 * gst_harness_pad_link_tear_down: (skip)
198 * @pad: (transfer none): A #GstPad that has been at one point associated to a
199 * #GstHarness.
200 *
201 * Reset the link to the harness. Further calls to @gst_harness_pad_link_lock
202 * will return NULL.
203 *
204 * This function will block until every thread that successfully locked the
205 * harness link with @gst_harness_pad_link_lock has unlocked it with
206 * @gst_harness_link_unlock.
207 */
208 void
209 gst_harness_pad_link_tear_down (GstPad * pad)
210 {
211 // Steal the reference from the pad. This is still synchronized with
212 // g_object_dup_data().
213 GstHarnessLink *link = g_object_steal_data (G_OBJECT (pad), HARNESS_LINK);
214 g_return_if_fail (link != NULL);
215
216 // Take the lock for writing, which will wait for all threads that have locked
217 // the harness and will block future lock attempts until we unlock.
218 g_rw_lock_writer_lock (&link->rw_lock);
219 link->harness = NULL;
220 g_rw_lock_writer_unlock (&link->rw_lock);
221
222 // Unref the reference. In the likely case that no other thread has just done
223 // g_object_dup_data() and has therefore increase the refcount, this will be
224 // the last reference and terminate the GstHarnessLink.
225 gst_harness_link_unref (link);
226
227 // Even in the case where there is a remaining reference to GstHarnessLink in
228 // a different thread, the GstHarness pointer has been cleared at this point,
229 // so the caller thread can safely tear down the GstHarness.
230 }