gstclock.c 42.3 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
 * 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.
Wim Taymans's avatar
Wim Taymans committed
101
 *
102
 * Last reviewed on 2009-05-21 (0.10.24)
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 137 138 139 140 141 142
struct _GstClockPrivate
{
  gint pre_count;
  gint post_count;
};

/* seqlocks */
#define read_seqbegin(clock)                                   \
143
  g_atomic_int_get (&clock->ABI.priv->post_count);
144 145 146 147 148

static inline gboolean
read_seqretry (GstClock * clock, gint seq)
{
  /* no retry if the seqnum did not change */
149
  if (G_LIKELY (seq == g_atomic_int_get (&clock->ABI.priv->pre_count)))
150 151 152 153 154 155 156 157 158 159 160
    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);                        \
161
  g_atomic_int_inc (&clock->ABI.priv->pre_count);     \
162 163 164 165
} G_STMT_END;

#define write_sequnlock(clock)                    \
G_STMT_START {                                    \
166
  g_atomic_int_inc (&clock->ABI.priv->post_count);    \
167 168 169
  GST_OBJECT_UNLOCK (clock);                      \
} G_STMT_END;

170
static void gst_clock_dispose (GObject * object);
Wim Taymans's avatar
Wim Taymans committed
171
static void gst_clock_finalize (GObject * object);
Wim Taymans's avatar
Wim Taymans committed
172

173 174 175 176 177
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);
178

179

180
static GstObjectClass *parent_class = NULL;
181

182 183
/* static guint gst_clock_signals[LAST_SIGNAL] = { 0 }; */

Wim Taymans's avatar
Wim Taymans committed
184
static GstClockID
185 186
gst_clock_entry_new (GstClock * clock, GstClockTime time,
    GstClockTime interval, GstClockEntryType type)
187 188
{
  GstClockEntry *entry;
189

190
  entry = g_slice_new (GstClockEntry);
Wim Taymans's avatar
Wim Taymans committed
191
#ifndef GST_DISABLE_TRACE
Wim Taymans's avatar
Wim Taymans committed
192
  gst_alloc_trace_new (_gst_clock_entry_trace, entry);
Wim Taymans's avatar
Wim Taymans committed
193
#endif
194 195
  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
      "created entry %p, time %" GST_TIME_FORMAT, entry, GST_TIME_ARGS (time));
196

197
  entry->refcount = 1;
198
  entry->clock = clock;
199
  entry->type = type;
200
  entry->time = time;
201
  entry->interval = interval;
202
  entry->status = GST_CLOCK_OK;
203 204
  entry->func = NULL;
  entry->user_data = NULL;
205
  entry->destroy_data = NULL;
206

207 208
  return (GstClockID) entry;
}
209

210 211
/**
 * gst_clock_id_ref:
Wim Taymans's avatar
Wim Taymans committed
212
 * @id: The #GstClockID to ref
213
 *
Wim Taymans's avatar
Wim Taymans committed
214
 * Increase the refcount of given @id.
215 216 217 218 219 220 221 222 223 224
 *
 * Returns: The same #GstClockID with increased refcount.
 *
 * MT safe.
 */
GstClockID
gst_clock_id_ref (GstClockID id)
{
  g_return_val_if_fail (id != NULL, NULL);

225
  g_atomic_int_inc (&((GstClockEntry *) id)->refcount);
226 227 228 229 230 231 232

  return id;
}

static void
_gst_clock_id_free (GstClockID id)
{
233
  GstClockEntry *entry;
234 235 236
  g_return_if_fail (id != NULL);

  GST_CAT_DEBUG (GST_CAT_CLOCK, "freed entry %p", id);
237 238 239
  entry = (GstClockEntry *) id;
  if (entry->destroy_data)
    entry->destroy_data (entry->user_data);
240 241 242 243

#ifndef GST_DISABLE_TRACE
  gst_alloc_trace_free (_gst_clock_entry_trace, id);
#endif
244
  g_slice_free (GstClockEntry, id);
245 246 247 248
}

