| 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 |
} |