gstclock.c 36.6 KB
Newer Older
1 2 3
/* GStreamer
 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
 *                    2000 Wim Taymans <wtay@chello.be>
4
 *                    2004 Wim Taymans <wim@fluendo.com>
5 6
 *
 * gstclock.c: Clock subsystem for maintaining time sync
Wim Taymans's avatar
Wim Taymans committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * 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.
 */
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
23

24 25 26
/**
 * SECTION:gstclock
 * @short_description: Abstract class for global clocks
Wim Taymans's avatar
Wim Taymans committed
27
 * @see_also: #GstSystemClock, #GstPipeline
28
 *
Wim Taymans's avatar
Wim Taymans committed
29
 * GStreamer uses a global clock to synchronize the plugins in a pipeline.
30 31 32
 * Different clock implementations are possible by implementing this abstract
 * base class.
 *
Wim Taymans's avatar
Wim Taymans committed
33
 * The #GstClock returns a monotonically increasing time with the method
Wim Taymans's avatar
Wim Taymans committed
34 35
 * gst_clock_get_time(). Its accuracy and base time depend on the specific
 * clock implementation but time is always expressed in nanoseconds. Since the
Wim Taymans's avatar
Wim Taymans committed
36
 * baseline of the clock is undefined, the clock time returned is not
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
37
 * meaningful in itself, what matters are the deltas between two clock times.
Wim Taymans's avatar
Wim Taymans committed
38
 * The time returned by a clock is called the absolute time.
Wim Taymans's avatar
Wim Taymans committed
39
 *
Wim Taymans's avatar
Wim Taymans committed
40
 * The pipeline uses the clock to calculate the stream time. Usually all
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
41
 * renderers synchronize to the global clock using the buffer timestamps, the
Wim Taymans's avatar
Wim Taymans committed
42
 * newsegment events and the element's base time, see #GstPipeline.
Wim Taymans's avatar
Wim Taymans committed
43
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
44 45
 * A clock implementation can support periodic and single shot clock
 * notifications both synchronous and asynchronous.
Wim Taymans's avatar
Wim Taymans committed
46 47
 *
 * One first needs to create a #GstClockID for the periodic or single shot
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
48 49
 * notification using gst_clock_new_single_shot_id() or
 * gst_clock_new_periodic_id().
Wim Taymans's avatar
Wim Taymans committed
50 51 52
 *
 * To perform a blocking wait for the specific time of the #GstClockID use the
 * gst_clock_id_wait(). To receive a callback when the specific time is reached
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
53 54 55
 * in the clock use gst_clock_id_wait_async(). Both these calls can be
 * interrupted with the gst_clock_id_unschedule() call. If the blocking wait is
 * unscheduled a return value of GST_CLOCK_UNSCHEDULED is returned.
Wim Taymans's avatar
Wim Taymans committed
56
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
57
 * Periodic callbacks scheduled async will be repeadedly called automatically
Wim Taymans's avatar
Wim Taymans committed
58
 * until it is unscheduled. To schedule a sync periodic callback,
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
59
 * gst_clock_id_wait() should be called repeadedly.
60
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
61 62
 * 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.
Wim Taymans's avatar
Wim Taymans committed
63 64
 *
 * A #GstClockID that has been unscheduled cannot be used again for any wait
Wim Taymans's avatar
Wim Taymans committed
65 66
 * operation, a new #GstClockID should be created and the old unscheduled one
 * should be destroyed wirth gst_clock_id_unref().
Wim Taymans's avatar
Wim Taymans committed
67
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
68 69
 * It is possible to perform a blocking wait on the same #GstClockID from
 * multiple threads. However, registering the same #GstClockID for multiple
Wim Taymans's avatar
Wim Taymans committed
70 71
 * async notifications is not possible, the callback will only be called for
 * the thread registering the entry last.
Wim Taymans's avatar
Wim Taymans committed
72
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
73 74 75 76
 * None of the wait operations unref the #GstClockID, the owner is responsible
 * for unreffing the ids itself. This holds for both periodic and single shot
 * notifications. The reason being that the owner of the #GstClockID has to
 * keep a handle to the #GstClockID to unblock the wait on FLUSHING events or
Wim Taymans's avatar
Wim Taymans committed
77 78
 * state changes and if the entry would be unreffed automatically, the handle 
 * might become invalid without any notification.
Wim Taymans's avatar
Wim Taymans committed
79 80 81 82 83 84
 *
 * These clock operations do not operate on the stream time, so the callbacks
 * will also occur when not in PLAYING state as if the clock just keeps on
 * running. Some clocks however do not progress when the element that provided
 * the clock is not PLAYING.
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
85 86 87 88 89 90 91 92
 * When a clock has the GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be
 * slaved to another #GstClock with the gst_clock_set_master(). The clock will
 * then automatically be synchronized to this master clock by repeadedly
 * sampling the master clock and the slave clock and recalibrating the slave
 * clock with gst_clock_set_calibration(). This feature is mostly usefull for
 * plugins that have an internal clock but must operate with another clock
 * selected by the #GstPipeline.  They can track the offset and rate difference
 * of their internal clock relative to the master clock by using the
Wim Taymans's avatar
Wim Taymans committed
93 94 95 96 97 98 99 100
 * gst_clock_get_calibration() function. 
 *
 * The master/slave synchronisation can be tuned with the "timeout", "window-size"
 * and "window-threshold" properties. The "timeout" property defines the interval
 * to sample the master clock and run the calibration functions. 
 * "window-size" defines the number of samples to use when calibrating and
 * "window-threshold" defines the minimum number of samples before the 
 * calibration is performed.
Wim Taymans's avatar
Wim Taymans committed
101
 *
Wim Taymans's avatar
Wim Taymans committed
102
 * Last reviewed on 2006-03-09 (0.10.4)
103
 */
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
104

