gstclock.c 48.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
 *
 * 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
Tim-Philipp Müller's avatar
Tim-Philipp Müller committed
20 21
 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
 * Boston, MA 02110-1301, USA.
Wim Taymans's avatar
Wim Taymans committed
22
 */
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
 * Different clock implementations are possible by implementing this abstract
31
 * base class or, more conveniently, by subclassing #GstSystemClock.
32
 *
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
 *
40
 * The pipeline uses the clock to calculate the running 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
 * 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
Stefan Kost's avatar
Stefan Kost committed
55
 * unscheduled a return value of #GST_CLOCK_UNSCHEDULED is returned.
Wim Taymans's avatar
Wim Taymans committed
56
 *
57
 * Periodic callbacks scheduled async will be repeatedly called automatically
Wim Taymans's avatar
Wim Taymans committed
58
 * until it is unscheduled. To schedule a sync periodic callback,
59
 * gst_clock_id_wait() should be called repeatedly.
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
 * operation, a new #GstClockID should be created and the old unscheduled one
66
 * should be destroyed with 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
 * These clock operations do not operate on the running time, so the callbacks
Wim Taymans's avatar
Wim Taymans committed
81 82 83 84
 * 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.
 *
85
 * When a clock has the #GST_CLOCK_FLAG_CAN_SET_MASTER flag set, it can be
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
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
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
88
 * sampling the master clock and the slave clock and recalibrating the slave
Kjartan Maraas's avatar
Kjartan Maraas committed
89
 * clock with gst_clock_set_calibration(). This feature is mostly useful for
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
90 91 92
 * 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
 * gst_clock_get_calibration() function. 
 *
Stefan Kost's avatar
Stefan Kost committed
95 96 97 98 99 100
 * The master/slave synchronisation can be tuned with the #GstClock:timeout,
 * #GstClock:window-size and #GstClock:window-threshold properties.
 * The #GstClock:timeout property defines the interval to sample the master
 * clock and run the calibration functions. #GstClock:window-size defines the
 * number of samples to use when calibrating and #GstClock:window-threshold
 * defines the minimum number of samples before the calibration is performed.
101
 */
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
102

103
#include "gst_private.h"
104
#include <time.h>
105

106
#include "gstclock.h"
107
#include "gstinfo.h"
108
#include "gstutils.h"
109
#include "glib-compat-private.h"
Wim Taymans's avatar
Wim Taymans committed
110

111 112
/* #define DEBUGGING_ENABLED */

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
113 114 115
#define DEFAULT_WINDOW_SIZE             32
#define DEFAULT_WINDOW_THRESHOLD        4
#define DEFAULT_TIMEOUT                 GST_SECOND / 10
116

117 118
enum
{
119 120 121 122
  PROP_0,
  PROP_WINDOW_SIZE,
  PROP_WINDOW_THRESHOLD,
  PROP_TIMEOUT
123 124
};

125 126 127 128 129 130
enum
{
  SIGNAL_SYNCED,
  SIGNAL_LAST
};

Wim Taymans's avatar
Wim Taymans committed
131 132 133
#define GST_CLOCK_SLAVE_LOCK(clock)     g_mutex_lock (&GST_CLOCK_CAST (clock)->priv->slave_lock)
#define GST_CLOCK_SLAVE_UNLOCK(clock)   g_mutex_unlock (&GST_CLOCK_CAST (clock)->priv->slave_lock)

134 135
struct _GstClockPrivate
{
Wim Taymans's avatar
Wim Taymans committed
136 137
  GMutex slave_lock;            /* order: SLAVE_LOCK, OBJECT_LOCK */

138 139
  GCond sync_cond;

Wim Taymans's avatar
Wim Taymans committed
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
  /* with LOCK */
  GstClockTime internal_calibration;
  GstClockTime external_calibration;
  GstClockTime rate_numerator;
  GstClockTime rate_denominator;
  GstClockTime last_time;

