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