105 106

#include "gst_private.h"
107
#include <time.h>
108

109
#include "gstclock.h"
110
#include "gstinfo.h"
111
#include "gstutils.h"
Wim Taymans's avatar
Wim Taymans committed
112

Wim Taymans's avatar
Wim Taymans committed
113
#ifndef GST_DISABLE_TRACE
Wim Taymans's avatar
Wim Taymans committed
114
/* #define GST_WITH_ALLOC_TRACE */
Wim Taymans's avatar
Wim Taymans committed
115 116 117
#include "gsttrace.h"
static GstAllocTrace *_gst_clock_entry_trace;
#endif
Wim Taymans's avatar
Wim Taymans committed
118

119 120
/* #define DEBUGGING_ENABLED */

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
121 122 123 124
#define DEFAULT_STATS                   FALSE
#define DEFAULT_WINDOW_SIZE             32
#define DEFAULT_WINDOW_THRESHOLD        4
#define DEFAULT_TIMEOUT                 GST_SECOND / 10
125

126 127
enum
{
128 129 130 131 132
  PROP_0,
  PROP_STATS,
  PROP_WINDOW_SIZE,
  PROP_WINDOW_THRESHOLD,
  PROP_TIMEOUT
133 134
};

135 136
static void gst_clock_class_init (GstClockClass * klass);
static void gst_clock_init (GstClock * clock);
137
static void gst_clock_dispose (GObject * object);
Wim Taymans's avatar
Wim Taymans committed
138
static void gst_clock_finalize (GObject * object);
Wim Taymans's avatar
Wim Taymans committed
139

140 141 142 143 144
static void gst_clock_set_property (GObject * object, guint prop_id,
    const GValue * value, GParamSpec * pspec);
static void gst_clock_get_property (GObject * object, guint prop_id,
    GValue * value, GParamSpec * pspec);
static void gst_clock_update_stats (GstClock * clock);
145

146

147
static GstObjectClass *parent_class = NULL;
148

149 150
/* static guint gst_clock_signals[LAST_SIGNAL] = { 0 }; */

Wim Taymans's avatar
Wim Taymans committed
151
static GstClockID
152 153
gst_clock_entry_new (GstClock * clock, GstClockTime time,
    GstClockTime interval, GstClockEntryType type)
154 155
{
  GstClockEntry *entry;
156

Wim Taymans's avatar
Wim Taymans committed
157 158 159
  /* FIXME, use g_slice, we do this a lot and potentially from
   * different threads. */
  entry = g_new0 (GstClockEntry, 1);
Wim Taymans's avatar
Wim Taymans committed
160
#ifndef GST_DISABLE_TRACE
Wim Taymans's avatar
Wim Taymans committed
161
  gst_alloc_trace_new (_gst_clock_entry_trace, entry);
Wim Taymans's avatar
Wim Taymans committed
162
#endif
163 164
  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
      "created entry %p, time %" GST_TIME_FORMAT, entry, GST_TIME_ARGS (time));
165

166
  gst_atomic_int_set (&entry->refcount, 1);
167 168
  entry->clock = clock;
  entry->time = time;
169
  entry->interval = interval;
170
  entry->type = type;
171
  entry->status = GST_CLOCK_BUSY;
172

173 174
  return (GstClockID) entry;
}
175

176 177
/**
 * gst_clock_id_ref:
Wim Taymans's avatar
Wim Taymans committed
178
 * @id: The #GstClockID to ref
179
 *
Wim Taymans's avatar
Wim Taymans committed
180
 * Increase the refcount of given @id.
181 182 183 184 185 186 187 188 189 190
 *
 * Returns: The same #GstClockID with increased refcount.
 *
 * MT safe.
 */
GstClockID
gst_clock_id_ref (GstClockID id)
{
  g_return_val_if_fail (id != NULL, NULL);

191
  g_atomic_int_inc (&((GstClockEntry *) id)->refcount);
192 193 194 195 196 197 198 199 200 201 202 203 204 205

  return id;
}

