1/* GStreamer
2 * Copyright (C) 2005 David Schleef <[email protected]>
3 *
4 * gstminiobject.h: Header for GstMiniObject
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22
23#ifndef __GST_MINI_OBJECT_H__
24#define __GST_MINI_OBJECT_H__
25
26#include <gst/gstconfig.h>
27
28#include <glib-object.h>
29
30G_BEGIN_DECLS
31
32#define GST_IS_MINI_OBJECT_TYPE(obj,type) ((obj) && GST_MINI_OBJECT_TYPE(obj) == (type))
33#define GST_MINI_OBJECT_CAST(obj) ((GstMiniObject*)(obj))
34#define GST_MINI_OBJECT_CONST_CAST(obj) ((const GstMiniObject*)(obj))
35#define GST_MINI_OBJECT(obj) (GST_MINI_OBJECT_CAST(obj))
36
37typedef struct _GstMiniObject GstMiniObject;
38
39/**
40 * GstMiniObjectCopyFunction:
41 * @obj: MiniObject to copy
42 *
43 * Function prototype for methods to create copies of instances.
44 *
45 * Returns: reference to cloned instance.
46 */
47typedef GstMiniObject * (*GstMiniObjectCopyFunction) (const GstMiniObject *obj);
48/**
49 * GstMiniObjectDisposeFunction:
50 * @obj: MiniObject to dispose
51 *
52 * Function prototype for when a miniobject has lost its last refcount.
53 * Implementation of the mini object are allowed to revive the
54 * passed object by doing a gst_mini_object_ref(). If the object is not
55 * revived after the dispose function, the function should return %TRUE
56 * and the memory associated with the object is freed.
57 *
58 * Returns: %TRUE if the object should be cleaned up.
59 */
60typedef gboolean (*GstMiniObjectDisposeFunction) (GstMiniObject *obj);
61/**
62 * GstMiniObjectFreeFunction:
63 * @obj: MiniObject to free
64 *
65 * Virtual function prototype for methods to free resources used by
66 * mini-objects.
67 */
68typedef void (*GstMiniObjectFreeFunction) (GstMiniObject *obj);
69
70 /**
71 * GstMiniObjectNotify:
72 * @user_data: data that was provided when the notify was added
73 * @obj: the mini object
74 *
75 * A #GstMiniObjectNotify function can be added to a mini object as a
76 * callback that gets triggered when gst_mini_object_unref() drops the
77 * last ref and @obj is about to be freed.
78 */
79typedef void (*GstMiniObjectNotify) (gpointer user_data, GstMiniObject * obj);
80
81/**
82 * GST_MINI_OBJECT_TYPE:
83 * @obj: MiniObject to return type for.
84 *
85 * This macro returns the type of the mini-object.
86 */
87#define GST_MINI_OBJECT_TYPE(obj) (GST_MINI_OBJECT_CAST(obj)->type)
88
89/**
90 * GST_MINI_OBJECT_FLAGS:
91 * @obj: MiniObject to return flags for.
92 *
93 * This macro returns the entire set of flags for the mini-object.
94 */
95#define GST_MINI_OBJECT_FLAGS(obj) (GST_MINI_OBJECT_CAST(obj)->flags)
96/**
97 * GST_MINI_OBJECT_FLAG_IS_SET:
98 * @obj: MiniObject to check for flags.
99 * @flag: Flag to check for
100 *
101 * This macro checks to see if the given flag is set.
102 */
103#define GST_MINI_OBJECT_FLAG_IS_SET(obj,flag) !!(GST_MINI_OBJECT_FLAGS (obj) & (flag))
104/**
105 * GST_MINI_OBJECT_FLAG_SET:
106 * @obj: MiniObject to set flag in.
107 * @flag: Flag to set, can by any number of bits in guint32.
108 *
109 * This macro sets the given bits.
110 */
111#define GST_MINI_OBJECT_FLAG_SET(obj,flag) (GST_MINI_OBJECT_FLAGS (obj) |= (flag))
112/**
113 * GST_MINI_OBJECT_FLAG_UNSET:
114 * @obj: MiniObject to unset flag in.
115 * @flag: Flag to set, must be a single bit in guint32.
116 *
117 * This macro unsets the given bits.
118 */
119#define GST_MINI_OBJECT_FLAG_UNSET(obj,flag) (GST_MINI_OBJECT_FLAGS (obj) &= ~(flag))
120
121/**
122 * GstMiniObjectFlags:
123 * @GST_MINI_OBJECT_FLAG_LOCKABLE: the object can be locked and unlocked with
124 * gst_mini_object_lock() and gst_mini_object_unlock().
125 * @GST_MINI_OBJECT_FLAG_LOCK_READONLY: the object is permanently locked in
126 * READONLY mode. Only read locks can be performed on the object.
127 * @GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED: the object is expected to stay alive
128 * even after gst_deinit() has been called and so should be ignored by leak
129 * detection tools. (Since 1.10)
130 * @GST_MINI_OBJECT_FLAG_LAST: first flag that can be used by subclasses.
131 *
132 * Flags for the mini object
133 */
134typedef enum
135{
136 GST_MINI_OBJECT_FLAG_LOCKABLE = (1 << 0),
137 GST_MINI_OBJECT_FLAG_LOCK_READONLY = (1 << 1),
138 GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED = (1 << 2),
139 /* padding */
140 GST_MINI_OBJECT_FLAG_LAST = (1 << 4)
141} GstMiniObjectFlags;
142
143/**
144 * GST_MINI_OBJECT_IS_LOCKABLE:
145 * @obj: a #GstMiniObject
146 *
147 * Check if @obj is lockable. A lockable object can be locked and unlocked with
148 * gst_mini_object_lock() and gst_mini_object_unlock().
149 */
150#define GST_MINI_OBJECT_IS_LOCKABLE(obj) GST_MINI_OBJECT_FLAG_IS_SET(obj, GST_MINI_OBJECT_FLAG_LOCKABLE)
151
152/**
153 * GstLockFlags:
154 * @GST_LOCK_FLAG_READ: lock for read access
155 * @GST_LOCK_FLAG_WRITE: lock for write access
156 * @GST_LOCK_FLAG_EXCLUSIVE: lock for exclusive access
157 * @GST_LOCK_FLAG_LAST: first flag that can be used for custom purposes
158 *
159 * Flags used when locking miniobjects
160 */
161typedef enum {
162 GST_LOCK_FLAG_READ = (1 << 0),
163 GST_LOCK_FLAG_WRITE = (1 << 1),
164 GST_LOCK_FLAG_EXCLUSIVE = (1 << 2),
165
166 GST_LOCK_FLAG_LAST = (1 << 8)
167} GstLockFlags;
168
169/**
170 * GST_LOCK_FLAG_READWRITE: (value 3) (type GstLockFlags)
171 *
172 * GstLockFlags value alias for GST_LOCK_FLAG_READ | GST_LOCK_FLAG_WRITE
173 */
174#define GST_LOCK_FLAG_READWRITE ((GstLockFlags) (GST_LOCK_FLAG_READ | GST_LOCK_FLAG_WRITE))
175
176/**
177 * GST_MINI_OBJECT_REFCOUNT:
178 * @obj: a #GstMiniObject
179 *
180 * Get access to the reference count field of the mini-object.
181 */
182#define GST_MINI_OBJECT_REFCOUNT(obj) ((GST_MINI_OBJECT_CAST(obj))->refcount)
183/**
184 * GST_MINI_OBJECT_REFCOUNT_VALUE:
185 * @obj: a #GstMiniObject
186 *
187 * Get the reference count value of the mini-object.
188 */
189#define GST_MINI_OBJECT_REFCOUNT_VALUE(obj) (g_atomic_int_get (&(GST_MINI_OBJECT_CAST(obj))->refcount))
190
191/**
192 * GstMiniObject: (ref-func gst_mini_object_ref) (unref-func gst_mini_object_unref) (set-value-func g_value_set_boxed) (get-value-func g_value_get_boxed)
193 * @type: the GType of the object
194 * @refcount: atomic refcount
195 * @lockstate: atomic state of the locks
196 * @flags: extra flags.
197 * @copy: a copy function
198 * @dispose: a dispose function
199 * @free: the free function
200 *
201 * Base class for refcounted lightweight objects.
202 */
203struct _GstMiniObject {
204 GType type;
205
206 /*< public >*/ /* with COW */
207 gint refcount;
208 gint lockstate;
209 guint flags;
210
211 GstMiniObjectCopyFunction copy;
212 GstMiniObjectDisposeFunction dispose;
213 GstMiniObjectFreeFunction free;
214
215 /* < private > */
216 /* Used to keep track of parents, weak ref notifies and qdata */
217 guint priv_uint;
218 gpointer priv_pointer;
219};
220
221GST_API
222void gst_mini_object_init (GstMiniObject *mini_object,
223 guint flags, GType type,
224 GstMiniObjectCopyFunction copy_func,
225 GstMiniObjectDisposeFunction dispose_func,
226 GstMiniObjectFreeFunction free_func);
227
228
229/* refcounting */
230
231GST_API
232GstMiniObject * gst_mini_object_ref (GstMiniObject *mini_object);
233
234GST_API
235void gst_mini_object_unref (GstMiniObject *mini_object);
236
237GST_API
238void gst_clear_mini_object (GstMiniObject **object_ptr);
239#define gst_clear_mini_object(object_ptr) g_clear_pointer ((object_ptr), gst_mini_object_unref)
240
241GST_API
242void gst_mini_object_weak_ref (GstMiniObject *object,
243 GstMiniObjectNotify notify,
244 gpointer data);
245GST_API
246void gst_mini_object_weak_unref (GstMiniObject *object,
247 GstMiniObjectNotify notify,
248 gpointer data);
249
250/* locking */
251
252GST_API
253gboolean gst_mini_object_lock (GstMiniObject *object, GstLockFlags flags);
254
255GST_API
256void gst_mini_object_unlock (GstMiniObject *object, GstLockFlags flags);
257
258GST_API
259gboolean gst_mini_object_is_writable (const GstMiniObject *mini_object);
260
261GST_API
262GstMiniObject * gst_mini_object_make_writable (GstMiniObject *mini_object) G_GNUC_WARN_UNUSED_RESULT;
263
264/* copy */
265
266GST_API
267GstMiniObject * gst_mini_object_copy (const GstMiniObject *mini_object) G_GNUC_MALLOC G_GNUC_WARN_UNUSED_RESULT;
268
269
270GST_API
271void gst_mini_object_set_qdata (GstMiniObject *object, GQuark quark,
272 gpointer data, GDestroyNotify destroy);
273GST_API
274gpointer gst_mini_object_get_qdata (GstMiniObject *object, GQuark quark);
275
276GST_API
277gpointer gst_mini_object_steal_qdata (GstMiniObject *object, GQuark quark);
278
279GST_API
280void gst_mini_object_add_parent (GstMiniObject *object, GstMiniObject *parent);
281GST_API
282void gst_mini_object_remove_parent (GstMiniObject *object, GstMiniObject *parent);
283
284GST_API
285gboolean gst_mini_object_replace (GstMiniObject **olddata, GstMiniObject *newdata);
286
287GST_API
288gboolean gst_mini_object_take (GstMiniObject **olddata, GstMiniObject *newdata);
289
290GST_API
291GstMiniObject * gst_mini_object_steal (GstMiniObject **olddata) G_GNUC_WARN_UNUSED_RESULT;
292
293/**
294 * GST_DEFINE_MINI_OBJECT_TYPE:
295 * @TypeName: name of the new type in CamelCase
296 * @type_name: name of the new type
297 *
298 * Define a new mini-object type with the given name
299 */
300#define GST_DEFINE_MINI_OBJECT_TYPE(TypeName,type_name) \
301 G_DEFINE_BOXED_TYPE(TypeName,type_name, \
302 (GBoxedCopyFunc) gst_mini_object_ref, \
303 (GBoxedFreeFunc) gst_mini_object_unref)
304
305G_END_DECLS
306
307#endif
308
309