  /* 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;
160
  GstClockTime *times_temp;
Wim Taymans's avatar
Wim Taymans committed
161 162
  GstClockID clockid;

163 164
  gint pre_count;
  gint post_count;
165 166

  gboolean synced;
167 168 169 170
};

/* seqlocks */
#define read_seqbegin(clock)                                   \
Wim Taymans's avatar
Wim Taymans committed
171
  g_atomic_int_get (&clock->priv->post_count);
172 173 174 175 176

static inline gboolean
read_seqretry (GstClock * clock, gint seq)
{
  /* no retry if the seqnum did not change */
Wim Taymans's avatar
Wim Taymans committed
177
  if (G_LIKELY (seq == g_atomic_int_get (&clock->priv->pre_count)))
178 179 180 181 182 183 184 185 186 187 188
    return FALSE;

  /* wait for the writer to finish and retry */
  GST_OBJECT_LOCK (clock);
  GST_OBJECT_UNLOCK (clock);
  return TRUE;
}

#define write_seqlock(clock)                      \
G_STMT_START {                                    \
  GST_OBJECT_LOCK (clock);                        \
Wim Taymans's avatar
Wim Taymans committed
189
  g_atomic_int_inc (&clock->priv->pre_count);     \
190 191 192 193
} G_STMT_END;

#define write_sequnlock(clock)                    \
G_STMT_START {                                    \
Wim Taymans's avatar
Wim Taymans committed
194
  g_atomic_int_inc (&clock->priv->post_count);    \
195 196 197
  GST_OBJECT_UNLOCK (clock);                      \
} G_STMT_END;

198
#ifndef GST_DISABLE_GST_DEBUG
199 200 201
static const gchar *
gst_clock_return_get_name (GstClockReturn ret)
{
202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
  switch (ret) {
    case GST_CLOCK_OK:
      return "ok";
    case GST_CLOCK_EARLY:
      return "early";
    case GST_CLOCK_UNSCHEDULED:
      return "unscheduled";
    case GST_CLOCK_BUSY:
      return "busy";
    case GST_CLOCK_BADTIME:
      return "bad-time";
    case GST_CLOCK_ERROR:
      return "error";
    case GST_CLOCK_UNSUPPORTED:
      return "unsupported";
    case GST_CLOCK_DONE:
      return "done";
    default:
      break;
221
  }
222

223 224
  return "unknown";
}
225
#endif /* GST_DISABLE_GST_DEBUG */
226

227
static void gst_clock_dispose (GObject * object);
Wim Taymans's avatar
Wim Taymans committed
228
static void gst_clock_finalize (GObject * object);
Wim Taymans's avatar
Wim Taymans committed
229

230 231 232 233
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);
234

235
static guint gst_clock_signals[SIGNAL_LAST] = { 0 };
236

Wim Taymans's avatar
Wim Taymans committed
237
static GstClockID
238 239
gst_clock_entry_new (GstClock * clock, GstClockTime time,
    GstClockTime interval, GstClockEntryType type)
240 241
{
  GstClockEntry *entry;
242

243
  entry = g_slice_new (GstClockEntry);
244 245 246

  /* FIXME: add tracer hook for struct allocations such as clock entries */

247 248
  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
      "created entry %p, time %" GST_TIME_FORMAT, entry, GST_TIME_ARGS (time));
249

250
  entry->refcount = 1;
251
  entry->clock = clock;
252
  entry->type = type;
253
  entry->time = time;
254
  entry->interval = interval;
255
  entry->status = GST_CLOCK_OK;
256 257
  entry->func = NULL;
  entry->user_data = NULL;
258
  entry->destroy_data = NULL;
259 260
  entry->unscheduled = FALSE;
  entry->woken_up = FALSE;
261

262 263
  return (GstClockID) entry;
}
264

265
/* WARNING : Does not modify the refcount
266 267 268 269 270 271 272 273 274 275 276 277
 * WARNING : Do not use if a pending clock operation is happening on that entry */
static gboolean
gst_clock_entry_reinit (GstClock * clock, GstClockEntry * entry,
    GstClockTime time, GstClockTime interval, GstClockEntryType type)
{
  g_return_val_if_fail (entry->status != GST_CLOCK_BUSY, FALSE);
  g_return_val_if_fail (entry->clock == clock, FALSE);

  entry->type = type;
  entry->time = time;
  entry->interval = interval;
  entry->status = GST_CLOCK_OK;
278 279
  entry->unscheduled = FALSE;
  entry->woken_up = FALSE;
280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303

  return TRUE;
}