static void
_gst_clock_id_free (GstClockID id)
{
  g_return_if_fail (id != NULL);

  GST_CAT_DEBUG (GST_CAT_CLOCK, "freed entry %p", id);

#ifndef GST_DISABLE_TRACE
  gst_alloc_trace_free (_gst_clock_entry_trace, id);
#endif
206
  g_free (id);
207 208 209 210
}

/**
 * gst_clock_id_unref:
Wim Taymans's avatar
Wim Taymans committed
211
 * @id: The #GstClockID to unref
212
 *
Wim Taymans's avatar
Wim Taymans committed
213
 * Unref given @id. When the refcount reaches 0 the
214 215 216 217 218 219 220 221 222 223 224
 * #GstClockID will be freed.
 *
 * MT safe.
 */
void
gst_clock_id_unref (GstClockID id)
{
  gint zero;

  g_return_if_fail (id != NULL);

225
  zero = g_atomic_int_dec_and_test (&((GstClockEntry *) id)->refcount);
226 227 228 229 230 231
  /* if we ended up with the refcount at zero, free the id */
  if (zero) {
    _gst_clock_id_free (id);
  }
}

232 233
/**
 * gst_clock_new_single_shot_id
Wim Taymans's avatar
Wim Taymans committed
234
 * @clock: The #GstClockID to get a single shot notification from
235 236
 * @time: the requested time
 *
Wim Taymans's avatar
Wim Taymans committed
237
 * Get a #GstClockID from @clock to trigger a single shot
238 239
 * notification at the requested time. The single shot id should be
 * unreffed after usage.
240
 *
Wim Taymans's avatar
Wim Taymans committed
241
 * Returns: A #GstClockID that can be used to request the time notification.
242 243
 *
 * MT safe.
244 245
 */
GstClockID
246
gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time)
247
{
248 249
  g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);

250 251
  return gst_clock_entry_new (clock,
      time, GST_CLOCK_TIME_NONE, GST_CLOCK_ENTRY_SINGLE);
252 253 254
}

/**
Wim Taymans's avatar
Wim Taymans committed
255
 * gst_clock_new_periodic_id
Wim Taymans's avatar
Wim Taymans committed
256
 * @clock: The #GstClockID to get a periodic notification id from
257 258 259
 * @start_time: the requested start time
 * @interval: the requested interval
 *
Wim Taymans's avatar
Wim Taymans committed
260
 * Get an ID from @clock to trigger a periodic notification.
261
 * The periodeic notifications will be start at time start_time and
Wim Taymans's avatar
Wim Taymans committed
262
 * will then be fired with the given interval. @id should be unreffed
263
 * after usage.
264
 *
Wim Taymans's avatar
Wim Taymans committed
265
 * Returns: A #GstClockID that can be used to request the time notification.
266 267
 *
 * MT safe.
268 269
 */
GstClockID
270 271
gst_clock_new_periodic_id (GstClock * clock, GstClockTime start_time,
    GstClockTime interval)
272
{
273
  g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);
274
  g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (start_time), NULL);
275 276
  g_return_val_if_fail (interval != 0, NULL);

277 278
  return gst_clock_entry_new (clock,
      start_time, interval, GST_CLOCK_ENTRY_PERIODIC);
279 280
}

281 282
/**
 * gst_clock_id_compare_func
Wim Taymans's avatar
Wim Taymans committed
283 284
 * @id1: A #GstClockID
 * @id2: A #GstClockID to compare with
285
 *
Wim Taymans's avatar
Wim Taymans committed
286
 * Compares the two #GstClockID instances. This function can be used
287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306
 * as a GCompareFunc when sorting ids.
 *
 * Returns: negative value if a < b; zero if a = b; positive value if a > b
 *
 * MT safe.
 */
gint
gst_clock_id_compare_func (gconstpointer id1, gconstpointer id2)
{
  GstClockEntry *entry1, *entry2;

  entry1 = (GstClockEntry *) id1;
  entry2 = (GstClockEntry *) id2;

  if (GST_CLOCK_ENTRY_TIME (entry1) > GST_CLOCK_ENTRY_TIME (entry2)) {
    return 1;
  }
  if (GST_CLOCK_ENTRY_TIME (entry1) < GST_CLOCK_ENTRY_TIME (entry2)) {
    return -1;
  }
Wim Taymans's avatar
Wim Taymans committed
307
  return 0;
308 309
}

310 311
/**
 * gst_clock_id_get_time
Wim Taymans's avatar
Wim Taymans committed
312
 * @id: The #GstClockID to query
313 314 315
 *
 * Get the time of the clock ID
 *
316 317 318
 * Returns: the time of the given clock id.
 *
 * MT safe.
319 320 321 322 323 324
 */
GstClockTime
gst_clock_id_get_time (GstClockID id)
{
  g_return_val_if_fail (id != NULL, GST_CLOCK_TIME_NONE);

325
  return GST_CLOCK_ENTRY_TIME ((GstClockEntry *) id);
326 327 328 329 330
}


