docs/gst/gstreamer-sections.txt: Added some new macros.

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
Added some new macros.

* gst/gstclock.c:
* gst/gstclock.h:
* gst/gstobject.h:
Docs updates.

ChangeLog

@@ -1,3 +1,13 @@
+2005-11-09  Wim Taymans  <wim@fluendo.com>
+
+	* docs/gst/gstreamer-sections.txt:
+	Added some new macros.
+
+	* gst/gstclock.c:
+	* gst/gstclock.h:
+	* gst/gstobject.h:
+	Docs updates.
+
 2005-11-09  Wim Taymans  <wim@fluendo.com>
 
 	* docs/design/part-TODO.txt:

docs/gst/gstreamer-sections.txt

@@ -652,6 +652,7 @@ gst_event_unref
 <SUBSECTION Standard>
 GstEventClass
 GST_EVENT
+GST_EVENT_CAST
 GST_IS_EVENT
 GST_IS_EVENT_CLASS
 GST_EVENT_CLASS
@@ -2229,6 +2230,7 @@ GST_BASE_SRC_PAD
 <SUBSECTION Standard>
 GstBaseSrcClass
 GST_BASE_SRC
+GST_BASE_SRC_CAST
 GST_IS_BASE_SRC
 GST_TYPE_BASE_SRC
 GST_BASE_SRC_CLASS
@@ -2251,6 +2253,7 @@ GST_BASE_SINK_PAD
 <SUBSECTION Standard>
 GstBaseSinkClass
 GST_BASE_SINK
+GST_BASE_SINK_CAST
 GST_IS_BASE_SINK
 GST_TYPE_BASE_SINK
 GST_BASE_SINK_CLASS

gst/gstclock.c

@@ -55,6 +55,10 @@
  * with the gst_clock_id_unschedule() call. If the blocking wait is unscheduled
  * a return value of GST_CLOCK_UNSCHEDULED is returned.
  *
+ * Periodic callbacks scheduled async will be repeadedly called automatically until
+ * it is unscheduled. To schedule an async periodic callback, gst_clock_id_wait() 
+ * should be called repeadedly.
+ *
  * The async callbacks can happen from any thread, either provided by the
  * core or from a streaming thread. The application should be prepared for this.
  *

gst/gstclock.h

@@ -169,8 +169,9 @@ G_STMT_START {						\
 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
 /**
  * GST_TIME_ARGS:
+ * @t: a #GstClockTime
  *
- * Format the GstClockTime argument for the GST_TIME_FORMAT format string.
+ * Format @t for the GST_TIME_FORMAT format string.
  */
 #define GST_TIME_ARGS(t) \
         (guint) (((GstClockTime)(t)) / (GST_SECOND * 60 * 60)), \

gst/gstobject.h

@@ -85,14 +85,21 @@ typedef enum
 /* we do a GST_OBJECT_CAST to avoid type checking, better call these
  * function with a valid object! */
 
+/**
+ * GST_GET_LOCK:
+ * @obj: Object to get the mutex of.
+ *
+ * Acquire a reference to the mutex of this object.
+ */
+#define GST_GET_LOCK(obj)               (GST_OBJECT_CAST(obj)->lock)
 /**
  * GST_LOCK:
  * @obj: Object to lock.
  *
  * This macro will obtain a lock on the object, making serialization possible.
- * It block until the lock can be obtained.
+ * It blocks until the lock can be obtained.
  */
-#define GST_LOCK(obj)                   g_mutex_lock(GST_OBJECT_CAST(obj)->lock)
+#define GST_LOCK(obj)                   g_mutex_lock(GST_GET_LOCK(obj))
 /**
  * GST_TRYLOCK:
  * @obj: Object to try to get a lock on.
@@ -100,21 +107,14 @@ typedef enum
  * This macro will try to obtain a lock on the object, but will return with
  * FALSE if it can't get it immediately.
  */
-#define GST_TRYLOCK(obj)                g_mutex_trylock(GST_OBJECT_CAST(obj)->lock)
+#define GST_TRYLOCK(obj)                g_mutex_trylock(GST_GET_LOCK(obj))
 /**
- * GST_LOCK:
+ * GST_UNLOCK:
  * @obj: Object to unlock.
  *
  * This macro releases a lock on the object.
  */
-#define GST_UNLOCK(obj)                 g_mutex_unlock(GST_OBJECT_CAST(obj)->lock)
+#define GST_UNLOCK(obj)                 g_mutex_unlock(GST_GET_LOCK(obj))
-/**
- * GST_LOCK:
- * @obj: Object to get the mutex of.
- *
- * Acquire a reference to the mutex of this object.
- */
-#define GST_GET_LOCK(obj)               (GST_OBJECT_CAST(obj)->lock)
 
 
 /**
@@ -212,10 +212,35 @@ struct _GstObject {
   gpointer _gst_reserved[GST_PADDING];
 };
 
-#define GST_CLASS_LOCK(obj)             (g_static_rec_mutex_lock(GST_OBJECT_CLASS_CAST(obj)->lock))
+/**
-#define GST_CLASS_TRYLOCK(obj)          (g_static_rec_mutex_trylock(GST_OBJECT_CLASS_CAST(obj)->lock))
+ * GST_CLASS_GET_LOCK:
-#define GST_CLASS_UNLOCK(obj)           (g_static_rec_mutex_unlock(GST_OBJECT_CLASS_CAST(obj)->lock))
+ * @obj: a #GstObjectClass
+ *
+ * This macro will return the class lock used to protect deep_notify signal
+ * emission on thread-unsafe glib versions (glib < 2.8).
+ */
 #define GST_CLASS_GET_LOCK(obj)         (GST_OBJECT_CLASS_CAST(obj)->lock)
+/**
+ * GST_CLASS_LOCK:
+ * @obj: a #GstObjectClass
+ *
+ * Lock the class.
+ */
+#define GST_CLASS_LOCK(obj)             (g_static_rec_mutex_lock(GST_CLASS_GET_LOCK(obj)))
+/**
+ * GST_CLASS_TRYLOCK:
+ * @obj: a #GstObjectClass
+ *
+ * Try to lock the class, returns TRUE if class could be locked.
+ */
+#define GST_CLASS_TRYLOCK(obj)          (g_static_rec_mutex_trylock(GST_CLASS_GET_LOCK(obj)))
+/**
+ * GST_CLASS_UNLOCK:
+ * @obj: a #GstObjectClass
+ *
+ * Unlock the class.
+ */
+#define GST_CLASS_UNLOCK(obj)           (g_static_rec_mutex_unlock(GST_CLASS_GET_LOCK(obj)))
 
 /* signal_object is used to signal to the whole class */
 struct _GstObjectClass {