/**
 * gst_clock_id_unref:
Wim Taymans's avatar
Wim Taymans committed
249
 * @id: The #GstClockID to unref
250
 *
Wim Taymans's avatar
Wim Taymans committed
251
 * Unref given @id. When the refcount reaches 0 the
252 253 254 255 256 257 258 259 260 261 262
 * #GstClockID will be freed.
 *
 * MT safe.
 */
void
gst_clock_id_unref (GstClockID id)
{
  gint zero;

  g_return_if_fail (id != NULL);

263
  zero = g_atomic_int_dec_and_test (&((GstClockEntry *) id)->refcount);
264 265 266 267 268 269
  /* if we ended up with the refcount at zero, free the id */
  if (zero) {
    _gst_clock_id_free (id);
  }
}

270 271
/**
 * gst_clock_new_single_shot_id
Wim Taymans's avatar
Wim Taymans committed
272
 * @clock: The #GstClockID to get a single shot notification from
273 274
 * @time: the requested time
 *
Wim Taymans's avatar
Wim Taymans committed
275
 * Get a #GstClockID from @clock to trigger a single shot
276 277
 * notification at the requested time. The single shot id should be
 * unreffed after usage.
278
 *
Wim Taymans's avatar
Wim Taymans committed
279
 * Returns: A #GstClockID that can be used to request the time notification.
280 281
 *
 * MT safe.
282 283
 */
GstClockID
284
gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time)
285
{
286 287
  g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);

288 289
  return gst_clock_entry_new (clock,
      time, GST_CLOCK_TIME_NONE, GST_CLOCK_ENTRY_SINGLE);
290 291 292
}

/**
Wim Taymans's avatar
Wim Taymans committed
293
 * gst_clock_new_periodic_id
Wim Taymans's avatar
Wim Taymans committed
294
 * @clock: The #GstClockID to get a periodic notification id from
295 296 297
 * @start_time: the requested start time
 * @interval: the requested interval
 *
Wim Taymans's avatar
Wim Taymans committed
298
 * Get an ID from @clock to trigger a periodic notification.
299 300
 * The periodic notifications will start at time @start_time and
 * will then be fired with the given @interval. @id should be unreffed
301
 * after usage.
302
 *
Wim Taymans's avatar
Wim Taymans committed
303
 * Returns: A #GstClockID that can be used to request the time notification.
304 305
 *
 * MT safe.
306 307
 */
GstClockID
308 309
gst_clock_new_periodic_id (GstClock * clock, GstClockTime start_time,
    GstClockTime interval)
310
{
311
  g_return_val_if_fail (GST_IS_CLOCK (clock), NULL);
312
  g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (start_time), NULL);
313
  g_return_val_if_fail (interval != 0, NULL);
314
  g_return_val_if_fail (GST_CLOCK_TIME_IS_VALID (interval), NULL);
315

316 317
  return gst_clock_entry_new (clock,
      start_time, interval, GST_CLOCK_ENTRY_PERIODIC);
318 319
}

320 321
/**
 * gst_clock_id_compare_func
Wim Taymans's avatar
Wim Taymans committed
322 323
 * @id1: A #GstClockID
 * @id2: A #GstClockID to compare with
324
 *
Wim Taymans's avatar
Wim Taymans committed
325
 * Compares the two #GstClockID instances. This function can be used
326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345
 * 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
346
  return 0;
347 348
}

349 350
/**
 * gst_clock_id_get_time
Wim Taymans's avatar
Wim Taymans committed
351
 * @id: The #GstClockID to query
352 353 354
 *
 * Get the time of the clock ID
 *
355 356 357
 * Returns: the time of the given clock id.
 *
 * MT safe.
358 359 360 361 362 363
 */
GstClockTime
gst_clock_id_get_time (GstClockID id)
{
  g_return_val_if_fail (id != NULL, GST_CLOCK_TIME_NONE);

364
  return GST_CLOCK_ENTRY_TIME ((GstClockEntry *) id);
365 366 367 368
}