/**
 * gst_clock_id_wait
Wim Taymans's avatar
Wim Taymans committed
331 332 333 334 335 336 337 338 339 340 341
 * @id: The #GstClockID to wait on
 * @jitter: A pointer that will contain the jitter, can be NULL.
 *
 * Perform a blocking wait on @id. 
 * @id should have been created with gst_clock_new_single_shot_id()
 * or gst_clock_new_periodic_id() and should not have been unscheduled
 * with a call to gst_clock_id_unschedule(). 
 *
 * If the @jitter argument is not NULL and this function returns #GST_CLOCK_OK
 * or #GST_CLOCK_EARLY, it will contain the difference
 * against the clock and the time of @id when this method was
342 343 344 345
 * called. Negative values indicate how late @id was relative to the clock
 * (in which case this function will return #GST_CLOCK_EARLY). 
 * Positive values indicate how much time was spent waiting on the clock 
 * before this function returned.
Wim Taymans's avatar
Wim Taymans committed
346 347 348 349 350
 *
 * Returns: the result of the blocking wait. #GST_CLOCK_EARLY will be returned
 * if the current clock time is past the time of @id, #GST_CLOCK_OK if 
 * @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was 
 * unscheduled with gst_clock_id_unschedule().
351 352
 *
 * MT safe.
353 354
 */
GstClockReturn
355
gst_clock_id_wait (GstClockID id, GstClockTimeDiff * jitter)
356 357
{
  GstClockEntry *entry;
358
  GstClock *clock;
359
  GstClockReturn res;
360
  GstClockTime requested;
Wim Taymans's avatar
Wim Taymans committed
361
  GstClockClass *cclass;
362

363
  g_return_val_if_fail (id != NULL, GST_CLOCK_ERROR);
364

365 366
  entry = (GstClockEntry *) id;
  requested = GST_CLOCK_ENTRY_TIME (entry);
367

368 369
  clock = GST_CLOCK_ENTRY_CLOCK (entry);

Wim Taymans's avatar
Wim Taymans committed
370
  /* can't sync on invalid times */
371 372 373
  if (G_UNLIKELY (!GST_CLOCK_TIME_IS_VALID (requested)))
    goto invalid_time;

Wim Taymans's avatar
Wim Taymans committed
374
  /* a previously unscheduled entry cannot be scheduled again */
375 376
  if (G_UNLIKELY (entry->status == GST_CLOCK_UNSCHEDULED))
    goto unscheduled;
377

Wim Taymans's avatar
Wim Taymans committed
378
  cclass = GST_CLOCK_GET_CLASS (clock);
379

Wim Taymans's avatar
Wim Taymans committed
380 381
  if (G_UNLIKELY (cclass->wait == NULL))
    goto not_supported;
382

Wim Taymans's avatar
Wim Taymans committed
383 384 385 386 387 388 389 390 391 392 393 394 395 396 397
  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "waiting on clock entry %p", id);

  /* jitter is the diff against the clock when this entry is scheduled */
  if (jitter) {
    GstClockTime now = gst_clock_get_time (clock);

    *jitter = GST_CLOCK_DIFF (requested, now);
  }
  res = cclass->wait (clock, entry);

  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
      "done waiting entry %p, res: %d", id, res);

  if (entry->type == GST_CLOCK_ENTRY_PERIODIC) {
    entry->time += entry->interval;
398
  }
Wim Taymans's avatar
Wim Taymans committed
399 400 401 402

  if (clock->stats)
    gst_clock_update_stats (clock);

403
  return res;
404 405 406 407

  /* ERRORS */
invalid_time:
  {
408 409
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "invalid time requested, returning _BADTIME");
410 411 412 413
    return GST_CLOCK_BADTIME;
  }
unscheduled:
  {
414 415
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "entry was unscheduled return _UNSCHEDULED");
416 417
    return GST_CLOCK_UNSCHEDULED;
  }
Wim Taymans's avatar
Wim Taymans committed
418 419 420 421 422
not_supported:
  {
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "clock wait is not supported");
    return GST_CLOCK_UNSUPPORTED;
  }
423 424 425
}

/**
Wim Taymans's avatar
Wim Taymans committed
426 427
 * gst_clock_id_wait_async:
 * @id: a #GstClockID to wait on
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
428
 * @func: The callback function
429 430
 * @user_data: User data passed in the calback
 *
Wim Taymans's avatar
Wim Taymans committed
431 432
 * Register a callback on the given #GstClockID @id with the given
 * function and user_data. When passing a #GstClockID with an invalid
433 434
 * time to this function, the callback will be called immediatly
 * with  a time set to GST_CLOCK_TIME_NONE. The callback will
Wim Taymans's avatar
Wim Taymans committed
435
 * be called when the time of @id has been reached.
436
 *
437
 * Returns: the result of the non blocking wait.
438 439
 *
 * MT safe.
440 441 442
 */
