2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gstdata.c: Data operations
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.
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.
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.
23 /* this file makes too much noise for most debugging sessions */
25 #define GST_DEBUG_FORCE_DISABLE
26 #include "gst_private.h"
28 #include "gstatomic_impl.h"
30 #include "gstdata_private.h"
35 * @data: a #GstData to initialize
36 * @type: the type of this data
37 * @flags: flags for this data
38 * @free: a free function
39 * @copy: a copy function
41 * Initialize the given data structure with the given parameters. The free and copy
42 * function will be called when this data is freed or copied respectively.
45 gst_data_init (GstData *data, GType type, guint16 flags, GstDataFreeFunction free, GstDataCopyFunction copy)
47 g_return_if_fail (data != NULL);
49 _GST_DATA_INIT (data, type, flags, free, copy);
54 * @data: a #GstData to copy
55 * @target: the target #GstData to copy into
57 * Copy the GstData into the specified target GstData structure.
58 * Thos method is mainly used by subclasses when they want to copy
59 * the relevant GstData info.
62 gst_data_copy_into (const GstData *data, GstData *target)
64 g_return_if_fail (data != NULL);
69 * @data: a #GstData to dispose
71 * Free all the resources allocated in the gst_data_init() function,
72 * mainly used by subclass implementors.
75 gst_data_dispose (GstData *data)
77 g_return_if_fail (data != NULL);
79 _GST_DATA_DISPOSE (data);
84 * @data: a #GstData to copy
86 * Copies the given #GstData. This function will call the custom subclass
87 * copy function or return NULL if no function was provided by the subclass.
89 * Returns: a copy of the data or NULL if the data cannot be copied. The refcount
90 * of the original buffer is not changed so you should unref it when you don't
94 gst_data_copy (const GstData *data)
96 g_return_val_if_fail (data != NULL, NULL);
99 return data->copy (data);
105 * gst_data_is_writable:
106 * @data: a #GstData to copy
108 * Query if the gstdata needs to be copied before it can safely be modified.
110 * Returns: FALSE if the given #GstData is potentially shared and needs to
111 * be copied before it can be modified safely.
114 gst_data_is_writable (GstData *data)
118 g_return_val_if_fail (data != NULL, FALSE);
120 refcount = gst_atomic_int_read (&data->refcount);
122 if (refcount == 1 && !GST_DATA_FLAG_IS_SET (data, GST_DATA_READONLY))
129 * gst_data_copy_on_write:
130 * @data: a #GstData to copy
132 * Copies the given #GstData if the refcount is greater than 1 so that the
133 * #GstData object can be written to safely.
135 * Returns: a copy of the data if the refcount is > 1 or the buffer is
136 * marked READONLY, data if the refcount == 1,
137 * or NULL if the data could not be copied. The refcount of the original buffer
138 * is decreased when a copy is made, so you are not supposed to use it after a
139 * call to this function.
142 gst_data_copy_on_write (GstData *data)
146 g_return_val_if_fail (data != NULL, NULL);
148 refcount = gst_atomic_int_read (&data->refcount);
150 if (refcount == 1 && !GST_DATA_FLAG_IS_SET (data, GST_DATA_READONLY))
151 return GST_DATA (data);
154 GstData *copy = data->copy (data);
155 gst_data_unref (data);
164 * @data: a #GstData to free
166 * Frees the given #GstData. This function will call the custom free function
167 * provided by the subclass.
170 gst_data_free (GstData *data)
181 * @data: a #GstData to reference
183 * Increments the reference count of this data.
188 gst_data_ref (GstData *data)
190 g_return_val_if_fail (data != NULL, NULL);
191 g_return_val_if_fail (GST_DATA_REFCOUNT_VALUE(data) > 0, NULL);
193 gst_atomic_int_inc (&data->refcount);
199 * gst_data_ref_by_count:
200 * @data: a #GstData to reference
201 * @count: the number to increment the reference count by
203 * Increments the reference count of this data by the given number.
208 gst_data_ref_by_count (GstData *data, gint count)
210 g_return_val_if_fail (data != NULL, NULL);
211 g_return_val_if_fail (count >= 0, NULL);
212 g_return_val_if_fail (GST_DATA_REFCOUNT_VALUE(data) > 0, NULL);
214 gst_atomic_int_add (&data->refcount, count);
221 * @data: a #GstData to unreference
223 * Decrements the refcount of this data. If the refcount is
224 * zero, the data will be freed.
226 * When you add data to a pipeline, the pipeline takes ownership of the
227 * data. When the data has been used by some plugin, it must unref()s it.
228 * Applications usually don't need to unref() anything.
231 gst_data_unref (GstData *data)
235 g_return_if_fail (data != NULL);
237 GST_INFO (GST_CAT_BUFFER, "unref data %p, count before unref is %d",
238 data, GST_DATA_REFCOUNT_VALUE (data));
239 g_return_if_fail (GST_DATA_REFCOUNT_VALUE (data) > 0);
241 zero = gst_atomic_int_dec_and_test (&data->refcount);
243 /* if we ended up with the refcount at zero, free the data */