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