GstClockReturn
gst_clock_id_wait_async (GstClockID id,
443
    GstClockCallback func, gpointer user_data)
444 445 446
{
  GstClockEntry *entry;
  GstClock *clock;
447
  GstClockReturn res;
Wim Taymans's avatar
Wim Taymans committed
448
  GstClockClass *cclass;
449
  GstClockTime requested;
450

451
  g_return_val_if_fail (id != NULL, GST_CLOCK_ERROR);
452
  g_return_val_if_fail (func != NULL, GST_CLOCK_ERROR);
453 454

  entry = (GstClockEntry *) id;
455 456
  requested = GST_CLOCK_ENTRY_TIME (entry);
  clock = GST_CLOCK_ENTRY_CLOCK (entry);
457

Wim Taymans's avatar
Wim Taymans committed
458
  /* can't sync on invalid times */
459 460 461
  if (G_UNLIKELY (!GST_CLOCK_TIME_IS_VALID (requested)))
    goto invalid_time;

Wim Taymans's avatar
Wim Taymans committed
462
  /* a previously unscheduled entry cannot be scheduled again */
463 464
  if (G_UNLIKELY (entry->status == GST_CLOCK_UNSCHEDULED))
    goto unscheduled;
465

Wim Taymans's avatar
Wim Taymans committed
466 467
  cclass = GST_CLOCK_GET_CLASS (clock);

Wim Taymans's avatar
Wim Taymans committed
468 469 470 471 472 473 474
  if (G_UNLIKELY (cclass->wait_async == NULL))
    goto not_supported;

  entry->func = func;
  entry->user_data = user_data;

  res = cclass->wait_async (clock, entry);
Wim Taymans's avatar
Wim Taymans committed
475

476 477
  return res;

478 479 480 481
  /* ERRORS */
invalid_time:
  {
    (func) (clock, GST_CLOCK_TIME_NONE, id, user_data);
482 483
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "invalid time requested, returning _BADTIME");
484 485 486 487
    return GST_CLOCK_BADTIME;
  }
unscheduled:
  {
488 489
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "entry was unscheduled return _UNSCHEDULED");
490 491
    return GST_CLOCK_UNSCHEDULED;
  }
Wim Taymans's avatar
Wim Taymans committed
492 493 494 495 496
not_supported:
  {
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "clock wait is not supported");
    return GST_CLOCK_UNSUPPORTED;
  }
497 498
}

499
/**
Wim Taymans's avatar
Wim Taymans committed
500 501
 * gst_clock_id_unschedule:
 * @id: The id to unschedule
502
 *
Wim Taymans's avatar
Wim Taymans committed
503
 * Cancel an outstanding request with @id. This can either
504
 * be an outstanding async notification or a pending sync notification.
Wim Taymans's avatar
Wim Taymans committed
505 506
 * After this call, @id cannot be used anymore to receive sync or
 * async notifications, you need to create a new #GstClockID.
507 508
 *
 * MT safe.
509 510 511 512 513 514
 */
void
gst_clock_id_unschedule (GstClockID id)
{
  GstClockEntry *entry;
  GstClock *clock;
Wim Taymans's avatar
Wim Taymans committed
515
  GstClockClass *cclass;
516

517 518 519 520
  g_return_if_fail (id != NULL);

  entry = (GstClockEntry *) id;
  clock = entry->clock;
521

Wim Taymans's avatar
Wim Taymans committed
522 523
  cclass = GST_CLOCK_GET_CLASS (clock);

Wim Taymans's avatar
Wim Taymans committed
524
  if (G_LIKELY (cclass->unschedule))
Wim Taymans's avatar
Wim Taymans committed
525
    cclass->unschedule (clock, entry);
526 527
}

528 529 530 531

/**
 * GstClock abstract base class implementation
 */
532 533
GType
gst_clock_get_type (void)
Wim Taymans's avatar
Wim Taymans committed
534
{
535 536
  static GType clock_type = 0;

537
  if (G_UNLIKELY (clock_type == 0)) {
538
    static const GTypeInfo clock_info = {
539
      sizeof (GstClockClass),
540 541 542 543 544
      NULL,
      NULL,
      (GClassInitFunc) gst_clock_class_init,
      NULL,
      NULL,
545
      sizeof (GstClock),
546
      0,
547 548 549
      (GInstanceInitFunc) gst_clock_init,
      NULL
    };
550

551
    clock_type = g_type_register_static (GST_TYPE_OBJECT, "GstClock",
552
        &clock_info, G_TYPE_FLAG_ABSTRACT);
553 554 555
  }
  return clock_type;
}
556

