2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
4 * 2004 Wim Taymans <wim@fluendo.com>
6 * gstclock.c: Clock subsystem for maintaining time sync
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.
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.
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.
26 * @short_description: Abstract class for global clocks
27 * @see_also: #GstSystemClock, #GstPipeline
29 * GStreamer uses a global clock to synchronize the plugins in a pipeline.
30 * Different clock implementations are possible by implementing this abstract
31 * base class or, more conveniently, by subclassing #GstSystemClock.
33 * The #GstClock returns a monotonically increasing time with the method
34 * gst_clock_get_time(). Its accuracy and base time depend on the specific
35 * clock implementation but time is always expressed in nanoseconds. Since the
36 * baseline of the clock is undefined, the clock time returned is not
37 * meaningful in itself, what matters are the deltas between two clock times.
38 * The time returned by a clock is called the absolute time.
40 * The pipeline uses the clock to calculate the running time. Usually all
41 * renderers synchronize to the global clock using the buffer timestamps, the
42 * newsegment events and the element's base time, see #GstPipeline.
44 * A clock implementation can support periodic and single shot clock
45 * notifications both synchronous and asynchronous.
47 * One first needs to create a #GstClockID for the periodic or single shot
48 * notification using gst_clock_new_single_shot_id() or
49 * gst_clock_new_periodic_id().
51 * To perform a blocking wait for the specific time of the #GstClockID use the
52 * gst_clock_id_wait(). To receive a callback when the specific time is reached
53 * in the clock use gst_clock_id_wait_async(). Both these calls can be
54 * interrupted with the gst_clock_id_unschedule() call. If the blocking wait is
55 * unscheduled a return value of #GST_CLOCK_UNSCHEDULED is returned.
57 * Periodic callbacks scheduled async will be repeatedly called automatically
58 * until it is unscheduled. To schedule a sync periodic callback,
59 * gst_clock_id_wait() should be called repeatedly.
61 * The async callbacks can happen from any thread, either provided by the core
62 * or from a streaming thread. The application should be prepared for this.
64 * A #GstClockID that has been unscheduled cannot be used again for any wait
65 * operation, a new #GstClockID should be created and the old unscheduled one
66 * should be destroyed with gst_clock_id_unref().
68 * It is possible to perform a blocking wait on the same #GstClockID from
69 * multiple threads. However, registering the same #GstClockID for multiple
70 * async notifications is not possible, the callback will only be called for
71 * the thread registering the entry last.
73 * None of the wait operations unref the #GstClockID, the owner is responsible
74 * for unreffing the ids itself. This holds for both periodic and single shot
75 * notifications. The reason being that the owner of the #GstClockID has to
76 * keep a handle to the #GstClockID to unblock the wait on FLUSHING events or
77 * state changes and if the entry would be unreffed automatically, the handle
78 * might become invalid without any notification.
80 * These clock operations do not operate on the running time, so the callbacks
81 * will also occur when not in PLAYING state as if the clock just keeps on
82 * running. Some clocks however do not progress when the element that provided
83 * the clock is not PLAYING.
85 * When a clock has the #GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be
86 * slaved to another #GstClock with the gst_clock_set_master(). The clock will
87 * then automatically be synchronized to this master clock by repeatedly
88 * sampling the master clock and the slave clock and recalibrating the slave
89 * clock with gst_clock_set_calibration(). This feature is mostly useful for
90 * plugins that have an internal clock but must operate with another clock
91 * selected by the #GstPipeline. They can track the offset and rate difference
92 * of their internal clock relative to the master clock by using the
93 * gst_clock_get_calibration() function.
95 * The master/slave synchronisation can be tuned with the #GstClock:timeout,
96 * #GstClock:window-size and #GstClock:window-threshold properties.
97 * The #GstClock:timeout property defines the interval to sample the master
98 * clock and run the calibration functions. #GstClock:window-size defines the
99 * number of samples to use when calibrating and #GstClock:window-threshold
100 * defines the minimum number of samples before the calibration is performed.
102 * Last reviewed on 2009-05-21 (0.10.24)
106 #include "gst_private.h"
109 #include "gstclock.h"
111 #include "gstutils.h"
112 #include "glib-compat-private.h"
114 #ifndef GST_DISABLE_TRACE
115 /* #define GST_WITH_ALLOC_TRACE */
116 #include "gsttrace.h"
117 static GstAllocTrace *_gst_clock_entry_trace;
120 /* #define DEBUGGING_ENABLED */
122 #define DEFAULT_STATS FALSE
123 #define DEFAULT_WINDOW_SIZE 32
124 #define DEFAULT_WINDOW_THRESHOLD 4
125 #define DEFAULT_TIMEOUT GST_SECOND / 10
132 PROP_WINDOW_THRESHOLD,
136 struct _GstClockPrivate
143 #define read_seqbegin(clock) \
144 g_atomic_int_get (&clock->ABI.priv->post_count);
146 static inline gboolean
147 read_seqretry (GstClock * clock, gint seq)
149 /* no retry if the seqnum did not change */
150 if (G_LIKELY (seq == g_atomic_int_get (&clock->ABI.priv->pre_count)))
153 /* wait for the writer to finish and retry */
154 GST_OBJECT_LOCK (clock);
155 GST_OBJECT_UNLOCK (clock);
159 #define write_seqlock(clock) \
161 GST_OBJECT_LOCK (clock); \
162 g_atomic_int_inc (&clock->ABI.priv->pre_count); \
165 #define write_sequnlock(clock) \
167 g_atomic_int_inc (&clock->ABI.priv->post_count); \
168 GST_OBJECT_UNLOCK (clock); \
171 static void gst_clock_dispose (GObject * object);
172 static void gst_clock_finalize (GObject * object);
174 static void gst_clock_set_property (GObject * object, guint prop_id,
175 const GValue * value, GParamSpec * pspec);
176 static void gst_clock_get_property (GObject * object, guint prop_id,
177 GValue * value, GParamSpec * pspec);
178 static void gst_clock_update_stats (GstClock * clock);
181 static GstObjectClass *parent_class = NULL;
183 /* static guint gst_clock_signals[LAST_SIGNAL] = { 0 }; */
186 gst_clock_entry_new (GstClock * clock, GstClockTime time,
187 GstClockTime interval, GstClockEntryType type)
189 GstClockEntry *entry;
191 entry = g_slice_new (GstClockEntry);
192 #ifndef GST_DISABLE_TRACE
193 gst_alloc_trace_new (_gst_clock_entry_trace, entry);
195 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
196 "created entry %p, time %" GST_TIME_FORMAT, entry, GST_TIME_ARGS (time));
199 entry->clock = clock;
202 entry->interval = interval;
203 entry->status = GST_CLOCK_OK;
205 entry->user_data = NULL;
206 entry->destroy_data = NULL;
207 entry->unscheduled = FALSE;
208 entry->woken_up = FALSE;
210 return (GstClockID) entry;
213 /* WARNING : Does not modify the refcount
214 * WARNING : Do not use if a pending clock operation is happening on that entry */
216 gst_clock_entry_reinit (GstClock * clock, GstClockEntry * entry,
217 GstClockTime time, GstClockTime interval, GstClockEntryType type)
219 g_return_val_if_fail (entry->status != GST_CLOCK_BUSY, FALSE);
220 g_return_val_if_fail (entry->clock == clock, FALSE);
224 entry->interval = interval;
225 entry->status = GST_CLOCK_OK;
226 entry->unscheduled = FALSE;
227 entry->woken_up = FALSE;
233 * gst_clock_single_shot_id_reinit:
234 * @clock: a #GstClock
236 * @time: The requested time.
238 * Reinitializes the provided single shot @id to the provided time. Does not
239 * modify the reference count.
241 * Returns: %TRUE if the GstClockID could be reinitialized to the provided
242 * @time, else %FALSE.
247 gst_clock_single_shot_id_reinit (GstClock * clock, GstClockID id,
250 return gst_clock_entry_reinit (clock, (GstClockEntry *) id, time,
251 GST_CLOCK_TIME_NONE, GST_CLOCK_ENTRY_SINGLE);
255 * gst_clock_periodic_id_reinit:
256 * @clock: a #GstClock
258 * @start_time: the requested start time
259 * @interval: the requested interval
261 * Reinitializes the provided periodic @id to the provided start time and
262 * interval. Does not modify the reference count.
264 * Returns: %TRUE if the GstClockID could be reinitialized to the provided
265 * @time, else %FALSE.
271 gst_clock_periodic_id_reinit (GstClock * clock, GstClockID id,
272 GstClockTime start_time, GstClockTime interval)
274 return gst_clock_entry_reinit (clock, (GstClockEntry *) id, start_time,
275 interval, GST_CLOCK_ENTRY_PERIODIC);
280 * @id: The #GstClockID to ref
282 * Increase the refcount of given @id.
284 * Returns: (transfer full): The same #GstClockID with increased refcount.
289 gst_clock_id_ref (GstClockID id)
291 g_return_val_if_fail (id != NULL, NULL);
293 g_atomic_int_inc (&((GstClockEntry *) id)->refcount);
299 _gst_clock_id_free (GstClockID id)
301 GstClockEntry *entry;
302 g_return_if_fail (id != NULL);
304 GST_CAT_DEBUG (GST_CAT_CLOCK, "freed entry %p", id);
305 entry = (GstClockEntry *) id;
306 if (entry->destroy_data)
307 entry->destroy_data (entry->user_data);
309 #ifndef GST_DISABLE_TRACE
310 gst_alloc_trace_free (_gst_clock_entry_trace, id);
312 g_slice_free (GstClockEntry, id);
316 * gst_clock_id_unref:
317 * @id: (transfer full): The #GstClockID to unref
319 * Unref given @id. When the refcount reaches 0 the
320 * #GstClockID will be freed.
325 gst_clock_id_unref (GstClockID id)
329 g_return_if_fail (id != NULL);
331 zero = g_atomic_int_dec_and_test (&((GstClockEntry *) id)->refcount);
332 /* if we ended up with the refcount at zero, free the id */
334 _gst_clock_id_free (id);
339 * gst_clock_new_single_shot_id:
340 * @clock: The #GstClockID to get a single shot notification from
341 * @time: the requested time
343 * Get a #GstClockID from @clock to trigger a single shot
344 * notification at the requested time. The single shot id should be
345 * unreffed after usage.
347 * Free-function: gst_clock_id_unref
349 * Returns: (transfer full): a #GstClockID that can be used to request the
355 gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time)
357 g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);
359 return gst_clock_entry_new (clock,
360 time, GST_CLOCK_TIME_NONE, GST_CLOCK_ENTRY_SINGLE);
364 * gst_clock_new_periodic_id:
365 * @clock: The #GstClockID to get a periodic notification id from
366 * @start_time: the requested start time
367 * @interval: the requested interval
369 * Get an ID from @clock to trigger a periodic notification.
370 * The periodic notifications will start at time @start_time and
371 * will then be fired with the given @interval. @id should be unreffed
374 * Free-function: gst_clock_id_unref
376 * Returns: (transfer full): a #GstClockID that can be used to request the
382 gst_clock_new_periodic_id (GstClock * clock, GstClockTime start_time,
383 GstClockTime interval)
385 g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);
386 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (start_time), NULL);
387 g_return_val_if_fail (interval != 0, NULL);
388 g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (interval), NULL);
390 return gst_clock_entry_new (clock,
391 start_time, interval, GST_CLOCK_ENTRY_PERIODIC);
395 * gst_clock_id_compare_func
396 * @id1: A #GstClockID
397 * @id2: A #GstClockID to compare with
399 * Compares the two #GstClockID instances. This function can be used
400 * as a GCompareFunc when sorting ids.
402 * Returns: negative value if a < b; zero if a = b; positive value if a > b
407 gst_clock_id_compare_func (gconstpointer id1, gconstpointer id2)
409 GstClockEntry *entry1, *entry2;
411 entry1 = (GstClockEntry *) id1;
412 entry2 = (GstClockEntry *) id2;
414 if (GST_CLOCK_ENTRY_TIME (entry1) > GST_CLOCK_ENTRY_TIME (entry2)) {
417 if (GST_CLOCK_ENTRY_TIME (entry1) < GST_CLOCK_ENTRY_TIME (entry2)) {
424 * gst_clock_id_get_time
425 * @id: The #GstClockID to query
427 * Get the time of the clock ID
429 * Returns: the time of the given clock id.
434 gst_clock_id_get_time (GstClockID id)
436 g_return_val_if_fail (id != NULL, GST_CLOCK_TIME_NONE);
438 return GST_CLOCK_ENTRY_TIME ((GstClockEntry *) id);
443 * @id: The #GstClockID to wait on
444 * @jitter: (out) (allow-none): a pointer that will contain the jitter,
447 * Perform a blocking wait on @id.
448 * @id should have been created with gst_clock_new_single_shot_id()
449 * or gst_clock_new_periodic_id() and should not have been unscheduled
450 * with a call to gst_clock_id_unschedule().
452 * If the @jitter argument is not %NULL and this function returns #GST_CLOCK_OK
453 * or #GST_CLOCK_EARLY, it will contain the difference
454 * against the clock and the time of @id when this method was
456 * Positive values indicate how late @id was relative to the clock
457 * (in which case this function will return #GST_CLOCK_EARLY).
458 * Negative values indicate how much time was spent waiting on the clock
459 * before this function returned.
461 * Returns: the result of the blocking wait. #GST_CLOCK_EARLY will be returned
462 * if the current clock time is past the time of @id, #GST_CLOCK_OK if
463 * @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
464 * unscheduled with gst_clock_id_unschedule().
469 gst_clock_id_wait (GstClockID id, GstClockTimeDiff * jitter)
471 GstClockEntry *entry;
474 GstClockTime requested;
475 GstClockClass *cclass;
477 g_return_val_if_fail (id != NULL, GST_CLOCK_ERROR);
479 entry = (GstClockEntry *) id;
480 requested = GST_CLOCK_ENTRY_TIME (entry);
482 clock = GST_CLOCK_ENTRY_CLOCK (entry);
484 /* can't sync on invalid times */
485 if (G_UNLIKELY (!GST_CLOCK_TIME_IS_VALID (requested)))
488 cclass = GST_CLOCK_GET_CLASS (clock);
490 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "waiting on clock entry %p", id);
492 /* if we have a wait_jitter function, use that */
493 if (G_LIKELY (cclass->wait_jitter)) {
494 res = cclass->wait_jitter (clock, entry, jitter);
496 /* check if we have a simple _wait function otherwise. The function without
497 * the jitter arg is less optimal as we need to do an additional _get_time()
498 * which is not atomic with the _wait() and a typical _wait() function does
499 * yet another _get_time() anyway. */
500 if (G_UNLIKELY (cclass->wait == NULL))
504 GstClockTime now = gst_clock_get_time (clock);
506 /* jitter is the diff against the clock when this entry is scheduled. Negative
507 * values mean that the entry was in time, a positive value means that the
508 * entry was too late. */
509 *jitter = GST_CLOCK_DIFF (requested, now);
511 res = cclass->wait (clock, entry);
514 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
515 "done waiting entry %p, res: %d", id, res);
517 if (entry->type == GST_CLOCK_ENTRY_PERIODIC)
518 entry->time = requested + entry->interval;
520 if (G_UNLIKELY (clock->stats))
521 gst_clock_update_stats (clock);
528 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
529 "invalid time requested, returning _BADTIME");
530 return GST_CLOCK_BADTIME;
534 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "clock wait is not supported");
535 return GST_CLOCK_UNSUPPORTED;
540 * gst_clock_id_wait_async_full:
541 * @id: a #GstClockID to wait on
542 * @func: The callback function
543 * @user_data: User data passed in the callback
544 * @destroy_data: #GDestroyNotify for user_data
546 * Register a callback on the given #GstClockID @id with the given
547 * function and user_data. When passing a #GstClockID with an invalid
548 * time to this function, the callback will be called immediately
549 * with a time set to GST_CLOCK_TIME_NONE. The callback will
550 * be called when the time of @id has been reached.
552 * The callback @func can be invoked from any thread, either provided by the
553 * core or from a streaming thread. The application should be prepared for this.
555 * Returns: the result of the non blocking wait.
562 gst_clock_id_wait_async_full (GstClockID id,
563 GstClockCallback func, gpointer user_data, GDestroyNotify destroy_data)
565 GstClockEntry *entry;
568 GstClockClass *cclass;
569 GstClockTime requested;
571 g_return_val_if_fail (id != NULL, GST_CLOCK_ERROR);
572 g_return_val_if_fail (func != NULL, GST_CLOCK_ERROR);
574 entry = (GstClockEntry *) id;
575 requested = GST_CLOCK_ENTRY_TIME (entry);
576 clock = GST_CLOCK_ENTRY_CLOCK (entry);
578 /* can't sync on invalid times */
579 if (G_UNLIKELY (!GST_CLOCK_TIME_IS_VALID (requested)))
582 cclass = GST_CLOCK_GET_CLASS (clock);
584 if (G_UNLIKELY (cclass->wait_async == NULL))
588 entry->user_data = user_data;
589 entry->destroy_data = destroy_data;
591 res = cclass->wait_async (clock, entry);
598 (func) (clock, GST_CLOCK_TIME_NONE, id, user_data);
599 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
600 "invalid time requested, returning _BADTIME");
601 return GST_CLOCK_BADTIME;
605 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "clock wait is not supported");
606 return GST_CLOCK_UNSUPPORTED;
611 * gst_clock_id_wait_async:
612 * @id: a #GstClockID to wait on
613 * @func: The callback function
614 * @user_data: User data passed in the callback
616 * Register a callback on the given #GstClockID @id with the given
617 * function and user_data. When passing a #GstClockID with an invalid
618 * time to this function, the callback will be called immediately
619 * with a time set to GST_CLOCK_TIME_NONE. The callback will
620 * be called when the time of @id has been reached.
622 * The callback @func can be invoked from any thread, either provided by the
623 * core or from a streaming thread. The application should be prepared for this.
625 * Returns: the result of the non blocking wait.
630 gst_clock_id_wait_async (GstClockID id,
631 GstClockCallback func, gpointer user_data)
633 return gst_clock_id_wait_async_full (id, func, user_data, NULL);
637 * gst_clock_id_unschedule:
638 * @id: The id to unschedule
640 * Cancel an outstanding request with @id. This can either
641 * be an outstanding async notification or a pending sync notification.
642 * After this call, @id cannot be used anymore to receive sync or
643 * async notifications, you need to create a new #GstClockID.
648 gst_clock_id_unschedule (GstClockID id)
650 GstClockEntry *entry;
652 GstClockClass *cclass;
654 g_return_if_fail (id != NULL);
656 entry = (GstClockEntry *) id;
657 clock = entry->clock;
659 cclass = GST_CLOCK_GET_CLASS (clock);
661 if (G_LIKELY (cclass->unschedule))
662 cclass->unschedule (clock, entry);
667 * GstClock abstract base class implementation
669 G_DEFINE_TYPE (GstClock, gst_clock, GST_TYPE_OBJECT);
672 gst_clock_class_init (GstClockClass * klass)
674 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
676 parent_class = g_type_class_peek_parent (klass);
678 #ifndef GST_DISABLE_TRACE
679 _gst_clock_entry_trace =
680 gst_alloc_trace_register (GST_CLOCK_ENTRY_TRACE_NAME);
683 gobject_class->dispose = gst_clock_dispose;
684 gobject_class->finalize = gst_clock_finalize;
685 gobject_class->set_property = gst_clock_set_property;
686 gobject_class->get_property = gst_clock_get_property;
688 g_object_class_install_property (gobject_class, PROP_STATS,
689 g_param_spec_boolean ("stats", "Stats",
690 "Enable clock stats (unimplemented)", DEFAULT_STATS,
691 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
692 g_object_class_install_property (gobject_class, PROP_WINDOW_SIZE,
693 g_param_spec_int ("window-size", "Window size",
694 "The size of the window used to calculate rate and offset", 2, 1024,
695 DEFAULT_WINDOW_SIZE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
696 g_object_class_install_property (gobject_class, PROP_WINDOW_THRESHOLD,
697 g_param_spec_int ("window-threshold", "Window threshold",
698 "The threshold to start calculating rate and offset", 2, 1024,
699 DEFAULT_WINDOW_THRESHOLD,
700 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
701 g_object_class_install_property (gobject_class, PROP_TIMEOUT,
702 g_param_spec_uint64 ("timeout", "Timeout",
703 "The amount of time, in nanoseconds, to sample master and slave clocks",
704 0, G_MAXUINT64, DEFAULT_TIMEOUT,
705 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
707 g_type_class_add_private (klass, sizeof (GstClockPrivate));
711 gst_clock_init (GstClock * clock)
713 clock->last_time = 0;
714 clock->entries = NULL;
715 clock->entries_changed = g_cond_new ();
716 clock->stats = FALSE;
719 G_TYPE_INSTANCE_GET_PRIVATE (clock, GST_TYPE_CLOCK, GstClockPrivate);
721 clock->internal_calibration = 0;
722 clock->external_calibration = 0;
723 clock->rate_numerator = 1;
724 clock->rate_denominator = 1;
726 clock->slave_lock = g_mutex_new ();
727 clock->window_size = DEFAULT_WINDOW_SIZE;
728 clock->window_threshold = DEFAULT_WINDOW_THRESHOLD;
729 clock->filling = TRUE;
730 clock->time_index = 0;
731 clock->timeout = DEFAULT_TIMEOUT;
732 clock->times = g_new0 (GstClockTime, 4 * clock->window_size);
736 gst_clock_dispose (GObject * object)
738 GstClock *clock = GST_CLOCK (object);
741 GST_OBJECT_LOCK (clock);
742 master_p = &clock->master;
743 gst_object_replace ((GstObject **) master_p, NULL);
744 GST_OBJECT_UNLOCK (clock);
746 G_OBJECT_CLASS (parent_class)->dispose (object);
750 gst_clock_finalize (GObject * object)
752 GstClock *clock = GST_CLOCK (object);
754 GST_CLOCK_SLAVE_LOCK (clock);
755 if (clock->clockid) {
756 gst_clock_id_unschedule (clock->clockid);
757 gst_clock_id_unref (clock->clockid);
758 clock->clockid = NULL;
760 g_free (clock->times);
762 GST_CLOCK_SLAVE_UNLOCK (clock);
764 g_cond_free (clock->entries_changed);
765 g_mutex_free (clock->slave_lock);
767 G_OBJECT_CLASS (parent_class)->finalize (object);
771 * gst_clock_set_resolution
772 * @clock: a #GstClock
773 * @resolution: The resolution to set
775 * Set the accuracy of the clock. Some clocks have the possibility to operate
776 * with different accuracy at the expense of more resource usage. There is
777 * normally no need to change the default resolution of a clock. The resolution
778 * of a clock can only be changed if the clock has the
779 * #GST_CLOCK_FLAG_CAN_SET_RESOLUTION flag set.
781 * Returns: the new resolution of the clock.
784 gst_clock_set_resolution (GstClock * clock, GstClockTime resolution)
786 GstClockClass *cclass;
788 g_return_val_if_fail (GST_IS_CLOCK (clock), 0);
789 g_return_val_if_fail (resolution != 0, 0);
791 cclass = GST_CLOCK_GET_CLASS (clock);
793 if (cclass->change_resolution)
795 cclass->change_resolution (clock, clock->resolution, resolution);
797 return clock->resolution;
801 * gst_clock_get_resolution
802 * @clock: a #GstClock
804 * Get the accuracy of the clock. The accuracy of the clock is the granularity
805 * of the values returned by gst_clock_get_time().
807 * Returns: the resolution of the clock in units of #GstClockTime.
812 gst_clock_get_resolution (GstClock * clock)
814 GstClockClass *cclass;
816 g_return_val_if_fail (GST_IS_CLOCK (clock), 0);
818 cclass = GST_CLOCK_GET_CLASS (clock);
820 if (cclass->get_resolution)
821 return cclass->get_resolution (clock);
827 * gst_clock_adjust_unlocked
828 * @clock: a #GstClock to use
829 * @internal: a clock time
831 * Converts the given @internal clock time to the external time, adjusting for the
832 * rate and reference time set with gst_clock_set_calibration() and making sure
833 * that the returned time is increasing. This function should be called with the
834 * clock's OBJECT_LOCK held and is mainly used by clock subclasses.
836 * This function is the reverse of gst_clock_unadjust_unlocked().
838 * Returns: the converted time of the clock.
841 gst_clock_adjust_unlocked (GstClock * clock, GstClockTime internal)
843 GstClockTime ret, cinternal, cexternal, cnum, cdenom;
845 /* get calibration values for readability */
846 cinternal = clock->internal_calibration;
847 cexternal = clock->external_calibration;
848 cnum = clock->rate_numerator;
849 cdenom = clock->rate_denominator;
851 /* avoid divide by 0 */
852 if (G_UNLIKELY (cdenom == 0))
855 /* The formula is (internal - cinternal) * cnum / cdenom + cexternal
857 * Since we do math on unsigned 64-bit ints we have to special case for
858 * internal < cinternal to get the sign right. this case is not very common,
861 if (G_LIKELY (internal >= cinternal)) {
862 ret = internal - cinternal;
863 ret = gst_util_uint64_scale (ret, cnum, cdenom);
866 ret = cinternal - internal;
867 ret = gst_util_uint64_scale (ret, cnum, cdenom);
869 if (G_LIKELY (cexternal > ret))
870 ret = cexternal - ret;
875 /* make sure the time is increasing */
876 clock->last_time = MAX (ret, clock->last_time);
878 return clock->last_time;
882 * gst_clock_unadjust_unlocked
883 * @clock: a #GstClock to use
884 * @external: an external clock time
886 * Converts the given @external clock time to the internal time of @clock,
887 * using the rate and reference time set with gst_clock_set_calibration().
888 * This function should be called with the clock's OBJECT_LOCK held and
889 * is mainly used by clock subclasses.
891 * This function is the reverse of gst_clock_adjust_unlocked().
893 * Returns: the internal time of the clock corresponding to @external.
898 gst_clock_unadjust_unlocked (GstClock * clock, GstClockTime external)
900 GstClockTime ret, cinternal, cexternal, cnum, cdenom;
902 /* get calibration values for readability */
903 cinternal = clock->internal_calibration;
904 cexternal = clock->external_calibration;
905 cnum = clock->rate_numerator;
906 cdenom = clock->rate_denominator;
908 /* avoid divide by 0 */
909 if (G_UNLIKELY (cnum == 0))
912 /* The formula is (external - cexternal) * cdenom / cnum + cinternal */
913 if (G_LIKELY (external >= cexternal)) {
914 ret = external - cexternal;
915 ret = gst_util_uint64_scale (ret, cdenom, cnum);
918 ret = cexternal - external;
919 ret = gst_util_uint64_scale (ret, cdenom, cnum);
920 if (G_LIKELY (cinternal > ret))
921 ret = cinternal - ret;
929 * gst_clock_get_internal_time
930 * @clock: a #GstClock to query
932 * Gets the current internal time of the given clock. The time is returned
933 * unadjusted for the offset and the rate.
935 * Returns: the internal time of the clock. Or GST_CLOCK_TIME_NONE when
936 * given invalid input.
941 gst_clock_get_internal_time (GstClock * clock)
944 GstClockClass *cclass;
946 g_return_val_if_fail (GST_IS_CLOCK (clock), GST_CLOCK_TIME_NONE);
948 cclass = GST_CLOCK_GET_CLASS (clock);
950 if (G_UNLIKELY (cclass->get_internal_time == NULL))
953 ret = cclass->get_internal_time (clock);
955 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "internal time %" GST_TIME_FORMAT,
956 GST_TIME_ARGS (ret));
963 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
964 "internal time not supported, return 0");
965 return G_GINT64_CONSTANT (0);
971 * @clock: a #GstClock to query
973 * Gets the current time of the given clock. The time is always
974 * monotonically increasing and adjusted according to the current
977 * Returns: the time of the clock. Or GST_CLOCK_TIME_NONE when
978 * given invalid input.
983 gst_clock_get_time (GstClock * clock)
988 g_return_val_if_fail (GST_IS_CLOCK (clock), GST_CLOCK_TIME_NONE);
991 /* reget the internal time when we retry to get the most current
993 ret = gst_clock_get_internal_time (clock);
995 seq = read_seqbegin (clock);
996 /* this will scale for rate and offset */
997 ret = gst_clock_adjust_unlocked (clock, ret);
998 } while (read_seqretry (clock, seq));
1000 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "adjusted time %" GST_TIME_FORMAT,
1001 GST_TIME_ARGS (ret));
1007 * gst_clock_set_calibration
1008 * @clock: a #GstClock to calibrate
1009 * @internal: a reference internal time
1010 * @external: a reference external time
1011 * @rate_num: the numerator of the rate of the clock relative to its
1013 * @rate_denom: the denominator of the rate of the clock
1015 * Adjusts the rate and time of @clock. A rate of 1/1 is the normal speed of
1016 * the clock. Values bigger than 1/1 make the clock go faster.
1018 * @internal and @external are calibration parameters that arrange that
1019 * gst_clock_get_time() should have been @external at internal time @internal.
1020 * This internal time should not be in the future; that is, it should be less
1021 * than the value of gst_clock_get_internal_time() when this function is called.
1023 * Subsequent calls to gst_clock_get_time() will return clock times computed as
1027 * time = (internal_time - internal) * rate_num / rate_denom + external
1030 * This formula is implemented in gst_clock_adjust_unlocked(). Of course, it
1031 * tries to do the integer arithmetic as precisely as possible.
1033 * Note that gst_clock_get_time() always returns increasing values so when you
1034 * move the clock backwards, gst_clock_get_time() will report the previous value
1035 * until the clock catches up.
1040 gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime
1041 external, GstClockTime rate_num, GstClockTime rate_denom)
1043 g_return_if_fail (GST_IS_CLOCK (clock));
1044 g_return_if_fail (rate_num != GST_CLOCK_TIME_NONE);
1045 g_return_if_fail (rate_denom > 0 && rate_denom != GST_CLOCK_TIME_NONE);
1047 write_seqlock (clock);
1048 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
1049 "internal %" GST_TIME_FORMAT " external %" GST_TIME_FORMAT " %"
1050 G_GUINT64_FORMAT "/%" G_GUINT64_FORMAT " = %f", GST_TIME_ARGS (internal),
1051 GST_TIME_ARGS (external), rate_num, rate_denom,
1052 gst_guint64_to_gdouble (rate_num) / gst_guint64_to_gdouble (rate_denom));
1054 clock->internal_calibration = internal;
1055 clock->external_calibration = external;
1056 clock->rate_numerator = rate_num;
1057 clock->rate_denominator = rate_denom;
1058 write_sequnlock (clock);
1062 * gst_clock_get_calibration
1063 * @clock: a #GstClock
1064 * @internal: (out) (allow-none): a location to store the internal time
1065 * @external: (out) (allow-none): a location to store the external time
1066 * @rate_num: (out) (allow-none): a location to store the rate numerator
1067 * @rate_denom: (out) (allow-none): a location to store the rate denominator
1069 * Gets the internal rate and reference time of @clock. See
1070 * gst_clock_set_calibration() for more information.
1072 * @internal, @external, @rate_num, and @rate_denom can be left %NULL if the
1073 * caller is not interested in the values.
1078 gst_clock_get_calibration (GstClock * clock, GstClockTime * internal,
1079 GstClockTime * external, GstClockTime * rate_num, GstClockTime * rate_denom)
1083 g_return_if_fail (GST_IS_CLOCK (clock));
1086 seq = read_seqbegin (clock);
1088 *rate_num = clock->rate_numerator;
1090 *rate_denom = clock->rate_denominator;
1092 *external = clock->external_calibration;
1094 *internal = clock->internal_calibration;
1095 } while (read_seqretry (clock, seq));
1098 /* will be called repeatedly to sample the master and slave clock
1099 * to recalibrate the clock */
1101 gst_clock_slave_callback (GstClock * master, GstClockTime time,
1102 GstClockID id, GstClock * clock)
1104 GstClockTime stime, mtime;
1107 stime = gst_clock_get_internal_time (clock);
1108 mtime = gst_clock_get_time (master);
1110 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
1111 "master %" GST_TIME_FORMAT ", slave %" GST_TIME_FORMAT,
1112 GST_TIME_ARGS (mtime), GST_TIME_ARGS (stime));
1114 gst_clock_add_observation (clock, stime, mtime, &r_squared);
1116 /* FIXME, we can use the r_squared value to adjust the timeout
1117 * value of the clockid */
1123 * gst_clock_set_master
1124 * @clock: a #GstClock
1125 * @master: (allow-none): a master #GstClock
1127 * Set @master as the master clock for @clock. @clock will be automatically
1128 * calibrated so that gst_clock_get_time() reports the same time as the
1131 * A clock provider that slaves its clock to a master can get the current
1132 * calibration values with gst_clock_get_calibration().
1134 * @master can be %NULL in which case @clock will not be slaved anymore. It will
1135 * however keep reporting its time adjusted with the last configured rate
1138 * Returns: %TRUE if the clock is capable of being slaved to a master clock.
1139 * Trying to set a master on a clock without the
1140 * #GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return %FALSE.
1145 gst_clock_set_master (GstClock * clock, GstClock * master)
1147 GstClock **master_p;
1149 g_return_val_if_fail (GST_IS_CLOCK (clock), FALSE);
1150 g_return_val_if_fail (master != clock, FALSE);
1152 GST_OBJECT_LOCK (clock);
1153 /* we always allow setting the master to NULL */
1154 if (master && !GST_OBJECT_FLAG_IS_SET (clock, GST_CLOCK_FLAG_CAN_SET_MASTER))
1156 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
1157 "slaving %p to master clock %p", clock, master);
1158 GST_OBJECT_UNLOCK (clock);
1160 GST_CLOCK_SLAVE_LOCK (clock);
1161 if (clock->clockid) {
1162 gst_clock_id_unschedule (clock->clockid);
1163 gst_clock_id_unref (clock->clockid);
1164 clock->clockid = NULL;
1167 clock->filling = TRUE;
1168 clock->time_index = 0;
1169 /* use the master periodic id to schedule sampling and
1170 * clock calibration. */
1171 clock->clockid = gst_clock_new_periodic_id (master,
1172 gst_clock_get_time (master), clock->timeout);
1173 gst_clock_id_wait_async_full (clock->clockid,
1174 (GstClockCallback) gst_clock_slave_callback,
1175 gst_object_ref (clock), (GDestroyNotify) gst_object_unref);
1177 GST_CLOCK_SLAVE_UNLOCK (clock);
1179 GST_OBJECT_LOCK (clock);
1180 master_p = &clock->master;
1181 gst_object_replace ((GstObject **) master_p, (GstObject *) master);
1182 GST_OBJECT_UNLOCK (clock);
1189 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
1190 "cannot be slaved to a master clock");
1191 GST_OBJECT_UNLOCK (clock);
1197 * gst_clock_get_master:
1198 * @clock: a #GstClock
1200 * Get the master clock that @clock is slaved to or %NULL when the clock is
1201 * not slaved to any master clock.
1203 * Returns: (transfer full): a master #GstClock or %NULL when this clock is
1204 * not slaved to a master clock. Unref after usage.
1209 gst_clock_get_master (GstClock * clock)
1211 GstClock *result = NULL;
1213 g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);
1215 GST_OBJECT_LOCK (clock);
1217 result = gst_object_ref (clock->master);
1218 GST_OBJECT_UNLOCK (clock);
1223 /* http://mathworld.wolfram.com/LeastSquaresFitting.html
1227 do_linear_regression (GstClock * clock, GstClockTime * m_num,
1228 GstClockTime * m_denom, GstClockTime * b, GstClockTime * xbase,
1229 gdouble * r_squared)
1231 GstClockTime *newx, *newy;
1232 GstClockTime xmin, ymin, xbar, ybar, xbar4, ybar4;
1233 GstClockTimeDiff sxx, sxy, syy;
1234 GstClockTime *x, *y;
1238 xbar = ybar = sxx = syy = sxy = 0;
1241 y = clock->times + 2;
1242 n = clock->filling ? clock->time_index : clock->window_size;
1244 #ifdef DEBUGGING_ENABLED
1245 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "doing regression on:");
1246 for (i = j = 0; i < n; i++, j += 4)
1247 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
1248 " %" G_GUINT64_FORMAT " %" G_GUINT64_FORMAT, x[j], y[j]);
1251 xmin = ymin = G_MAXUINT64;
1252 for (i = j = 0; i < n; i++, j += 4) {
1253 xmin = MIN (xmin, x[j]);
1254 ymin = MIN (ymin, y[j]);
1257 #ifdef DEBUGGING_ENABLED
1258 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "min x: %" G_GUINT64_FORMAT,
1260 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "min y: %" G_GUINT64_FORMAT,
1264 newx = clock->times + 1;
1265 newy = clock->times + 3;
1267 /* strip off unnecessary bits of precision */
1268 for (i = j = 0; i < n; i++, j += 4) {
1269 newx[j] = x[j] - xmin;
1270 newy[j] = y[j] - ymin;
1273 #ifdef DEBUGGING_ENABLED
1274 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "reduced numbers:");
1275 for (i = j = 0; i < n; i++, j += 4)
1276 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
1277 " %" G_GUINT64_FORMAT " %" G_GUINT64_FORMAT, newx[j], newy[j]);
1280 /* have to do this precisely otherwise the results are pretty much useless.
1281 * should guarantee that none of these accumulators can overflow */
1283 /* quantities on the order of 1e10 -> 30 bits; window size a max of 2^10, so
1284 this addition could end up around 2^40 or so -- ample headroom */
1285 for (i = j = 0; i < n; i++, j += 4) {
1292 #ifdef DEBUGGING_ENABLED
1293 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, " xbar = %" G_GUINT64_FORMAT,
1295 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, " ybar = %" G_GUINT64_FORMAT,
1299 /* multiplying directly would give quantities on the order of 1e20 -> 60 bits;
1300 times the window size that's 70 which is too much. Instead we (1) subtract
1301 off the xbar*ybar in the loop instead of after, to avoid accumulation; (2)
1302 shift off 4 bits from each multiplicand, giving an expected ceiling of 52
1303 bits, which should be enough. Need to check the incoming range and domain
1304 to ensure this is an appropriate loss of precision though. */
1307 for (i = j = 0; i < n; i++, j += 4) {
1308 GstClockTime newx4, newy4;
1310 newx4 = newx[j] >> 4;
1311 newy4 = newy[j] >> 4;
1313 sxx += newx4 * newx4 - xbar4 * xbar4;
1314 syy += newy4 * newy4 - ybar4 * ybar4;
1315 sxy += newx4 * newy4 - xbar4 * ybar4;
1318 if (G_UNLIKELY (sxx == 0))
1324 *b = (ybar + ymin) - gst_util_uint64_scale (xbar, *m_num, *m_denom);
1325 *r_squared = ((double) sxy * (double) sxy) / ((double) sxx * (double) syy);
1327 #ifdef DEBUGGING_ENABLED
1328 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, " m = %g",
1329 ((double) *m_num) / *m_denom);
1330 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, " b = %" G_GUINT64_FORMAT,
1332 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, " xbase = %" G_GUINT64_FORMAT,
1334 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, " r2 = %g", *r_squared);
1341 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "sxx == 0, regression failed");
1347 * gst_clock_add_observation
1348 * @clock: a #GstClock
1349 * @slave: a time on the slave
1350 * @master: a time on the master
1351 * @r_squared: (out): a pointer to hold the result
1353 * The time @master of the master clock and the time @slave of the slave
1354 * clock are added to the list of observations. If enough observations
1355 * are available, a linear regression algorithm is run on the
1356 * observations and @clock is recalibrated.
1358 * If this functions returns %TRUE, @r_squared will contain the
1359 * correlation coefficient of the interpolation. A value of 1.0
1360 * means a perfect regression was performed. This value can
1361 * be used to control the sampling frequency of the master and slave
1364 * Returns: %TRUE if enough observations were added to run the
1365 * regression algorithm.
1370 gst_clock_add_observation (GstClock * clock, GstClockTime slave,
1371 GstClockTime master, gdouble * r_squared)
1373 GstClockTime m_num, m_denom, b, xbase;
1375 g_return_val_if_fail (GST_IS_CLOCK (clock), FALSE);
1376 g_return_val_if_fail (r_squared != NULL, FALSE);
1378 GST_CLOCK_SLAVE_LOCK (clock);
1380 GST_CAT_LOG_OBJECT (GST_CAT_CLOCK, clock,
1381 "adding observation slave %" GST_TIME_FORMAT ", master %" GST_TIME_FORMAT,
1382 GST_TIME_ARGS (slave), GST_TIME_ARGS (master));
1384 clock->times[(4 * clock->time_index)] = slave;
1385 clock->times[(4 * clock->time_index) + 2] = master;
1387 clock->time_index++;
1388 if (G_UNLIKELY (clock->time_index == clock->window_size)) {
1389 clock->filling = FALSE;
1390 clock->time_index = 0;
1393 if (G_UNLIKELY (clock->filling
1394 && clock->time_index < clock->window_threshold))
1397 if (!do_linear_regression (clock, &m_num, &m_denom, &b, &xbase, r_squared))
1400 GST_CLOCK_SLAVE_UNLOCK (clock);
1402 GST_CAT_LOG_OBJECT (GST_CAT_CLOCK, clock,
1403 "adjusting clock to m=%" G_GUINT64_FORMAT "/%" G_GUINT64_FORMAT ", b=%"
1404 G_GUINT64_FORMAT " (rsquared=%g)", m_num, m_denom, b, *r_squared);
1406 /* if we have a valid regression, adjust the clock */
1407 gst_clock_set_calibration (clock, xbase, b, m_num, m_denom);
1413 GST_CLOCK_SLAVE_UNLOCK (clock);
1418 /* no valid regression has been done, ignore the result then */
1419 GST_CLOCK_SLAVE_UNLOCK (clock);
1425 gst_clock_update_stats (GstClock * clock)
1430 gst_clock_set_property (GObject * object, guint prop_id,
1431 const GValue * value, GParamSpec * pspec)
1435 clock = GST_CLOCK (object);
1439 GST_OBJECT_LOCK (clock);
1440 clock->stats = g_value_get_boolean (value);
1441 GST_OBJECT_UNLOCK (clock);
1443 case PROP_WINDOW_SIZE:
1444 GST_CLOCK_SLAVE_LOCK (clock);
1445 clock->window_size = g_value_get_int (value);
1446 clock->window_threshold =
1447 MIN (clock->window_threshold, clock->window_size);
1449 g_renew (GstClockTime, clock->times, 4 * clock->window_size);
1450 /* restart calibration */
1451 clock->filling = TRUE;
1452 clock->time_index = 0;
1453 GST_CLOCK_SLAVE_UNLOCK (clock);
1455 case PROP_WINDOW_THRESHOLD:
1456 GST_CLOCK_SLAVE_LOCK (clock);
1457 clock->window_threshold =
1458 MIN (g_value_get_int (value), clock->window_size);
1459 GST_CLOCK_SLAVE_UNLOCK (clock);
1462 GST_CLOCK_SLAVE_LOCK (clock);
1463 clock->timeout = g_value_get_uint64 (value);
1464 GST_CLOCK_SLAVE_UNLOCK (clock);
1467 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1473 gst_clock_get_property (GObject * object, guint prop_id,
1474 GValue * value, GParamSpec * pspec)
1478 clock = GST_CLOCK (object);
1482 GST_OBJECT_LOCK (clock);
1483 g_value_set_boolean (value, clock->stats);
1484 GST_OBJECT_UNLOCK (clock);
1486 case PROP_WINDOW_SIZE:
1487 GST_CLOCK_SLAVE_LOCK (clock);
1488 g_value_set_int (value, clock->window_size);
1489 GST_CLOCK_SLAVE_UNLOCK (clock);
1491 case PROP_WINDOW_THRESHOLD:
1492 GST_CLOCK_SLAVE_LOCK (clock);
1493 g_value_set_int (value, clock->window_threshold);
1494 GST_CLOCK_SLAVE_UNLOCK (clock);
1497 GST_CLOCK_SLAVE_LOCK (clock);
1498 g_value_set_uint64 (value, clock->timeout);
1499 GST_CLOCK_SLAVE_UNLOCK (clock);
1502 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);