/**
 * gst_clock_id_wait
Wim Taymans's avatar
Wim Taymans committed
369
 * @id: The #GstClockID to wait on
370
 * @jitter: A pointer that will contain the jitter, can be %NULL.
Wim Taymans's avatar
Wim Taymans committed
371 372 373 374 375 376
 *
 * 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(). 
 *
377
 * If the @jitter argument is not %NULL and this function returns #GST_CLOCK_OK
Wim Taymans's avatar
Wim Taymans committed
378 379
 * or #GST_CLOCK_EARLY, it will contain the difference
 * against the clock and the time of @id when this method was
380 381
 * called. 
 * Positive values indicate how late @id was relative to the clock
382
 * (in which case this function will return #GST_CLOCK_EARLY). 
383
 * Negative values indicate how much time was spent waiting on the clock 
384
 * before this function returned.
Wim Taymans's avatar
Wim Taymans committed
385 386 387 388 389
 *
 * 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().
390 391
 *
 * MT safe.
392 393
 */
GstClockReturn
394
gst_clock_id_wait (GstClockID id, GstClockTimeDiff * jitter)
395 396
{
  GstClockEntry *entry;
397
  GstClock *clock;
398
  GstClockReturn res;
399
  GstClockTime requested;
Wim Taymans's avatar
Wim Taymans committed
400
  GstClockClass *cclass;
401

402
  g_return_val_if_fail (id != NULL, GST_CLOCK_ERROR);
403

404 405
  entry = (GstClockEntry *) id;
  requested = GST_CLOCK_ENTRY_TIME (entry);
406

407 408
  clock = GST_CLOCK_ENTRY_CLOCK (entry);

Wim Taymans's avatar
Wim Taymans committed
409
  /* can't sync on invalid times */
410 411 412
  if (G_UNLIKELY (!GST_CLOCK_TIME_IS_VALID (requested)))
    goto invalid_time;

Wim Taymans's avatar
Wim Taymans committed
413
  cclass = GST_CLOCK_GET_CLASS (clock);
414

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

417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436
  /* if we have a wait_jitter function, use that */
  if (G_LIKELY (cclass->wait_jitter)) {
    res = cclass->wait_jitter (clock, entry, jitter);
  } else {
    /* check if we have a simple _wait function otherwise. The function without
     * the jitter arg is less optimal as we need to do an additional _get_time()
     * which is not atomic with the _wait() and a typical _wait() function does
     * yet another _get_time() anyway. */
    if (G_UNLIKELY (cclass->wait == NULL))
      goto not_supported;

    if (jitter) {
      GstClockTime now = gst_clock_get_time (clock);

      /* jitter is the diff against the clock when this entry is scheduled. Negative
       * values mean that the entry was in time, a positive value means that the
       * entry was too late. */
      *jitter = GST_CLOCK_DIFF (requested, now);
    }
    res = cclass->wait (clock, entry);
Wim Taymans's avatar
Wim Taymans committed
437 438 439 440 441
  }

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

442 443
  if (entry->type == GST_CLOCK_ENTRY_PERIODIC)
    entry->time = requested + entry->interval;
Wim Taymans's avatar
Wim Taymans committed
444

445
  if (G_UNLIKELY (clock->stats))
Wim Taymans's avatar
Wim Taymans committed
446 447
    gst_clock_update_stats (clock);

448
  return res;
449 450 451 452

  /* ERRORS */
invalid_time:
  {
453 454
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "invalid time requested, returning _BADTIME");
455 456
    return GST_CLOCK_BADTIME;
  }
Wim Taymans's avatar
Wim Taymans committed
457 458 459 460 461
not_supported:
  {
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "clock wait is not supported");
    return GST_CLOCK_UNSUPPORTED;
  }
462 463 464
}

/**
465
 * gst_clock_id_wait_async_full:
Wim Taymans's avatar
Wim Taymans committed
466
 * @id: a #GstClockID to wait on
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
467
 * @func: The callback function
468
 * @user_data: User data passed in the callback
469
 * @destroy_data: #GDestroyNotify for user_data
470
 *
Wim Taymans's avatar
Wim Taymans committed
471 472
 * Register a callback on the given #GstClockID @id with the given
 * function and user_data. When passing a #GstClockID with an invalid
473
 * time to this function, the callback will be called immediately
474
 * with  a time set to GST_CLOCK_TIME_NONE. The callback will
Wim Taymans's avatar
Wim Taymans committed
475
 * be called when the time of @id has been reached.
476
 *
477 478 479
 * 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.
 *
480
 * Returns: the result of the non blocking wait.
481 482
 *
 * MT safe.
483 484
 *
 * Since: 0.10.30
485 486
 */