557
static void
558
gst_clock_class_init (GstClockClass * klass)
559 560 561
{
  GObjectClass *gobject_class;
  GstObjectClass *gstobject_class;
562

563 564
  gobject_class = G_OBJECT_CLASS (klass);
  gstobject_class = GST_OBJECT_CLASS (klass);
565

566
  parent_class = g_type_class_peek_parent (klass);
567

Wim Taymans's avatar
Wim Taymans committed
568 569 570
  if (!g_thread_supported ())
    g_thread_init (NULL);

Wim Taymans's avatar
Wim Taymans committed
571
#ifndef GST_DISABLE_TRACE
572 573
  _gst_clock_entry_trace =
      gst_alloc_trace_register (GST_CLOCK_ENTRY_TRACE_NAME);
Wim Taymans's avatar
Wim Taymans committed
574
#endif
575

576
  gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_clock_dispose);
Wim Taymans's avatar
Wim Taymans committed
577
  gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_clock_finalize);
578 579 580
  gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_clock_set_property);
  gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_clock_get_property);

581
  g_object_class_install_property (gobject_class, PROP_STATS,
582 583 584
      g_param_spec_boolean ("stats", "Stats",
          "Enable clock stats (unimplemented)", DEFAULT_STATS,
          G_PARAM_READWRITE));
585
  g_object_class_install_property (gobject_class, PROP_WINDOW_SIZE,
586 587 588
      g_param_spec_int ("window-size", "Window size",
          "The size of the window used to calculate rate and offset", 2, 1024,
          DEFAULT_WINDOW_SIZE, G_PARAM_READWRITE));
589 590
  g_object_class_install_property (gobject_class, PROP_WINDOW_THRESHOLD,
      g_param_spec_int ("window-threshold", "Window threshold",
591 592
          "The threshold to start calculating rate and offset", 2, 1024,
          DEFAULT_WINDOW_THRESHOLD, G_PARAM_READWRITE));
593
  g_object_class_install_property (gobject_class, PROP_TIMEOUT,
594 595 596
      g_param_spec_uint64 ("timeout", "Timeout",
          "The amount of time, in nanoseconds, to sample master and slave clocks",
          0, G_MAXUINT64, DEFAULT_TIMEOUT, G_PARAM_READWRITE));
Wim Taymans's avatar
Wim Taymans committed
597 598
}

599
static void
600
gst_clock_init (GstClock * clock)
Wim Taymans's avatar
Wim Taymans committed
601
{
602 603
  clock->last_time = 0;
  clock->entries = NULL;
604
  clock->entries_changed = g_cond_new ();
605
  clock->stats = FALSE;
606

607 608
  clock->internal_calibration = 0;
  clock->external_calibration = 0;
609 610 611 612
  clock->rate_numerator = 1;
  clock->rate_denominator = 1;

  clock->slave_lock = g_mutex_new ();
613 614
  clock->window_size = DEFAULT_WINDOW_SIZE;
  clock->window_threshold = DEFAULT_WINDOW_THRESHOLD;
Wim Taymans's avatar
Wim Taymans committed
615
  clock->filling = TRUE;
616 617 618
  clock->time_index = 0;
  clock->timeout = DEFAULT_TIMEOUT;
  clock->times = g_new0 (GstClockTime, 4 * clock->window_size);
Wim Taymans's avatar
Wim Taymans committed
619 620
}

621 622 623 624
static void
gst_clock_dispose (GObject * object)
{
  GstClock *clock = GST_CLOCK (object);
625
  GstClock **master_p;
626 627

  GST_OBJECT_LOCK (clock);
628 629
  master_p = &clock->master;
  gst_object_replace ((GstObject **) master_p, NULL);
630 631 632 633 634
  GST_OBJECT_UNLOCK (clock);

  G_OBJECT_CLASS (parent_class)->dispose (object);
}

Wim Taymans's avatar
Wim Taymans committed
635
static void
Wim Taymans's avatar
Wim Taymans committed
636
gst_clock_finalize (GObject * object)
Wim Taymans's avatar
Wim Taymans committed
637 638 639
{
  GstClock *clock = GST_CLOCK (object);

640
  GST_CLOCK_SLAVE_LOCK (clock);
641 642 643 644 645 646 647
  if (clock->clockid) {
    gst_clock_id_unschedule (clock->clockid);
    gst_clock_id_unref (clock->clockid);
    clock->clockid = NULL;
  }
  g_free (clock->times);
  clock->times = NULL;
648
  GST_CLOCK_SLAVE_UNLOCK (clock);
649

650
  g_cond_free (clock->entries_changed);
651 652
  g_mutex_free (clock->slave_lock);

Wim Taymans's avatar
Wim Taymans committed
653
  G_OBJECT_CLASS (parent_class)->finalize (object);
Wim Taymans's avatar
Wim Taymans committed
654 655
}

Wim Taymans's avatar
Wim Taymans committed
656
/**
657
 * gst_clock_set_resolution
658
 * @clock: a #GstClock
659
 * @resolution: The resolution to set
Wim Taymans's avatar
Wim Taymans committed
660
 *
661 662 663
 * Set the accuracy of the clock.
 *
 * Returns: the new resolution of the clock.
Wim Taymans's avatar
Wim Taymans committed
664
 */
