gst/gstobject.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *                    2005 Wim Taymans <wim@fluendo.com>
   5  *
   6  * gstobject.h: Header for base GstObject
   7  *
   8  * This library is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Library General Public
  10  * License as published by the Free Software Foundation; either
  11  * version 2 of the License, or (at your option) any later version.
  12  *
  13  * This library is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * Library General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU Library General Public
  19  * License along with this library; if not, write to the
  20  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  21  * Boston, MA 02111-1307, USA.
  22  */
  23
  24 #ifndef __GST_OBJECT_H__
  25 #define __GST_OBJECT_H__
  26
  27 #include <gst/gstconfig.h>
  28
  29 #include <glib-object.h>
  30
  31 G_BEGIN_DECLS
  32
  33 #define GST_TYPE_OBJECT                 (gst_object_get_type ())
  34 #define GST_IS_OBJECT(obj)              (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_OBJECT))
  35 #define GST_IS_OBJECT_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_OBJECT))
  36 #define GST_OBJECT_GET_CLASS(obj)       (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_OBJECT, GstObjectClass))
  37 #define GST_OBJECT(obj)                 (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_OBJECT, GstObject))
  38 #define GST_OBJECT_CLASS(klass)         (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_OBJECT, GstObjectClass))
  39 #define GST_OBJECT_CAST(obj)            ((GstObject*)(obj))
  40 #define GST_OBJECT_CLASS_CAST(klass)    ((GstObjectClass*)(klass))
  41
  42 /* make sure we don't change the object size but still make it compile
  43  * without libxml */
  44 #ifdef GST_DISABLE_LOADSAVE_REGISTRY
  45 #define xmlNodePtr      gpointer
  46 #endif
  47
  48 /**
  49  * GstObjectFlags:
  50  * @GST_OBJECT_DISPOSING: the object is been destroyed, do use it anymore
  51  * @GST_OBJECT_FLOATING:  the object has a floating reference count (e.g. its
  52  *  not assigned to a bin)
  53  * @GST_OBJECT_FLAG_LAST: subclasses can add additional flags starting from this flag
  54  *
  55  * The standard flags that an gstobject may have.
  56  */
  57 typedef enum
  58 {
  59   GST_OBJECT_DISPOSING = (1<<0),
  60   GST_OBJECT_FLOATING = (1<<1),
  61   /* padding */
  62   GST_OBJECT_FLAG_LAST = (1<<4)
  63 } GstObjectFlags;
  64
  65 #ifdef GST_HAVE_GLIB_2_8
  66 /**
  67  * GST_OBJECT_REFCOUNT:
  68  * @obj: a #GstObject
  69  *
  70  * Get access to the reference count field of the object.
  71  */
  72 #define GST_OBJECT_REFCOUNT(obj)                (((GObject*)(obj))->ref_count)
  73 /**
  74  * GST_OBJECT_REFCOUNT_VALUE:
  75  * @obj: a #GstObject
  76  *
  77  * Get the reference count value of the object.
  78  */
  79 #define GST_OBJECT_REFCOUNT_VALUE(obj)          GST_OBJECT_REFCOUNT(obj)
  80 #else
  81 #define GST_OBJECT_REFCOUNT(obj)                ((GST_OBJECT_CAST(obj))->refcount)
  82 #define GST_OBJECT_REFCOUNT_VALUE(obj)          (g_atomic_int_get (&(GST_OBJECT_CAST(obj))->refcount))
  83 #endif /* GST_HAVE_GLIB_2_8 */
  84
  85 /* we do a GST_OBJECT_CAST to avoid type checking, better call these
  86  * function with a valid object! */
  87
  88 /**
  89  * GST_OBJECT_GET_LOCK:
  90  * @obj: a #GstObject
  91  *
  92  * Acquire a reference to the mutex of this object.
  93  */
  94 #define GST_OBJECT_GET_LOCK(obj)               (GST_OBJECT_CAST(obj)->lock)
  95 /**
  96  * GST_OBJECT_LOCK:
  97  * @obj: a #GstObject to lock
  98  *
  99  * This macro will obtain a lock on the object, making serialization possible.
 100  * It blocks until the lock can be obtained.
 101  */
 102 #define GST_OBJECT_LOCK(obj)                   g_mutex_lock(GST_OBJECT_GET_LOCK(obj))
 103 /**
 104  * GST_OBJECT_TRYLOCK:
 105  * @obj: a #Object.
 106  *
 107  * This macro will try to obtain a lock on the object, but will return with
 108  * FALSE if it can't get it immediately.
 109  */
 110 #define GST_OBJECT_TRYLOCK(obj)                g_mutex_trylock(GST_OBJECT_GET_LOCK(obj))
 111 /**
 112  * GST_OBJECT_UNLOCK:
 113  * @obj: a #GstObject to unlock.
 114  *
 115  * This macro releases a lock on the object.
 116  */
 117 #define GST_OBJECT_UNLOCK(obj)                 g_mutex_unlock(GST_OBJECT_GET_LOCK(obj))
 118
 119
 120 /**
 121  * GST_OBJECT_NAME:
 122  * @obj: a #GstObject
 123  *
 124  * Get the name of this object
 125  */
 126 #define GST_OBJECT_NAME(obj)            (GST_OBJECT_CAST(obj)->name)
 127 /**
 128  * GST_OBJECT_PARENT:
 129  * @obj: a #GstObject
 130  *
 131  * Get the parent of this object
 132  */
 133 #define GST_OBJECT_PARENT(obj)          (GST_OBJECT_CAST(obj)->parent)
 134
 135
 136 /**
 137  * GST_OBJECT_FLAGS:
 138  * @obj: a #GstObject
 139  *
 140  * This macro returns the entire set of flags for the object.
 141  */
 142 #define GST_OBJECT_FLAGS(obj)                  (GST_OBJECT_CAST (obj)->flags)
 143 /**
 144  * GST_OBJECT_FLAG_IS_SET:
 145  * @obj: a #GstObject
 146  * @flag: Flag to check for
 147  *
 148  * This macro checks to see if the given flag is set.
 149  */
 150 #define GST_OBJECT_FLAG_IS_SET(obj,flag)       ((GST_OBJECT_FLAGS (obj) & (flag)) == (flag))
 151 /**
 152  * GST_OBJECT_FLAG_SET:
 153  * @obj: a #GstObject
 154  * @flag: Flag to set
 155  *
 156  * This macro sets the given bits.
 157  */
 158 #define GST_OBJECT_FLAG_SET(obj,flag)          (GST_OBJECT_FLAGS (obj) |= (flag))
 159 /**
 160  * GST_OBJECT_FLAG_UNSET:
 161  * @obj: a #GstObject
 162  * @flag: Flag to set
 163  *
 164  * This macro usets the given bits.
 165  */
 166 #define GST_OBJECT_FLAG_UNSET(obj,flag)        (GST_OBJECT_FLAGS (obj) &= ~(flag))
 167
 168
 169 /**
 170  * GST_OBJECT_IS_DISPOSING:
 171  * @obj: a #GstObject
 172  *
 173  * Check if the given object is beeing destroyed.
 174  */
 175 #define GST_OBJECT_IS_DISPOSING(obj)    (GST_OBJECT_FLAG_IS_SET (obj, GST_OBJECT_DISPOSING))
 176 /**
 177  * GST_OBJECT_IS_FLOATING:
 178  * @obj: a #GstObject
 179  *
 180  * Check if the given object is floating (has no owner).
 181  */
 182 #define GST_OBJECT_IS_FLOATING(obj)     (GST_OBJECT_FLAG_IS_SET (obj, GST_OBJECT_FLOATING))
 183
 184 typedef struct _GstObject GstObject;
 185 typedef struct _GstObjectClass GstObjectClass;
 186
 187 /**
 188  * GstObject:
 189  * @refcount: only used ifndef GST_HAVE_GLIB_2_8
 190  * @lock: object LOCK
 191  * @name: The name of the object
 192  * @name_prefix: used for debugging
 193  * @parent: this object's parent, weak ref
 194  * @flags: use GST_OBJECT_IS_XXX macros to access the flags
 195  *
 196  * GStreamer base object class.
 197  */
 198 struct _GstObject {
 199   GObject        object;
 200
 201   /*< public >*/
 202   gint           refcount;
 203
 204   /*< public >*/ /* with LOCK */
 205   GMutex        *lock;        /* object LOCK */
 206   gchar         *name;        /* object name */
 207   gchar         *name_prefix; /* used for debugging */
 208   GstObject     *parent;      /* this object's parent, weak ref */
 209   guint32        flags;
 210
 211   /*< private >*/
 212   gpointer _gst_reserved[GST_PADDING];
 213 };
 214
 215 /**
 216  * GST_CLASS_GET_LOCK:
 217  * @obj: a #GstObjectClass
 218  *
 219  * This macro will return the class lock used to protect deep_notify signal
 220  * emission on thread-unsafe glib versions (glib < 2.8).
 221  */
 222 #define GST_CLASS_GET_LOCK(obj)         (GST_OBJECT_CLASS_CAST(obj)->lock)
 223 /**
 224  * GST_CLASS_LOCK:
 225  * @obj: a #GstObjectClass
 226  *
 227  * Lock the class.
 228  */
 229 #define GST_CLASS_LOCK(obj)             (g_static_rec_mutex_lock(GST_CLASS_GET_LOCK(obj)))
 230 /**
 231  * GST_CLASS_TRYLOCK:
 232  * @obj: a #GstObjectClass
 233  *
 234  * Try to lock the class, returns TRUE if class could be locked.
 235  */
 236 #define GST_CLASS_TRYLOCK(obj)          (g_static_rec_mutex_trylock(GST_CLASS_GET_LOCK(obj)))
 237 /**
 238  * GST_CLASS_UNLOCK:
 239  * @obj: a #GstObjectClass
 240  *
 241  * Unlock the class.
 242  */
 243 #define GST_CLASS_UNLOCK(obj)           (g_static_rec_mutex_unlock(GST_CLASS_GET_LOCK(obj)))
 244
 245 /*
 246  * GstObjectClass:
 247  *
 248  * @signal_object: is used to signal to the whole class
 249  * @save_thyself: xml serialisation
 250  * @restore_thyself: xml de-serialisation
 251  */
 252 struct _GstObjectClass {
 253   GObjectClass  parent_class;
 254
 255   gchar         *path_string_separator;
 256   GObject       *signal_object;
 257
 258   GStaticRecMutex *lock;
 259
 260   /* signals */
 261   void          (*parent_set)           (GstObject *object, GstObject *parent);
 262   void          (*parent_unset)         (GstObject *object, GstObject *parent);
 263   void          (*object_saved)         (GstObject *object, xmlNodePtr parent);
 264   void          (*deep_notify)          (GstObject *object, GstObject *orig, GParamSpec *pspec);
 265
 266   /*< public >*/
 267   /* virtual methods for subclasses */
 268   xmlNodePtr    (*save_thyself)         (GstObject *object, xmlNodePtr parent);
 269   void          (*restore_thyself)      (GstObject *object, xmlNodePtr self);
 270
 271   /*< private >*/
 272   gpointer _gst_reserved[GST_PADDING];
 273 };
 274
 275 /* normal GObject stuff */
 276 GType           gst_object_get_type             (void);
 277
 278 /* name routines */
 279 gboolean        gst_object_set_name             (GstObject *object, const gchar *name);
 280 gchar*          gst_object_get_name             (GstObject *object);
 281 void            gst_object_set_name_prefix      (GstObject *object, const gchar *name_prefix);
 282 gchar*          gst_object_get_name_prefix      (GstObject *object);
 283
 284 /* parentage routines */
 285 gboolean        gst_object_set_parent           (GstObject *object, GstObject *parent);
 286 GstObject*      gst_object_get_parent           (GstObject *object);
 287 void            gst_object_unparent             (GstObject *object);
 288 gboolean        gst_object_has_ancestor         (GstObject *object, GstObject *ancestor);
 289
 290 void            gst_object_default_deep_notify  (GObject *object, GstObject *orig,
 291                                                  GParamSpec *pspec, gchar **excluded_props);
 292
 293 /* refcounting + life cycle */
 294 gpointer        gst_object_ref                  (gpointer object);
 295 void            gst_object_unref                (gpointer object);
 296 void            gst_object_sink                 (gpointer object);
 297
 298 /* replace object pointer */
 299 void            gst_object_replace              (GstObject **oldobj, GstObject *newobj);
 300
 301 /* printing out the 'path' of the object */
 302 gchar *         gst_object_get_path_string      (GstObject *object);
 303
 304 /* misc utils */
 305 gboolean        gst_object_check_uniqueness     (GList *list, const gchar *name);
 306
 307 /* load/save */
 308 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
 309 xmlNodePtr      gst_object_save_thyself         (GstObject *object, xmlNodePtr parent);
 310 void            gst_object_restore_thyself      (GstObject *object, xmlNodePtr self);
 311 #else
 312 #if defined _GNUC_ && _GNUC_ >= 3
 313 #pragma GCC poison gst_object_save_thyself
 314 #pragma GCC poison gst_object_restore_thyself
 315 #endif
 316 #endif
 317
 318 /* class signal stuff */
 319 guint           gst_class_signal_connect        (GstObjectClass *klass,
 320                                                  const gchar    *name,
 321                                                  gpointer        func,
 322                                                  gpointer        func_data);
 323
 324 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
 325 void            gst_class_signal_emit_by_name   (GstObject      *object,
 326                                                  const gchar    *name,
 327                                                  xmlNodePtr      self);
 328 #else
 329 #if defined _GNUC_ && _GNUC_ >= 3
 330 #pragma GCC poison gst_class_signal_emit_by_name
 331 #endif
 332 #endif
 333
 334
 335 G_END_DECLS
 336
 337 #endif /* __GST_OBJECT_H__ */
 338