GstClockReturn
487 488
gst_clock_id_wait_async_full (GstClockID id,
    GstClockCallback func, gpointer user_data, GDestroyNotify destroy_data)
489 490 491
{
  GstClockEntry *entry;
  GstClock *clock;
492
  GstClockReturn res;
Wim Taymans's avatar
Wim Taymans committed
493
  GstClockClass *cclass;
494
  GstClockTime requested;
495

496
  g_return_val_if_fail (id != NULL, GST_CLOCK_ERROR);
497
  g_return_val_if_fail (func != NULL, GST_CLOCK_ERROR);
498 499

  entry = (GstClockEntry *) id;
500 501
  requested = GST_CLOCK_ENTRY_TIME (entry);
  clock = GST_CLOCK_ENTRY_CLOCK (entry);
502

Wim Taymans's avatar
Wim Taymans committed
503
  /* can't sync on invalid times */
504 505 506
  if (G_UNLIKELY (!GST_CLOCK_TIME_IS_VALID (requested)))
    goto invalid_time;

Wim Taymans's avatar
Wim Taymans committed
507 508
  cclass = GST_CLOCK_GET_CLASS (clock);

Wim Taymans's avatar
Wim Taymans committed
509 510 511 512 513
  if (G_UNLIKELY (cclass->wait_async == NULL))
    goto not_supported;

  entry->func = func;
  entry->user_data = user_data;
514
  entry->destroy_data = destroy_data;
Wim Taymans's avatar
Wim Taymans committed
515 516

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

518 519
  return res;

520 521 522 523
  /* ERRORS */
invalid_time:
  {
    (func) (clock, GST_CLOCK_TIME_NONE, id, user_data);
524 525
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "invalid time requested, returning _BADTIME");
526 527
    return GST_CLOCK_BADTIME;
  }
Wim Taymans's avatar
Wim Taymans committed
528 529 530 531 532
not_supported:
  {
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "clock wait is not supported");
    return GST_CLOCK_UNSUPPORTED;
  }
533 534
}

535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560
/**
 * gst_clock_id_wait_async:
 * @id: a #GstClockID to wait on
 * @func: The callback function
 * @user_data: User data passed in the callback
 *
 * Register a callback on the given #GstClockID @id with the given
 * function and user_data. When passing a #GstClockID with an invalid
 * time to this function, the callback will be called immediately
 * with  a time set to GST_CLOCK_TIME_NONE. The callback will
 * be called when the time of @id has been reached.
 *
 * 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.
 *
 * Returns: the result of the non blocking wait.
 *
 * MT safe.
 */
GstClockReturn
gst_clock_id_wait_async (GstClockID id,
    GstClockCallback func, gpointer user_data)
{
  return gst_clock_id_wait_async_full (id, func, user_data, NULL);
}

561
/**
Wim Taymans's avatar
Wim Taymans committed
562 563
 * gst_clock_id_unschedule:
 * @id: The id to unschedule
564
 *
Wim Taymans's avatar
Wim Taymans committed
565
 * Cancel an outstanding request with @id. This can either
566
 * be an outstanding async notification or a pending sync notification.
Wim Taymans's avatar
Wim Taymans committed
567 568
 * After this call, @id cannot be used anymore to receive sync or
 * async notifications, you need to create a new #GstClockID.
569 570
 *
 * MT safe.
571 572 573 574 575 576
 */
void
gst_clock_id_unschedule (GstClockID id)
{
  GstClockEntry *entry;
  GstClock *clock;
Wim Taymans's avatar
Wim Taymans committed
577
  GstClockClass *cclass;
578

579 580 581 582
  g_return_if_fail (id != NULL);

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

Wim Taymans's avatar
Wim Taymans committed
584 585
  cclass = GST_CLOCK_GET_CLASS (clock);

Wim Taymans's avatar
Wim Taymans committed
586
  if (G_LIKELY (cclass->unschedule))
Wim Taymans's avatar
Wim Taymans committed
587
    cclass->unschedule (clock, entry);
588 589
}