/**
 * gst_clock_single_shot_id_reinit:
 * @clock: a #GstClock
 * @id: a #GstClockID
 * @time: The requested time.
 *
 * Reinitializes the provided single shot @id to the provided time. Does not
 * modify the reference count.
 *
 * Returns: %TRUE if the GstClockID could be reinitialized to the provided
 * @time, else %FALSE.
 */
gboolean
gst_clock_single_shot_id_reinit (GstClock * clock, GstClockID id,
    GstClockTime time)
{
  return gst_clock_entry_reinit (clock, (GstClockEntry *) id, time,
      GST_CLOCK_TIME_NONE, GST_CLOCK_ENTRY_SINGLE);
}

304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
/**
 * gst_clock_periodic_id_reinit:
 * @clock: a #GstClock
 * @id: a #GstClockID
 * @start_time: the requested start time
 * @interval: the requested interval
 *
 * Reinitializes the provided periodic @id to the provided start time and
 * interval. Does not modify the reference count.
 *
 * Returns: %TRUE if the GstClockID could be reinitialized to the provided
 * @time, else %FALSE.
 */
gboolean
gst_clock_periodic_id_reinit (GstClock * clock, GstClockID id,
    GstClockTime start_time, GstClockTime interval)
{
  return gst_clock_entry_reinit (clock, (GstClockEntry *) id, start_time,
      interval, GST_CLOCK_ENTRY_PERIODIC);
}

325 326
/**
 * gst_clock_id_ref:
Wim Taymans's avatar
Wim Taymans committed
327
 * @id: The #GstClockID to ref
328
 *
Wim Taymans's avatar
Wim Taymans committed
329
 * Increase the refcount of given @id.
330
 *
331
 * Returns: (transfer full): The same #GstClockID with increased refcount.
332 333 334 335 336 337 338 339
 *
 * MT safe.
 */
GstClockID
gst_clock_id_ref (GstClockID id)
{
  g_return_val_if_fail (id != NULL, NULL);

340
  g_atomic_int_inc (&((GstClockEntry *) id)->refcount);
341 342 343 344 345 346 347

  return id;
}

static void
_gst_clock_id_free (GstClockID id)
{
348
  GstClockEntry *entry;
349 350 351
  g_return_if_fail (id != NULL);

  GST_CAT_DEBUG (GST_CAT_CLOCK, "freed entry %p", id);
352 353 354
  entry = (GstClockEntry *) id;
  if (entry->destroy_data)
    entry->destroy_data (entry->user_data);
355

356 357
  /* FIXME: add tracer hook for struct allocations such as clock entries */

358
  g_slice_free (GstClockEntry, id);
359 360 361 362
}

/**
 * gst_clock_id_unref:
363
 * @id: (transfer full): The #GstClockID to unref
364
 *
Wim Taymans's avatar
Wim Taymans committed
365
 * Unref given @id. When the refcount reaches 0 the
366 367 368 369 370 371 372 373 374 375 376
 * #GstClockID will be freed.
 *
 * MT safe.
 */
void
gst_clock_id_unref (GstClockID id)
{
  gint zero;

  g_return_if_fail (id != NULL);

377
  zero = g_atomic_int_dec_and_test (&((GstClockEntry *) id)->refcount);
378 379 380 381 382 383
  /* if we ended up with the refcount at zero, free the id */
  if (zero) {
    _gst_clock_id_free (id);
  }
}

384
/**
385
 * gst_clock_new_single_shot_id:
Wim Taymans's avatar
Wim Taymans committed
386
 * @clock: The #GstClockID to get a single shot notification from
387 388
 * @time: the requested time
 *
Wim Taymans's avatar
Wim Taymans committed
389
 * Get a #GstClockID from @clock to trigger a single shot
390 391
 * notification at the requested time. The single shot id should be
 * unreffed after usage.
392
 *
393 394 395 396
 * Free-function: gst_clock_id_unref
 *
 * Returns: (transfer full): a #GstClockID that can be used to request the
 *     time notification.
397 398
 *
 * MT safe.
399 400
 */