665 666
GstClockTime
gst_clock_set_resolution (GstClock * clock, GstClockTime resolution)
Wim Taymans's avatar
Wim Taymans committed
667
{
Wim Taymans's avatar
Wim Taymans committed
668 669
  GstClockClass *cclass;

670 671
  g_return_val_if_fail (GST_IS_CLOCK (clock), 0);
  g_return_val_if_fail (resolution != 0, 0);
672

Wim Taymans's avatar
Wim Taymans committed
673 674 675
  cclass = GST_CLOCK_GET_CLASS (clock);

  if (cclass->change_resolution)
676
    clock->resolution =
677
        cclass->change_resolution (clock, clock->resolution, resolution);
678

679 680
  return clock->resolution;
}
681

682 683
/**
 * gst_clock_get_resolution
684
 * @clock: a #GstClock
685 686 687
 *
 * Get the accuracy of the clock.
 *
688
 * Returns: the resolution of the clock in units of #GstClockTime.
689 690
 *
 * MT safe.
691
 */
692
GstClockTime
693
gst_clock_get_resolution (GstClock * clock)
694
{
Wim Taymans's avatar
Wim Taymans committed
695 696
  GstClockClass *cclass;

697
  g_return_val_if_fail (GST_IS_CLOCK (clock), 0);
698

Wim Taymans's avatar
Wim Taymans committed
699 700 701 702
  cclass = GST_CLOCK_GET_CLASS (clock);

  if (cclass->get_resolution)
    return cclass->get_resolution (clock);
703

704
  return 1;
Wim Taymans's avatar
Wim Taymans committed
705 706
}

Wim Taymans's avatar
Wim Taymans committed
707
/**
708 709 710
 * gst_clock_adjust_unlocked
 * @clock: a #GstClock to use
 * @internal: a clock time
Wim Taymans's avatar
Wim Taymans committed
711
 *
712
 * Converts the given @internal clock time to the real time, adjusting for the
713 714
 * rate and reference time set with gst_clock_set_calibration() and making sure
 * that the returned time is increasing. This function should be called with the
715
 * clock's OBJECT_LOCK held and is mainly used by clock subclasses.
Wim Taymans's avatar
Wim Taymans committed
716
 *
717
 * Returns: the converted time of the clock.
718
 *
719
 * MT safe.
720
 */
721 722
GstClockTime
gst_clock_adjust_unlocked (GstClock * clock, GstClockTime internal)
723
{
724
  GstClockTime ret;
725

726 727
  ret = gst_util_uint64_scale (internal - clock->internal_calibration,
      clock->rate_numerator, clock->rate_denominator);
728
  ret += clock->external_calibration;
729 730 731 732 733

  /* make sure the time is increasing */
  clock->last_time = MAX (ret, clock->last_time);

  return clock->last_time;
734 735
}

Wim Taymans's avatar
Wim Taymans committed
736
/**
737
 * gst_clock_get_internal_time
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
738
 * @clock: a #GstClock to query
Wim Taymans's avatar
Wim Taymans committed
739
 *
740 741
 * Gets the current internal time of the given clock. The time is returned
 * unadjusted for the offset and the rate.
742
 *
743
 * Returns: the internal time of the clock. Or GST_CLOCK_TIME_NONE when
744 745 746
 * giving wrong input.
 *
 * MT safe.
Wim Taymans's avatar
Wim Taymans committed
747
 */
748
GstClockTime
749
gst_clock_get_internal_time (GstClock * clock)
750
{
751
  GstClockTime ret;
752
  GstClockClass *cclass;
753

754
  g_return_val_if_fail (GST_IS_CLOCK (clock), GST_CLOCK_TIME_NONE);
755

756
  cclass = GST_CLOCK_GET_CLASS (clock);
Wim Taymans's avatar
Wim Taymans committed
757

Wim Taymans's avatar
Wim Taymans committed
758 759 760 761 762
  if (G_UNLIKELY (cclass->get_internal_time == NULL))
    goto not_supported;

  ret = cclass->get_internal_time (clock);

763
  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "internal time %" GST_TIME_FORMAT,
764
      GST_TIME_ARGS (ret));
765

766
  return ret;
Wim Taymans's avatar
Wim Taymans committed
767 768 769 770 771 772 773 774

  /* ERRORS */
not_supported:
  {
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "internal time not supported, return 0");
    return G_GINT64_CONSTANT (0);
  }
775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798
}

/**
 * gst_clock_get_time
 * @clock: a #GstClock to query
 *
 * Gets the current time of the given clock. The time is always
 * monotonically increasing and adjusted according to the current
 * offset and rate.
 *
 * Returns: the time of the clock. Or GST_CLOCK_TIME_NONE when
 * giving wrong input.
 *
 * MT safe.
 */