590

Stefan Kost's avatar
Stefan Kost committed
591
/*
592 593
 * GstClock abstract base class implementation
 */
594
G_DEFINE_TYPE (GstClock, gst_clock, GST_TYPE_OBJECT);
595

596
static void
597
gst_clock_class_init (GstClockClass * klass)
598
{
599
  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
600

601
  parent_class = g_type_class_peek_parent (klass);
602

Wim Taymans's avatar
Wim Taymans committed
603
#ifndef GST_DISABLE_TRACE
604 605
  _gst_clock_entry_trace =
      gst_alloc_trace_register (GST_CLOCK_ENTRY_TRACE_NAME);
Wim Taymans's avatar
Wim Taymans committed
606
#endif
607

608 609 610 611
  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;
612

613
  g_object_class_install_property (gobject_class, PROP_STATS,
614 615
      g_param_spec_boolean ("stats", "Stats",
          "Enable clock stats (unimplemented)", DEFAULT_STATS,
616
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
617
  g_object_class_install_property (gobject_class, PROP_WINDOW_SIZE,
618 619
      g_param_spec_int ("window-size", "Window size",
          "The size of the window used to calculate rate and offset", 2, 1024,
620
          DEFAULT_WINDOW_SIZE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
621 622
  g_object_class_install_property (gobject_class, PROP_WINDOW_THRESHOLD,
      g_param_spec_int ("window-threshold", "Window threshold",
623
          "The threshold to start calculating rate and offset", 2, 1024,
624 625
          DEFAULT_WINDOW_THRESHOLD,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
626
  g_object_class_install_property (gobject_class, PROP_TIMEOUT,
627 628
      g_param_spec_uint64 ("timeout", "Timeout",
          "The amount of time, in nanoseconds, to sample master and slave clocks",
629 630
          0, G_MAXUINT64, DEFAULT_TIMEOUT,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
631 632

  g_type_class_add_private (klass, sizeof (GstClockPrivate));
Wim Taymans's avatar
Wim Taymans committed
633 634
}

635
static void
636
gst_clock_init (GstClock * clock)
Wim Taymans's avatar
Wim Taymans committed
637
{
638 639
  clock->last_time = 0;
  clock->entries = NULL;
640
  clock->entries_changed = g_cond_new ();
641
  clock->stats = FALSE;
642

643
  clock->ABI.priv =
644 645
      G_TYPE_INSTANCE_GET_PRIVATE (clock, GST_TYPE_CLOCK, GstClockPrivate);

646 647
  clock->internal_calibration = 0;
  clock->external_calibration = 0;
648 649 650 651
  clock->rate_numerator = 1;
  clock->rate_denominator = 1;

  clock->slave_lock = g_mutex_new ();
652 653
  clock->window_size = DEFAULT_WINDOW_SIZE;
  clock->window_threshold = DEFAULT_WINDOW_THRESHOLD;
Wim Taymans's avatar
Wim Taymans committed
654
  clock->filling = TRUE;
655 656 657
  clock->time_index = 0;
  clock->timeout = DEFAULT_TIMEOUT;
  clock->times = g_new0 (GstClockTime, 4 * clock->window_size);
Wim Taymans's avatar
Wim Taymans committed
658 659
}

660 661 662 663
static void
gst_clock_dispose (GObject * object)
{
  GstClock *clock = GST_CLOCK (object);
664
  GstClock **master_p;
665 666

  GST_OBJECT_LOCK (clock);
667 668
  master_p = &clock->master;
  gst_object_replace ((GstObject **) master_p, NULL);
669 670 671 672 673
  GST_OBJECT_UNLOCK (clock);

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

Wim Taymans's avatar
Wim Taymans committed
674
static void
Wim Taymans's avatar
Wim Taymans committed
675
gst_clock_finalize (GObject * object)
Wim Taymans's avatar
Wim Taymans committed
676 677 678
{
  GstClock *clock = GST_CLOCK (object);

679
  GST_CLOCK_SLAVE_LOCK (clock);
680 681 682 683 684 685 686
  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;
687
  GST_CLOCK_SLAVE_UNLOCK (clock);
688

689
  g_cond_free (clock->entries_changed);
690 691
  g_mutex_free (clock->slave_lock);

Wim Taymans's avatar
Wim Taymans committed
692
  G_OBJECT_CLASS (parent_class)->finalize (object);
Wim Taymans's avatar
Wim Taymans committed
693 694
}

Wim Taymans's avatar
Wim Taymans committed
695
/**
696
 * gst_clock_set_resolution
697
 * @clock: a #GstClock
698
 * @resolution: The resolution to set
Wim Taymans's avatar
Wim Taymans committed
699
 *
700 701 702 703 704
 * 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.
705 706
 *
 * Returns: the new resolution of the clock.
Wim Taymans's avatar
Wim Taymans committed
707
 */
708 709
GstClockTime
gst_clock_set_resolution (GstClock * clock, GstClockTime resolution)
Wim Taymans's avatar
Wim Taymans committed
710
{
Wim Taymans's avatar
Wim Taymans committed
711 712
  GstClockClass *cclass;

713 714
  g_return_val_if_fail (GST_IS_CLOCK (clock), 0);
  g_return_val_if_fail (resolution != 0, 0);
715

Wim Taymans's avatar
Wim Taymans committed
716 717 718
  cclass = GST_CLOCK_GET_CLASS (clock);

  if (cclass->change_resolution)
719
    clock->resolution =
720
        cclass->change_resolution (clock, clock->resolution, resolution);
721

722 723
  return clock->resolution;
}
724

725 726
/**
 * gst_clock_get_resolution
727
 * @clock: a #GstClock
728
 *
729 730
 * Get the accuracy of the clock. The accuracy of the clock is the granularity
 * of the values returned by gst_clock_get_time().
731
 *
732
 * Returns: the resolution of the clock in units of #GstClockTime.
733 734
 *
 * MT safe.
735
 */
736
GstClockTime
737
gst_clock_get_resolution (GstClock * clock)
738
{
Wim Taymans's avatar
Wim Taymans committed
739 740
  GstClockClass *cclass;

741
  g_return_val_if_fail (GST_IS_CLOCK (clock), 0);
742

Wim Taymans's avatar
Wim Taymans committed
743 744 745 746
  cclass = GST_CLOCK_GET_CLASS (clock);

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

748
  return 1;
Wim Taymans's avatar
Wim Taymans committed
749 750
}

Wim Taymans's avatar
Wim Taymans committed
751
/**
752 753 754
 * gst_clock_adjust_unlocked
 * @clock: a #GstClock to use
 * @internal: a clock time
Wim Taymans's avatar
Wim Taymans committed
755
 *
756
 * Converts the given @internal clock time to the external time, adjusting for the
757 758
 * 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
759
 * clock's OBJECT_LOCK held and is mainly used by clock subclasses.
Wim Taymans's avatar
Wim Taymans committed
760
 *
761
 * This function is the reverse of gst_clock_unadjust_unlocked().
762
 *
763
 * Returns: the converted time of the clock.
764
 */
765 766
GstClockTime
gst_clock_adjust_unlocked (GstClock * clock, GstClockTime internal)
767
{
768 769 770 771 772 773 774 775 776
  GstClockTime ret, cinternal, cexternal, cnum, cdenom;

  /* get calibration values for readability */
  cinternal = clock->internal_calibration;
  cexternal = clock->external_calibration;
  cnum = clock->rate_numerator;
  cdenom = clock->rate_denominator;

  /* avoid divide by 0 */
777
  if (G_UNLIKELY (cdenom == 0))
778 779 780 781 782
    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
783
   * internal < cinternal to get the sign right. this case is not very common,
784 785 786
   * though.
   */
  if (G_LIKELY (internal >= cinternal)) {
787 788
    ret = internal - cinternal;
    ret = gst_util_uint64_scale (ret, cnum, cdenom);
789 790
    ret += cexternal;
  } else {
791 792
    ret = cinternal - internal;
    ret = gst_util_uint64_scale (ret, cnum, cdenom);
793
    /* clamp to 0 */
794
    if (G_LIKELY (cexternal > ret))
795 796 797 798
      ret = cexternal - ret;
    else
      ret = 0;
  }
799 800 801 802 803

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

  return clock->last_time;
804 805
}

806 807 808 809 810 811 812 813 814 815
/**
 * gst_clock_unadjust_unlocked
 * @clock: a #GstClock to use
 * @external: an external clock time
 *
 * Converts the given @external clock time to the internal time of @clock,
 * using the rate and reference time set with gst_clock_set_calibration().
 * This function should be called with the clock's OBJECT_LOCK held and
 * is mainly used by clock subclasses.
 *
816
 * This function is the reverse of gst_clock_adjust_unlocked().
817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833
 *
 * Returns: the internal time of the clock corresponding to @external.
 *
 * Since: 0.10.13
 */
GstClockTime
gst_clock_unadjust_unlocked (GstClock * clock, GstClockTime external)
{
  GstClockTime ret, cinternal, cexternal, cnum, cdenom;

  /* get calibration values for readability */
  cinternal = clock->internal_calibration;
  cexternal = clock->external_calibration;
  cnum = clock->rate_numerator;
  cdenom = clock->rate_denominator;

  /* avoid divide by 0 */
834
  if (G_UNLIKELY (cnum == 0))
835 836 837
    cnum = cdenom = 1;

  /* The formula is (external - cexternal) * cdenom / cnum + cinternal */
838 839 840
  if (G_LIKELY (external >= cexternal)) {
    ret = external - cexternal;
    ret = gst_util_uint64_scale (ret, cdenom, cnum);
841 842
    ret += cinternal;
  } else {
843 844 845
    ret = cexternal - external;
    ret = gst_util_uint64_scale (ret, cdenom, cnum);
    if (G_LIKELY (cinternal > ret))
846 847 848 849 850 851 852
      ret = cinternal - ret;
    else
      ret = 0;
  }
  return ret;
}

Wim Taymans's avatar
Wim Taymans committed
853
/**
854
 * gst_clock_get_internal_time
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
855
 * @clock: a #GstClock to query
Wim Taymans's avatar
Wim Taymans committed
856
 *
857 858
 * Gets the current internal time of the given clock. The time is returned
 * unadjusted for the offset and the rate.
859
 *
860
 * Returns: the internal time of the clock. Or GST_CLOCK_TIME_NONE when
861
 * given invalid input.
862 863
 *
 * MT safe.
Wim Taymans's avatar
Wim Taymans committed
864
 */
865
GstClockTime
866
gst_clock_get_internal_time (GstClock * clock)
867
{
868
  GstClockTime ret;
869
  GstClockClass *cclass;
870

871
  g_return_val_if_fail (GST_IS_CLOCK (clock), GST_CLOCK_TIME_NONE);
872

873
  cclass = GST_CLOCK_GET_CLASS (clock);
Wim Taymans's avatar
Wim Taymans committed
874

Wim Taymans's avatar
Wim Taymans committed
875 876 877 878 879
  if (G_UNLIKELY (cclass->get_internal_time == NULL))
    goto not_supported;

  ret = cclass->get_internal_time (clock);

880
  GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock, "internal time %" GST_TIME_FORMAT,
881
      GST_TIME_ARGS (ret));
882

883
  return ret;
Wim Taymans's avatar
Wim Taymans committed
884 885 886 887 888 889 890 891

  /* ERRORS */
not_supported:
  {
    GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, clock,
        "internal time not supported, return 0");
    return G_GINT64_CONSTANT (0);
  }
892 893 894 895 896 897 898 899 900 901 902
}

/**
 * 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
903
 * given invalid input.
904 905 906 907 908 909 910
 *
 * MT safe.
 */
GstClockTime
gst_clock_get_time (GstClock * clock)
{
  GstClockTime ret;
911
  gint seq;
912 913 914

  g_return_val_if_fail (GST_IS_CLOCK (clock), GST_CLOCK_TIME_NONE);

915 916 917 918
  do {
    /* reget the internal time when we retry to get the most current
     * timevalue */
    ret = gst_clock_get_internal_time (clock);