introspection: Assorted minor introspection and documentation fixes
[platform/upstream/gstreamer.git] / gst / gstclock.h
index e0b3afc..2fbe90c 100644 (file)
@@ -17,8 +17,8 @@
  *
  * You should have received a copy of the GNU Library General Public
  * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
  */
 
 #ifndef __GST_CLOCK_H__
@@ -35,9 +35,6 @@ G_BEGIN_DECLS
 #define GST_CLOCK_GET_CLASS(clock)      (G_TYPE_INSTANCE_GET_CLASS ((clock), GST_TYPE_CLOCK, GstClockClass))
 #define GST_CLOCK_CAST(clock)           ((GstClock*)(clock))
 
-#define GST_CLOCK_SLAVE_LOCK(clock)     g_mutex_lock (&GST_CLOCK_CAST (clock)->slave_lock)
-#define GST_CLOCK_SLAVE_UNLOCK(clock)   g_mutex_unlock (&GST_CLOCK_CAST (clock)->slave_lock)
-
 /**
  * GstClockTime:
  *
@@ -69,6 +66,9 @@ typedef gpointer GstClockID;
  * GST_CLOCK_TIME_NONE:
  *
  * Constant to define an undefined clock time.
+ *
+ * Value: 18446744073709551615
+ * Type: GstClockTime
  */
 #define GST_CLOCK_TIME_NONE             ((GstClockTime) -1)
 /**
@@ -86,7 +86,7 @@ typedef gpointer GstClockID;
  * Constant that defines one GStreamer second.
  *
  * Value: 1000000000
- *
+ * Type: GstClockTime
  */
 #define GST_SECOND  (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
 /**
@@ -95,7 +95,7 @@ typedef gpointer GstClockID;
  * Constant that defines one GStreamer millisecond.
  *
  * Value: 1000000
- *
+ * Type: GstClockTime
  */
 #define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
 /**
@@ -104,7 +104,7 @@ typedef gpointer GstClockID;
  * Constant that defines one GStreamer microsecond.
  *
  * Value: 1000
- *
+ * Type: GstClockTime
  */
 #define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
 /**
@@ -113,7 +113,7 @@ typedef gpointer GstClockID;
  * Constant that defines one GStreamer nanosecond
  *
  * Value: 1
- *
+ * Type: GstClockTime
  */
 #define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))
 
@@ -123,8 +123,6 @@ typedef gpointer GstClockID;
  * @time: the time
  *
  * Convert a #GstClockTime to seconds.
- *
- * Since: 0.10.16
  */
 #define GST_TIME_AS_SECONDS(time)  ((time) / GST_SECOND)
 /**
@@ -132,8 +130,6 @@ typedef gpointer GstClockID;
  * @time: the time
  *
  * Convert a #GstClockTime to milliseconds (1/1000 of a second).
- *
- * Since: 0.10.16
  */
 #define GST_TIME_AS_MSECONDS(time) ((time) / G_GINT64_CONSTANT (1000000))
 /**
@@ -141,8 +137,6 @@ typedef gpointer GstClockID;
  * @time: the time
  *
  * Convert a #GstClockTime to microseconds (1/1000000 of a second).
- *
- * Since: 0.10.16
  */
 #define GST_TIME_AS_USECONDS(time) ((time) / G_GINT64_CONSTANT (1000))
 /**
@@ -150,8 +144,6 @@ typedef gpointer GstClockID;
  * @time: the time
  *
  * Convert a #GstClockTime to nanoseconds (1/1000000000 of a second).
- *
- * Since: 0.10.16
  */
 #define GST_TIME_AS_NSECONDS(time) (time)
 