GstClockID
401
gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time)
402
{
403 404
  g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);

405 406
  return gst_clock_entry_new (clock,
      time, GST_CLOCK_TIME_NONE, GST_CLOCK_ENTRY_SINGLE);
407 408 409
}

/**
410
 * gst_clock_new_periodic_id:
Wim Taymans's avatar
Wim Taymans committed
411
 * @clock: The #GstClockID to get a periodic notification id from
412 413 414
 * @start_time: the requested start time
 * @interval: the requested interval
 *
Wim Taymans's avatar
Wim Taymans committed
415
 * Get an ID from @clock to trigger a periodic notification.
416 417
 * The periodic notifications will start at time @start_time and
 * will then be fired with the given @interval. @id should be unreffed
418
 * after usage.
419
 *
420 421 422 423
 * Free-function: gst_clock_id_unref
 *
 * Returns: (transfer full): a #GstClockID that can be used to request the
 *     time notification.
424 425
 *
 * MT safe.
426 427
 */
GstClockID
428 429
gst_clock_new_periodic_id (GstClock * clock, GstClockTime start_time,
    GstClockTime interval)
430
{
431
  g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);
432
  g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (start_time), NULL);
433
  g_return_val_if_fail (interval != 0, NULL);
434
  g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (interval), NULL);
435

436 437
  return gst_clock_entry_new (clock,
      start_time, interval, GST_CLOCK_ENTRY_PERIODIC);
438 439
}

440
/**
441
 * gst_clock_id_compare_func:
Wim Taymans's avatar
Wim Taymans committed
442 443
 * @id1: A #GstClockID
 * @id2: A #GstClockID to compare with
444
 *
Wim Taymans's avatar
Wim Taymans committed
445
 * Compares the two #GstClockID instances. This function can be used
446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465
 * 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
466
  return 0;
467 468
}

469
/**
470
 * gst_clock_id_get_time:
Wim Taymans's avatar
Wim Taymans committed
471
 * @id: The #GstClockID to query
472 473 474
 *
 * Get the time of the clock ID
 *
475 476 477
 * Returns: the time of the given clock id.
 *
 * MT safe.
478 479 480 481 482 483
 */
GstClockTime
gst_clock_id_get_time (GstClockID id)
{
  g_return_val_if_fail (id != NULL, GST_CLOCK_TIME_NONE);

484
  return GST_CLOCK_ENTRY_TIME ((GstClockEntry *) id);
485 486 487
}

/**
488
 * gst_clock_id_wait:
Wim Taymans's avatar
Wim Taymans committed
489
 * @id: The #GstClockID to wait on
Wim Taymans's avatar
Wim Taymans committed
490
 * @jitter: (out) (allow-none): a pointer that will contain the jitter,
491
 *     can be %NULL.
Wim Taymans's avatar
Wim Taymans committed
492 493 494 495 496 497
 *
 * 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(). 
 *
498
 * If the @jitter argument is not %NULL and this function returns #GST_CLOCK_OK
Wim Taymans's avatar
Wim Taymans committed
499 500
 * or #GST_CLOCK_EARLY, it will contain the difference
 * against the clock and the time of @id when this method was
501 502
 * called. 
 * Positive values indicate how late @id was relative to the clock
503
 * (in which case this function will return #GST_CLOCK_EARLY). 
504
 * Negative values indicate how much time was spent waiting on the clock 
505
 * before this function returned.
Wim Taymans's avatar
Wim Taymans committed
506 507 508 509 510
 *
 * 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().
511 512
 *
 * MT safe.
513 514
 */