GstClockTime
gst_clock_get_time (GstClock * clock)
{
  GstClockTime ret;

  g_return_val_if_fail (GST_IS_CLOCK (clock), GST_CLOCK_TIME_NONE);

  ret = gst_clock_get_internal_time (clock);

799
  GST_OBJECT_LOCK (clock);
800
  /* this will scale for rate and offset */
801
  ret = gst_clock_adjust_unlocked (clock, ret);
802
  GST_OBJECT_UNLOCK (clock);
803

804
  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "adjusted time %" GST_TIME_FORMAT,
805
      GST_TIME_ARGS (ret));
806

807
  return ret;
808 809
}

810 811 812 813 814
/**
 * gst_clock_set_calibration
 * @clock: a #GstClock to calibrate
 * @internal: a reference internal time
 * @external: a reference external time
815 816 817
 * @rate_num: the numerator of the rate of the clock relative to its
 *            internal time 
 * @rate_denom: the denominator of the rate of the clock
818
 *
819 820
 * Adjusts the rate and time of @clock. A rate of 1/1 is the normal speed of
 * the clock. Values bigger than 1/1 make the clock go faster.
821 822 823 824 825
 *
 * @internal and @external are calibration parameters that arrange that
 * gst_clock_get_time() should have been @external at internal time @internal.
 * This internal time should not be in the future; that is, it should be less
 * than the value of gst_clock_get_internal_time() when this function is called.
826 827 828 829 830
 *
 * Subsequent calls to gst_clock_get_time() will return clock times computed as
 * follows:
 *
 * <programlisting>
831
 *   time = (internal_time - @internal) * @rate_num / @rate_denom + @external
832 833
 * </programlisting>
 *
834 835 836
 * This formula is implemented in gst_clock_adjust_unlocked(). Of course, it
 * tries to do the integer arithmetic as precisely as possible.
 *
837 838 839 840 841 842 843
 * Note that gst_clock_get_time() always returns increasing values so when you
 * move the clock backwards, gst_clock_get_time() will report the previous value
 * until the clock catches up.
 *
 * MT safe.
 */
void
844
gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime
845
    external, GstClockTime rate_num, GstClockTime rate_denom)
846 847
{
  g_return_if_fail (GST_IS_CLOCK (clock));
848
  g_return_if_fail (rate_num >= 0);
849
  g_return_if_fail (rate_denom > 0);
850
  g_return_if_fail (internal <= gst_clock_get_internal_time (clock));
851

852
  GST_OBJECT_LOCK (clock);
853 854
  clock->internal_calibration = internal;
  clock->external_calibration = external;
855 856
  clock->rate_numerator = rate_num;
  clock->rate_denominator = rate_denom;
857
  GST_OBJECT_UNLOCK (clock);
858 859 860
}

/**
861 862 863 864
 * gst_clock_get_calibration
 * @clock: a #GstClock 
 * @internal: a location to store the internal time
 * @external: a location to store the external time
865 866
 * @rate_num: a location to store the rate numerator
 * @rate_denom: a location to store the rate denominator
867
 *
868 869
 * Gets the internal rate and reference time of @clock. See
 * gst_clock_set_calibration() for more information.
870
 *
871 872
 * @internal, @external, @rate_num, and @rate_denom can be left NULL if the
 * caller is not interested in the values.
873
 *
874 875 876
 * MT safe.
 */
void
877
gst_clock_get_calibration (GstClock * clock, GstClockTime * internal,
878
    GstClockTime * external, GstClockTime * rate_num, GstClockTime * rate_denom)
879 880 881
{
  g_return_if_fail (GST_IS_CLOCK (clock));

882
  GST_OBJECT_LOCK (clock);
883 884 885 886
  if (rate_num)
    *rate_num = clock->rate_numerator;
  if (rate_denom)
    *rate_denom = clock->rate_denominator;
887
  if (external)
888
    *external = clock->external_calibration;
889
  if (internal)
890
    *internal = clock->internal_calibration;
891
  GST_OBJECT_UNLOCK (clock);
892 893
}

894
/* will be called repeadedly to sample the master and slave clock
Wim Taymans's avatar
Wim Taymans committed
895
 * to recalibrate the clock  */
896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917
static gboolean
gst_clock_slave_callback (GstClock * master, GstClockTime time,
    GstClockID id, GstClock * clock)
{
  GstClockTime stime, mtime;
  gdouble r_squared;

  stime = gst_clock_get_internal_time (clock);
  mtime = gst_clock_get_time (master);

  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
      "master %" GST_TIME_FORMAT ", slave %" GST_TIME_FORMAT,
      GST_TIME_ARGS (mtime), GST_TIME_ARGS (stime));

  gst_clock_add_observation (clock, stime, mtime, &r_squared);

  /* FIXME, we can use the r_squared value to adjust the timeout
   * value of the clockid */

  return TRUE;