@@ -186,10 +178,12 @@ typedef gpointer GstClockID;
  */
 #define GST_TIME_TO_TIMEVAL(t,tv)                               \
 G_STMT_START {                                                  \
-  (tv).tv_sec  = ((GstClockTime) (t)) / GST_SECOND;             \
-  (tv).tv_usec = (((GstClockTime) (t)) -                        \
+  g_assert ("Value of time " #t " is out of timeval's range" && \
+      ((t) / GST_SECOND) < G_MAXLONG);                          \
+  (tv).tv_sec  = (glong) (((GstClockTime) (t)) / GST_SECOND);   \
+  (tv).tv_usec = (glong) ((((GstClockTime) (t)) -               \
                   ((GstClockTime) (tv).tv_sec) * GST_SECOND)    \
-                 / GST_USECOND                                \
+                 / GST_USECOND);                                \
 } G_STMT_END
 
 /**
@@ -206,10 +200,12 @@ G_STMT_START {                                                  \
  *
  * Convert a #GstClockTime to a struct timespec (see man pselect)
  */
-#define GST_TIME_TO_TIMESPEC(t,ts)                      \
-G_STMT_START {                                          \
-  (ts).tv_sec  =  (t) / GST_SECOND;                     \
-  (ts).tv_nsec = ((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND;        \
+#define GST_TIME_TO_TIMESPEC(t,ts)                                \
+G_STMT_START {                                                    \
+  g_assert ("Value of time " #t " is out of timespec's range" &&  \
+      ((t) / GST_SECOND) < G_MAXLONG);                            \
+  (ts).tv_sec  =  (glong) ((t) / GST_SECOND);                     \
+  (ts).tv_nsec = (glong) (((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND);        \
 } G_STMT_END
 
 /* timestamp debugging macros */
@@ -271,7 +267,7 @@ typedef gboolean        (*GstClockCallback)     (GstClock *clock, GstClockTime t
  * @GST_CLOCK_BADTIME: A bad time was provided to a function.
  * @GST_CLOCK_ERROR: An error occurred
  * @GST_CLOCK_UNSUPPORTED: Operation is not supported
- * @GST_CLOCK_DONE: The ClockID is done waiting (Since: 0.10.32)
+ * @GST_CLOCK_DONE: The ClockID is done waiting
  *
  * The return value of a clock operation.
  */
@@ -365,6 +361,7 @@ struct _GstClockEntry {
   gboolean               unscheduled;
   gboolean               woken_up;
 
+  /*< private >*/
   gpointer _gst_reserved[GST_PADDING];
 };
 
@@ -402,38 +399,6 @@ typedef enum {
 #define GST_CLOCK_FLAGS(clock)  GST_OBJECT_FLAGS(clock)
 
 /**
- * GST_CLOCK_GET_COND:
- * @clock: the clock to query
- *
- * Gets the #GCond that gets signalled when the entries of the clock
- * changed.
- */
-#define GST_CLOCK_GET_COND(clock)        (&GST_CLOCK_CAST(clock)->entries_changed)
-/**
- * GST_CLOCK_WAIT:
- * @clock: the clock to wait on
- *
- * Wait on the clock until the entries changed.
- */
-#define GST_CLOCK_WAIT(clock)            g_cond_wait(GST_CLOCK_GET_COND(clock),GST_OBJECT_GET_LOCK(clock))
-/**
- * GST_CLOCK_TIMED_WAIT:
- * @clock: the clock to wait on
- * @tv: a #GTimeVal to wait.
- *
- * Wait on the clock until the entries changed or the specified timeout
- * occurred.
- */
-#define GST_CLOCK_TIMED_WAIT(clock,tv)   g_cond_timed_wait(GST_CLOCK_GET_COND(clock),GST_OBJECT_GET_LOCK(clock),tv)
-/**
- * GST_CLOCK_BROADCAST:
- * @clock: the clock to broadcast
- *
- * Signal that the entries in the clock have changed.
- */
-#define GST_CLOCK_BROADCAST(clock)       g_cond_broadcast(GST_CLOCK_GET_COND(clock))
-
-/**
  * GstClock:
  *
  * #GstClock base structure. The values of this structure are
@@ -442,32 +407,6 @@ typedef enum {
 struct _GstClock {
   GstObject      object;
 
-  GMutex         slave_lock; /* order: SLAVE_LOCK, OBJECT_LOCK */
-
-  /*< protected >*/ /* with LOCK */
-  GstClockTime   internal_calibration;
-  GstClockTime   external_calibration;
-  GstClockTime   rate_numerator;
-  GstClockTime   rate_denominator;
-  GstClockTime   last_time;
-  GList         *entries;
-  GCond          entries_changed;
-
-  /*< private >*/ /* with LOCK */
-  GstClockTime   resolution;
-
-  /* for master/slave clocks */
-  GstClock      *master;
-
-  /* with SLAVE_LOCK */
-  gboolean       filling;
-  gint           window_size;
-  gint           window_threshold;
-  gint           time_index;
-  GstClockTime   timeout;
-  GstClockTime  *times;
-  GstClockID     clockid;
-
   /*< private >*/
   GstClockPrivate *priv;
 
@@ -531,6 +470,11 @@ void                    gst_clock_get_calibration       (GstClock *clock, GstClo
 /* master/slave clocks */
 gboolean                gst_clock_set_master            (GstClock *clock, GstClock *master);
 GstClock*               gst_clock_get_master            (GstClock *clock);
+
+void                    gst_clock_set_timeout           (GstClock *clock,
+                                                         GstClockTime timeout);
+GstClockTime            gst_clock_get_timeout           (GstClock *clock);
+
 gboolean                gst_clock_add_observation       (GstClock *clock, GstClockTime slave,
                                                          GstClockTime master, gdouble *r_squared);
 
@@ -560,9 +504,6 @@ GstClockReturn          gst_clock_id_wait               (GstClockID id,
                                                          GstClockTimeDiff *jitter);
 GstClockReturn          gst_clock_id_wait_async         (GstClockID id,
                                                          GstClockCallback func,
-                                                         gpointer user_data);
-GstClockReturn          gst_clock_id_wait_async_full    (GstClockID id,
-                                                         GstClockCallback func,
                                                          gpointer user_data,
                                                          GDestroyNotify destroy_data);
 void                    gst_clock_id_unschedule         (GstClockID id);