GstClockReturn
515
gst_clock_id_wait (GstClockID id, GstClockTimeDiff * jitter)
516 517
{
  GstClockEntry *entry;
518
  GstClock *clock;
519
  GstClockReturn res;
520
  GstClockTime requested;
Wim Taymans's avatar
Wim Taymans committed
521
  GstClockClass *cclass;
522

523
  g_return_val_if_fail (id != NULL, GST_CLOCK_ERROR);
524

525 526
  entry = (GstClockEntry *) id;
  requested = GST_CLOCK_ENTRY_TIME (entry);
527

528 529
  clock = GST_CLOCK_ENTRY_CLOCK (entry);

Wim Taymans's avatar
Wim Taymans committed
530
  /* can't sync on invalid times */
531 532 533
  if (G_UNLIKELY (!GST_CLOCK_TIME_IS_VALID (requested)))
    goto invalid_time;

Wim Taymans's avatar
Wim Taymans committed
534
  cclass = GST_CLOCK_GET_CLASS (clock);
535

Wim Taymans's avatar
Wim Taymans committed
536 537
  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "waiting on clock entry %p", id);

538
  /* if we have a wait_jitter function, use that */
Wim Taymans's avatar
Wim Taymans committed
539 540 541 542
  if (G_UNLIKELY (cclass->wait == NULL))
    goto not_supported;

  res = cclass->wait (clock, entry, jitter);
Wim Taymans's avatar
Wim Taymans committed
543 544

  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
545 546
      "done waiting entry %p, res: %d (%s)", id, res,
      gst_clock_return_get_name (res));
Wim Taymans's avatar
Wim Taymans committed
547

548 549
  if (entry->type == GST_CLOCK_ENTRY_PERIODIC)
    entry->time = requested + entry->interval;
Wim Taymans's avatar
Wim Taymans committed
550

551
  return res;
552 553 554 555

  /* ERRORS */
invalid_time:
  {
556 557
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "invalid time requested, returning _BADTIME");
558 559
    return GST_CLOCK_BADTIME;
  }
Wim Taymans's avatar
Wim Taymans committed
560 561 562 563 564
not_supported:
  {
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "clock wait is not supported");
    return GST_CLOCK_UNSUPPORTED;
  }
565 566 567
}

/**
Wim Taymans's avatar
Wim Taymans committed
568
 * gst_clock_id_wait_async:
Wim Taymans's avatar
Wim Taymans committed
569
 * @id: a #GstClockID to wait on
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
570
 * @func: The callback function
571
 * @user_data: User data passed in the callback
572
 * @destroy_data: #GDestroyNotify for user_data
573
 *
Wim Taymans's avatar
Wim Taymans committed
574 575
 * Register a callback on the given #GstClockID @id with the given
 * function and user_data. When passing a #GstClockID with an invalid
576
 * time to this function, the callback will be called immediately
577
 * with  a time set to GST_CLOCK_TIME_NONE. The callback will
Wim Taymans's avatar
Wim Taymans committed
578
 * be called when the time of @id has been reached.
579
 *
580 581 582
 * The callback @func can be invoked from any thread, either provided by the
 * core or from a streaming thread. The application should be prepared for this.
 *
583
 * Returns: the result of the non blocking wait.
584 585
 *
 * MT safe.
586 587
 */
GstClockReturn
Wim Taymans's avatar
Wim Taymans committed
588
gst_clock_id_wait_async (GstClockID id,
589
    GstClockCallback func, gpointer user_data, GDestroyNotify destroy_data)
590 591 592
{
  GstClockEntry *entry;
  GstClock *clock;
593
  GstClockReturn res;
Wim Taymans's avatar
Wim Taymans committed
594
  GstClockClass *cclass;
595
  GstClockTime requested;
596

597
  g_return_val_if_fail (id != NULL, GST_CLOCK_ERROR);
598
  g_return_val_if_fail (func != NULL, GST_CLOCK_ERROR);
599 600

  entry = (GstClockEntry *) id;
601 602
  requested = GST_CLOCK_ENTRY_TIME (entry);
  clock = GST_CLOCK_ENTRY_CLOCK (entry);
603

Wim Taymans's avatar
Wim Taymans committed
604
  /* can't sync on invalid times */
605 606 607
  if (G_UNLIKELY (!GST_CLOCK_TIME_IS_VALID (requested)))
    goto invalid_time;

Wim Taymans's avatar
Wim Taymans committed
608 609
  cclass = GST_CLOCK_GET_CLASS (clock);

Wim Taymans's avatar
Wim Taymans committed
610 611 612 613 614
  if (G_UNLIKELY (cclass->wait_async == NULL))
    goto not_supported;

  entry->func = func;
  entry->user_data = user_data;
615
  entry->destroy_data = destroy_data;
Wim Taymans's avatar
Wim Taymans committed
616 617

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

619 620
  return res;

621 622 623 624
  /* ERRORS */
invalid_time:
  {
    (func) (clock, GST_CLOCK_TIME_NONE, id, user_data);
625 626
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "invalid time requested, returning _BADTIME");
627 628
    return GST_CLOCK_BADTIME;
  }
