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 /**
  66  * GST_OBJECT_REFCOUNT:
  67  * @obj: a #GstObject
  68  *
  69  * Get access to the reference count field of the object.
  70  */
  71 #define GST_OBJECT_REFCOUNT(obj)                (((GObject*)(obj))->ref_count)
  72 /**
  73  * GST_OBJECT_REFCOUNT_VALUE:
  74  * @obj: a #GstObject
  75  *
  76  * Get the reference count value of the object.
  77  */
  78 #define GST_OBJECT_REFCOUNT_VALUE(obj)          g_atomic_int_get ((gint *) &GST_OBJECT_REFCOUNT(obj))
  79
  80 /* we do a GST_OBJECT_CAST to avoid type checking, better call these
  81  * function with a valid object! */
  82
  83 /**
  84  * GST_OBJECT_GET_LOCK:
  85  * @obj: a #GstObject
  86  *
  87  * Acquire a reference to the mutex of this object.
  88  */
  89 #define GST_OBJECT_GET_LOCK(obj)               (GST_OBJECT_CAST(obj)->lock)
  90 /**
  91  * GST_OBJECT_LOCK:
  92  * @obj: a #GstObject to lock
  93  *
  94  * This macro will obtain a lock on the object, making serialization possible.
  95  * It blocks until the lock can be obtained.
  96  */
  97 #define GST_OBJECT_LOCK(obj)                   g_mutex_lock(GST_OBJECT_GET_LOCK(obj))
  98 /**
  99  * GST_OBJECT_TRYLOCK:
 100  * @obj: a #Object.
 101  *
 102  * This macro will try to obtain a lock on the object, but will return with
 103  * FALSE if it can't get it immediately.
 104  */
 105 #define GST_OBJECT_TRYLOCK(obj)                g_mutex_trylock(GST_OBJECT_GET_LOCK(obj))
 106 /**
 107  * GST_OBJECT_UNLOCK:
 108  * @obj: a #GstObject to unlock.
 109  *
 110  * This macro releases a lock on the object.
 111  */
 112 #define GST_OBJECT_UNLOCK(obj)                 g_mutex_unlock(GST_OBJECT_GET_LOCK(obj))
 113
 114
 115 /**
 116  * GST_OBJECT_NAME:
 117  * @obj: a #GstObject
 118  *
 119  * Get the name of this object
 120  */
 121 #define GST_OBJECT_NAME(obj)            (GST_OBJECT_CAST(obj)->name)
 122 /**
 123  * GST_OBJECT_PARENT:
 124  * @obj: a #GstObject
 125  *
 126  * Get the parent of this object
 127  */
 128 #define GST_OBJECT_PARENT(obj)          (GST_OBJECT_CAST(obj)->parent)
 129
 130
 131 /**
 132  * GST_OBJECT_FLAGS:
 133  * @obj: a #GstObject
 134  *
 135  * This macro returns the entire set of flags for the object.
 136  */
 137 #define GST_OBJECT_FLAGS(obj)                  (GST_OBJECT_CAST (obj)->flags)
 138 /**
 139  * GST_OBJECT_FLAG_IS_SET:
 140  * @obj: a #GstObject
 141  * @flag: Flag to check for
 142  *
 143  * This macro checks to see if the given flag is set.
 144  */
 145 #define GST_OBJECT_FLAG_IS_SET(obj,flag)       ((GST_OBJECT_FLAGS (obj) & (flag)) == (flag))
 146 /**
 147  * GST_OBJECT_FLAG_SET:
 148  * @obj: a #GstObject
 149  * @flag: Flag to set
 150  *
 151  * This macro sets the given bits.
 152  */
 153 #define GST_OBJECT_FLAG_SET(obj,flag)          (GST_OBJECT_FLAGS (obj) |= (flag))
 154 /**
 155  * GST_OBJECT_FLAG_UNSET:
 156  * @obj: a #GstObject
 157  * @flag: Flag to set
 158  *
 159  * This macro usets the given bits.
 160  */
 161 #define GST_OBJECT_FLAG_UNSET(obj,flag)        (GST_OBJECT_FLAGS (obj) &= ~(flag))
 162
 163
 164 /**
 165  * GST_OBJECT_IS_DISPOSING:
 166  * @obj: a #GstObject
 167  *
 168  * Check if the given object is beeing destroyed.
 169  */
 170 #define GST_OBJECT_IS_DISPOSING(obj)    (GST_OBJECT_FLAG_IS_SET (obj, GST_OBJECT_DISPOSING))
 171 /**
 172  * GST_OBJECT_IS_FLOATING:
 173  * @obj: a #GstObject
 174  *
 175  * Check if the given object is floating (has no owner).
 176  */
 177 #define GST_OBJECT_IS_FLOATING(obj)     (GST_OBJECT_FLAG_IS_SET (obj, GST_OBJECT_FLOATING))
 178
 179 typedef struct _GstObject GstObject;
 180 typedef struct _GstObjectClass GstObjectClass;
 181
 182 /**
 183  * GstObject:
 184  * @refcount: unused
 185  * @lock: object LOCK
 186  * @name: The name of the object
 187  * @name_prefix: used for debugging
 188  * @parent: this object's parent, weak ref
 189  * @flags: use GST_OBJECT_IS_XXX macros to access the flags
 190  *
 191  * GStreamer base object class.
 192  */
 193 struct _GstObject {
 194   GObject        object;
 195
 196   /*< public >*/
 197   gint           refcount;
 198
 199   /*< public >*/ /* with LOCK */
 200   GMutex        *lock;        /* object LOCK */
 201   gchar         *name;        /* object name */
 202   gchar         *name_prefix; /* used for debugging */
 203   GstObject     *parent;      /* this object's parent, weak ref */
 204   guint32        flags;
 205
 206   /*< private >*/
 207   gpointer _gst_reserved;
 208 };
 209
 210 /**
 211  * GST_CLASS_GET_LOCK:
 212  * @obj: a #GstObjectClass
 213  *
 214  * This macro will return the class lock used to protect deep_notify signal
 215  * emission on thread-unsafe glib versions (glib < 2.8).
 216  */
 217 #define GST_CLASS_GET_LOCK(obj)         (GST_OBJECT_CLASS_CAST(obj)->lock)
 218 /**
 219  * GST_CLASS_LOCK:
 220  * @obj: a #GstObjectClass
 221  *
 222  * Lock the class.
 223  */
 224 #define GST_CLASS_LOCK(obj)             (g_static_rec_mutex_lock(GST_CLASS_GET_LOCK(obj)))
 225 /**
 226  * GST_CLASS_TRYLOCK:
 227  * @obj: a #GstObjectClass
 228  *
 229  * Try to lock the class, returns TRUE if class could be locked.
 230  */
 231 #define GST_CLASS_TRYLOCK(obj)          (g_static_rec_mutex_trylock(GST_CLASS_GET_LOCK(obj)))
 232 /**
 233  * GST_CLASS_UNLOCK:
 234  * @obj: a #GstObjectClass
 235  *
 236  * Unlock the class.
 237  */
 238 #define GST_CLASS_UNLOCK(obj)           (g_static_rec_mutex_unlock(GST_CLASS_GET_LOCK(obj)))
 239
 240 /*
 241  * GstObjectClass:
 242  *
 243  * @signal_object: is used to signal to the whole class
 244  * @save_thyself: xml serialisation
 245  * @restore_thyself: xml de-serialisation
 246  */
 247 struct _GstObjectClass {
 248   GObjectClass  parent_class;
 249
 250   gchar         *path_string_separator;
 251   GObject       *signal_object;
 252
 253   GStaticRecMutex *lock;
 254
 255   /* signals */
 256   void          (*parent_set)           (GstObject *object, GstObject *parent);
 257   void          (*parent_unset)         (GstObject *object, GstObject *parent);
 258   void          (*object_saved)         (GstObject *object, xmlNodePtr parent);
 259   void          (*deep_notify)          (GstObject *object, GstObject *orig, GParamSpec *pspec);
 260
 261   /*< public >*/
 262   /* virtual methods for subclasses */
 263   xmlNodePtr    (*save_thyself)         (GstObject *object, xmlNodePtr parent);
 264   void          (*restore_thyself)      (GstObject *object, xmlNodePtr self);
 265
 266   /*< private >*/
 267   gpointer _gst_reserved[GST_PADDING];
 268 };
 269
 270 /* normal GObject stuff */
 271 GType           gst_object_get_type             (void);
 272
 273 /* name routines */
 274 gboolean        gst_object_set_name             (GstObject *object, const gchar *name);
 275 gchar*          gst_object_get_name             (GstObject *object);
 276 void            gst_object_set_name_prefix      (GstObject *object, const gchar *name_prefix);
 277 gchar*          gst_object_get_name_prefix      (GstObject *object);
 278
 279 /* parentage routines */
 280 gboolean        gst_object_set_parent           (GstObject *object, GstObject *parent);
 281 GstObject*      gst_object_get_parent           (GstObject *object);
 282 void            gst_object_unparent             (GstObject *object);
 283 gboolean        gst_object_has_ancestor         (GstObject *object, GstObject *ancestor);
 284
 285 void            gst_object_default_deep_notify  (GObject *object, GstObject *orig,
 286                                                  GParamSpec *pspec, gchar **excluded_props);
 287
 288 /* refcounting + life cycle */
 289 gpointer        gst_object_ref                  (gpointer object);
 290 void            gst_object_unref                (gpointer object);
 291 void            gst_object_sink                 (gpointer object);
 292
 293 /* replace object pointer */
 294 void            gst_object_replace              (GstObject **oldobj, GstObject *newobj);
 295
 296 /* printing out the 'path' of the object */
 297 gchar *         gst_object_get_path_string      (GstObject *object);
 298
 299 /* misc utils */
 300 gboolean        gst_object_check_uniqueness     (GList *list, const gchar *name);
 301
 302 /* load/save */
 303 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
 304 xmlNodePtr      gst_object_save_thyself         (GstObject *object, xmlNodePtr parent);
 305 void            gst_object_restore_thyself      (GstObject *object, xmlNodePtr self);
 306 #else
 307 #if defined _GNUC_ && _GNUC_ >= 3
 308 #pragma GCC poison gst_object_save_thyself
 309 #pragma GCC poison gst_object_restore_thyself
 310 #endif
 311 #endif
 312
 313 /* class signal stuff */
 314 guint           gst_class_signal_connect        (GstObjectClass *klass,
 315                                                  const gchar    *name,
 316                                                  gpointer        func,
 317                                                  gpointer        func_data);
 318
 319 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
 320 void            gst_class_signal_emit_by_name   (GstObject      *object,
 321                                                  const gchar    *name,
 322                                                  xmlNodePtr      self);
 323 #else
 324 #if defined _GNUC_ && _GNUC_ >= 3
 325 #pragma GCC poison gst_class_signal_emit_by_name
 326 #endif
 327 #endif
 328
 329
 330 G_END_DECLS
 331
 332 #endif /* __GST_OBJECT_H__ */
 333