Wim Taymans's avatar
Wim Taymans committed
629 630 631 632 633
not_supported:
  {
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "clock wait is not supported");
    return GST_CLOCK_UNSUPPORTED;
  }
634 635
}

636
/**
Wim Taymans's avatar
Wim Taymans committed
637 638
 * gst_clock_id_unschedule:
 * @id: The id to unschedule
639
 *
Wim Taymans's avatar
Wim Taymans committed
640
 * Cancel an outstanding request with @id. This can either
641
 * be an outstanding async notification or a pending sync notification.
Wim Taymans's avatar
Wim Taymans committed
642 643
 * After this call, @id cannot be used anymore to receive sync or
 * async notifications, you need to create a new #GstClockID.
644 645
 *
 * MT safe.
646 647 648 649 650 651
 */
void
gst_clock_id_unschedule (GstClockID id)
{
  GstClockEntry *entry;
  GstClock *clock;
Wim Taymans's avatar
Wim Taymans committed
652
  GstClockClass *cclass;
653

654 655 656 657
  g_return_if_fail (id != NULL);

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

Wim Taymans's avatar
Wim Taymans committed
659 660
  cclass = GST_CLOCK_GET_CLASS (clock);

Wim Taymans's avatar
Wim Taymans committed
661
  if (G_LIKELY (cclass->unschedule))
Wim Taymans's avatar
Wim Taymans committed
662
    cclass->unschedule (clock, entry);
663 664
}

665

Stefan Kost's avatar
Stefan Kost committed
666
/*
667 668
 * GstClock abstract base class implementation
 */
Wim Taymans's avatar
Wim Taymans committed
669
#define gst_clock_parent_class parent_class
Wim Taymans's avatar
Wim Taymans committed
670
G_DEFINE_ABSTRACT_TYPE (GstClock, gst_clock, GST_TYPE_OBJECT);
671

672
static void
673
gst_clock_class_init (GstClockClass * klass)
674
{
675
  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
676

677 678 679 680
  gobject_class->dispose = gst_clock_dispose;
  gobject_class->finalize = gst_clock_finalize;
  gobject_class->set_property = gst_clock_set_property;
  gobject_class->get_property = gst_clock_get_property;
681

682
  g_object_class_install_property (gobject_class, PROP_WINDOW_SIZE,
683 684
      g_param_spec_int ("window-size", "Window size",
          "The size of the window used to calculate rate and offset", 2, 1024,
685
          DEFAULT_WINDOW_SIZE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
686 687
  g_object_class_install_property (gobject_class, PROP_WINDOW_THRESHOLD,
      g_param_spec_int ("window-threshold", "Window threshold",
688
          "The threshold to start calculating rate and offset", 2, 1024,
689 690
          DEFAULT_WINDOW_THRESHOLD,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
691
  g_object_class_install_property (gobject_class, PROP_TIMEOUT,
692 693
      g_param_spec_uint64 ("timeout", "Timeout",
          "The amount of time, in nanoseconds, to sample master and slave clocks",
694 695
          0, G_MAXUINT64, DEFAULT_TIMEOUT,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
696

697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715
  /**
   * GstClock::synced:
   * @clock: the clock
   * @synced: if the clock is synced now
   *
   * Signaled on clocks with GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC set once
   * the clock is synchronized, or when it completely lost synchronization.
   * This signal will not be emitted on clocks without the flag.
   *
   * This signal will be emitted from an arbitrary thread, most likely not
   * the application's main thread.
   *
   * Since: 1.6
   */
  gst_clock_signals[SIGNAL_SYNCED] =
      g_signal_new ("synced", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
      0, NULL, NULL,
      g_cclosure_marshal_generic, G_TYPE_NONE, 1, G_TYPE_BOOLEAN);

716
  g_type_class_add_private (klass, sizeof (GstClockPrivate));
Wim Taymans's avatar
Wim Taymans committed
717 718
}

719
static void
720
gst_clock_init (GstClock * clock)
Wim Taymans's avatar
Wim Taymans committed
721
{
Wim Taymans's avatar
Wim Taymans committed
722
  GstClockPrivate *priv;
723

Wim Taymans's avatar
Wim Taymans committed
724
  clock->priv = priv =
725 726
      G_TYPE_INSTANCE_GET_PRIVATE (clock, GST_TYPE_CLOCK, GstClockPrivate);

Wim Taymans's avatar
Wim Taymans committed
727 728 729 730 731 732 733 734
  priv->last_time = 0;

  priv->internal_calibration = 0;
  priv->external_calibration = 0;
  priv->rate_numerator = 1;
  priv->rate_denominator = 1;

  g_mutex_init (&priv->slave_lock);
735
  g_cond_init (&priv->sync_cond);
Wim Taymans's avatar
Wim Taymans committed
736 737 738 739 740 741
  priv->window_size = DEFAULT_WINDOW_SIZE;
  priv->window_threshold = DEFAULT_WINDOW_THRESHOLD;
  priv->filling = TRUE;
  priv->time_index = 0;
  priv->timeout = DEFAULT_TIMEOUT;
  priv->times = g_new0 (GstClockTime, 4 * priv->window_size);
742
  priv->times_temp = priv->times + 2 * priv->window_size;
743 744 745

  /* clear floating flag */
  gst_object_ref_sink (clock);
Wim Taymans's avatar
Wim Taymans committed
746 747
}

748 749 750 751
static void
gst_clock_dispose (GObject * object)
{
  GstClock *clock = GST_CLOCK (object);
752
  GstClock **master_p;
753 754

  GST_OBJECT_LOCK (clock);
Wim Taymans's avatar
Wim Taymans committed
755
  master_p = &clock->priv->master;
756
  gst_object_replace ((GstObject **) master_p, NULL);
757 758 759 760 761
  GST_OBJECT_UNLOCK (clock);

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

Wim Taymans's avatar
Wim Taymans committed
762
static void
Wim Taymans's avatar
Wim Taymans committed
763
gst_clock_finalize (GObject * object)
Wim Taymans's avatar
Wim Taymans committed
764 765 766
{
  GstClock *clock = GST_CLOCK (object);

767
  GST_CLOCK_SLAVE_LOCK (clock);
Wim Taymans's avatar
Wim Taymans committed
768 769 770 771
  if (clock->priv->clockid) {
    gst_clock_id_unschedule (clock->priv->clockid);
    gst_clock_id_unref (clock->priv->clockid);
    clock->priv->clockid = NULL;
772
  }
Wim Taymans's avatar
Wim Taymans committed
773 774
  g_free (clock->priv->times);
  clock->priv->times = NULL;
775
  clock->priv->times_temp = NULL;
776
  GST_CLOCK_SLAVE_UNLOCK (clock);
777

Wim Taymans's avatar
Wim Taymans committed
778
  g_mutex_clear (&clock->priv->slave_lock);
779
  g_cond_clear (&clock->priv->sync_cond);
780

Wim Taymans's avatar
Wim Taymans committed
781
  G_OBJECT_CLASS (parent_class)->finalize (object);
Wim Taymans's avatar
Wim Taymans committed
782 783
}

Wim Taymans's avatar
Wim Taymans committed
784
/**
785
 * gst_clock_set_resolution:
786
 * @clock: a #GstClock
787
 * @resolution: The resolution to set
Wim Taymans's avatar
Wim Taymans committed
788
 *
789 790 791 792 793
 * Set the accuracy of the clock. Some clocks have the possibility to operate
 * with different accuracy at the expense of more resource usage. There is
 * normally no need to change the default resolution of a clock. The resolution
 * of a clock can only be changed if the clock has the
 * #GST_CLOCK_FLAG_CAN_SET_RESOLUTION flag set.
794 795
 *
 * Returns: the new resolution of the clock.
Wim Taymans's avatar
Wim Taymans committed
796
 */
797 798
GstClockTime
gst_clock_set_resolution (GstClock * clock, GstClockTime resolution)
Wim Taymans's avatar
Wim Taymans committed
799
{
Wim Taymans's avatar
Wim Taymans committed
800
  GstClockPrivate *priv;
Wim Taymans's avatar
Wim Taymans committed
801 802
  GstClockClass *cclass;

803 804
  g_return_val_if_fail (GST_IS_CLOCK (clock), 0);
  g_return_val_if_fail (resolution != 0, 0);
805

Wim Taymans's avatar
Wim Taymans committed
806
  cclass = GST_CLOCK_GET_CLASS (clock);
Wim Taymans's avatar
Wim Taymans committed
807
  priv = clock->priv;
Wim Taymans's avatar
Wim Taymans committed
808 809

  if (cclass->change_resolution)
Wim Taymans's avatar
Wim Taymans committed
810 811
    priv->resolution =
        cclass->change_resolution (clock, priv->resolution, resolution);
812

Wim Taymans's avatar
Wim Taymans committed
813
  return priv->resolution;
814
}
815

816
/**
817
 * gst_clock_get_resolution:
818
 * @clock: a #GstClock
819
 *
820 821
 * Get the accuracy of the clock. The accuracy of the clock is the granularity
 * of the values returned by gst_clock_get_time().
822
 *
823
 * Returns: the resolution of the clock in units of #GstClockTime.
824 825
 *
 * MT safe.
826
 */
827
GstClockTime
828
gst_clock_get_resolution (GstClock * clock)
829
{
Wim Taymans's avatar
Wim Taymans committed
830 831
  GstClockClass *cclass;

832
  g_return_val_if_fail (GST_IS_CLOCK (clock), 0);
833

Wim Taymans's avatar
Wim Taymans committed
834 835 836 837
  cclass = GST_CLOCK_GET_CLASS (clock);

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

839
  return 1;
Wim Taymans's avatar
Wim Taymans committed
840 841
}

842
/* FIXME 2.0: Remove clock parameter below */
Wim Taymans's avatar
Wim Taymans committed
843
/**
844
 * gst_clock_adjust_with_calibration:
845
 * @clock: (allow-none): a #GstClock to use
846 847 848 849 850 851 852 853 854 855 856 857
 * @internal_target: a clock time
 * @cinternal: a reference internal time
 * @cexternal: a reference external time
 * @cnum: the numerator of the rate of the clock relative to its
 *        internal time
 * @cdenom: the denominator of the rate of the clock
 *
 * Converts the given @internal_target clock time to the external time,
 * using the passed calibration parameters. This function performs the
 * same calculation as gst_clock_adjust_unlocked() when called using the
 * current calibration parameters, but doesn't ensure a monotonically
 * increasing result as gst_clock_adjust_unlocked() does.
858
 *
859 860
 * Note: The @clock parameter is unused and can be NULL
 *
861
 * Returns: the converted time of the clock.
862 863
 *
 * Since: 1.6
864
 */
865
GstClockTime
866 867 868
gst_clock_adjust_with_calibration (GstClock * clock,
    GstClockTime internal_target, GstClockTime cinternal,
    GstClockTime cexternal, GstClockTime cnum, GstClockTime cdenom)
869
{
870
  GstClockTime ret;
871 872

  /* avoid divide by 0 */
873
  if (G_UNLIKELY (cdenom == 0))
874 875 876 877 878
    cnum = cdenom = 1;

  /* The formula is (internal - cinternal) * cnum / cdenom + cexternal
   *
   * Since we do math on unsigned 64-bit ints we have to special case for
879
   * internal < cinternal to get the sign right. this case is not very common,
880 881
   * though.
   */
882 883
  if (G_LIKELY (internal_target >= cinternal)) {
    ret = internal_target - cinternal;
884
    ret = gst_util_uint64_scale (ret, cnum, cdenom);
885 886
    ret += cexternal;
  } else {
887
    ret = cinternal - internal_target;
888
    ret = gst_util_uint64_scale (ret, cnum, cdenom);
889
    /* clamp to 0 */
890
    if (G_LIKELY (cexternal > ret))