gstreamer_check/auto/

test_clock.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// from gst-gir-files (https://gitlab.freedesktop.org/gstreamer/gir-files-rs.git)
// DO NOT EDIT

use crate::ffi;
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// GstTestClock is an implementation of [`gst::Clock`][crate::gst::Clock] which has different
    /// behaviour compared to [`gst::SystemClock`][crate::gst::SystemClock]. Time for [`gst::SystemClock`][crate::gst::SystemClock] advances
    /// according to the system time, while time for [`TestClock`][crate::TestClock] changes only
    /// when [`set_time()`][Self::set_time()] or [`advance_time()`][Self::advance_time()] are
    /// called. [`TestClock`][crate::TestClock] provides unit tests with the possibility to
    /// precisely advance the time in a deterministic manner, independent of the
    /// system time or any other external factors.
    ///
    /// ## Advancing the time of a [`TestClock`][crate::TestClock]
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///   #include <gst/gst.h>
    ///   #include <gst/check/gsttestclock.h>
    ///
    ///   GstClock *clock;
    ///   GstTestClock *test_clock;
    ///
    ///   clock = gst_test_clock_new ();
    ///   test_clock = GST_TEST_CLOCK (clock);
    ///   GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
    ///   gst_test_clock_advance_time ( test_clock, 1 * GST_SECOND);
    ///   GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
    ///   g_usleep (10 * G_USEC_PER_SEC);
    ///   GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
    ///   gst_test_clock_set_time (test_clock, 42 * GST_SECOND);
    ///   GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
    ///   ...
    /// ```
    ///
    /// [`gst::Clock`][crate::gst::Clock] allows for setting up single shot or periodic clock notifications
    /// as well as waiting for these notifications synchronously (using
    /// `gst_clock_id_wait()`) or asynchronously (using `gst_clock_id_wait_async()` or
    /// `gst_clock_id_wait_async()`). This is used by many GStreamer elements,
    /// among them `GstBaseSrc` and `GstBaseSink`.
    ///
    /// [`TestClock`][crate::TestClock] keeps track of these clock notifications. By calling
    /// [`wait_for_next_pending_id()`][Self::wait_for_next_pending_id()] or
    /// [`wait_for_multiple_pending_ids()`][Self::wait_for_multiple_pending_ids()] a unit tests may wait for the
    /// next one or several clock notifications to be requested. Additionally unit
    /// tests may release blocked waits in a controlled fashion by calling
    /// [`process_next_clock_id()`][Self::process_next_clock_id()]. This way a unit test can control the
    /// inaccuracy (jitter) of clock notifications, since the test can decide to
    /// release blocked waits when the clock time has advanced exactly to, or past,
    /// the requested clock notification time.
    ///
    /// There are also interfaces for determining if a notification belongs to a
    /// [`TestClock`][crate::TestClock] or not, as well as getting the number of requested clock
    /// notifications so far.
    ///
    /// N.B.: When a unit test waits for a certain amount of clock notifications to
    /// be requested in [`wait_for_next_pending_id()`][Self::wait_for_next_pending_id()] or
    /// [`wait_for_multiple_pending_ids()`][Self::wait_for_multiple_pending_ids()] then these functions may block
    /// for a long time. If they block forever then the expected clock notifications
    /// were never requested from [`TestClock`][crate::TestClock], and so the assumptions in the code
    /// of the unit test are wrong. The unit test case runner in gstcheck is
    /// expected to catch these cases either by the default test case timeout or the
    /// one set for the unit test by calling tcase_set_timeout\(\).
    ///
    /// The sample code below assumes that the element under test will delay a
    /// buffer pushed on the source pad by some latency until it arrives on the sink
    /// pad. Moreover it is assumed that the element will at some point call
    /// `gst_clock_id_wait()` to synchronously wait for a specific time. The first
    /// buffer sent will arrive exactly on time only delayed by the latency. The
    /// second buffer will arrive a little late (7ms) due to simulated jitter in the
    /// clock notification.
    ///
    /// ## Demonstration of how to work with clock notifications and [`TestClock`][crate::TestClock]
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///   #include <gst/gst.h>
    ///   #include <gst/check/gstcheck.h>
    ///   #include <gst/check/gsttestclock.h>
    ///
    ///   GstClockTime latency;
    ///   GstElement *element;
    ///   GstPad *srcpad;
    ///   GstClock *clock;
    ///   GstTestClock *test_clock;
    ///   GstBuffer buf;
    ///   GstClockID pending_id;
    ///   GstClockID processed_id;
    ///
    ///   latency = 42 * GST_MSECOND;
    ///   element = create_element (latency, ...);
    ///   srcpad = get_source_pad (element);
    ///
    ///   clock = gst_test_clock_new ();
    ///   test_clock = GST_TEST_CLOCK (clock);
    ///   gst_element_set_clock (element, clock);
    ///
    ///   GST_INFO ("Set time, create and push the first buffer\n");
    ///   gst_test_clock_set_time (test_clock, 0);
    ///   buf = create_test_buffer (gst_clock_get_time (clock), ...);
    ///   gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK);
    ///
    ///   GST_INFO ("Block until element is waiting for a clock notification\n");
    ///   gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id);
    ///   GST_INFO ("Advance to the requested time of the clock notification\n");
    ///   gst_test_clock_advance_time (test_clock, latency);
    ///   GST_INFO ("Release the next blocking wait and make sure it is the one from element\n");
    ///   processed_id = gst_test_clock_process_next_clock_id (test_clock);
    ///   g_assert (processed_id == pending_id);
    ///   g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK);
    ///   gst_clock_id_unref (pending_id);
    ///   gst_clock_id_unref (processed_id);
    ///
    ///   GST_INFO ("Validate that element produced an output buffer and check its timestamp\n");
    ///   g_assert_cmpint (get_number_of_output_buffer (...), ==, 1);
    ///   buf = get_buffer_pushed_by_element (element, ...);
    ///   g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==, latency);
    ///   gst_buffer_unref (buf);
    ///   GST_INFO ("Check that element does not wait for any clock notification\n");
    ///   g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
    ///
    ///   GST_INFO ("Set time, create and push the second buffer\n");
    ///   gst_test_clock_advance_time (test_clock, 10 * GST_SECOND);
    ///   buf = create_test_buffer (gst_clock_get_time (clock), ...);
    ///   gst_assert_cmpint (gst_pad_push (srcpad, buf), ==, GST_FLOW_OK);
    ///
    ///   GST_INFO ("Block until element is waiting for a new clock notification\n");
    ///   (gst_test_clock_wait_for_next_pending_id (test_clock, &pending_id);
    ///   GST_INFO ("Advance past 7ms beyond the requested time of the clock notification\n");
    ///   gst_test_clock_advance_time (test_clock, latency + 7 * GST_MSECOND);
    ///   GST_INFO ("Release the next blocking wait and make sure it is the one from element\n");
    ///   processed_id = gst_test_clock_process_next_clock_id (test_clock);
    ///   g_assert (processed_id == pending_id);
    ///   g_assert_cmpint (GST_CLOCK_ENTRY_STATUS (processed_id), ==, GST_CLOCK_OK);
    ///   gst_clock_id_unref (pending_id);
    ///   gst_clock_id_unref (processed_id);
    ///
    ///   GST_INFO ("Validate that element produced an output buffer and check its timestamp\n");
    ///   g_assert_cmpint (get_number_of_output_buffer (...), ==, 1);
    ///   buf = get_buffer_pushed_by_element (element, ...);
    ///   g_assert_cmpint (GST_BUFFER_TIMESTAMP (buf), ==,
    ///       10 * GST_SECOND + latency + 7 * GST_MSECOND);
    ///   gst_buffer_unref (buf);
    ///   GST_INFO ("Check that element does not wait for any clock notification\n");
    ///   g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
    ///   ...
    /// ```
    ///
    /// Since [`TestClock`][crate::TestClock] is only supposed to be used in unit tests it calls
    /// `g_assert()`, `g_assert_cmpint()` or `g_assert_cmpuint()` to validate all function
    /// arguments. This will highlight any issues with the unit test code itself.
    ///
    /// ## Properties
    ///
    ///
    /// #### `clock-type`
    ///  Readable | Writeable
    ///
    ///
    /// #### `start-time`
    ///  When a [`TestClock`][crate::TestClock] is constructed it will have a certain start time set.
    /// If the clock was created using [`TestClock::with_start_time()`][crate::TestClock::with_start_time()] then
    /// this property contains the value of the `start_time` argument. If
    /// [`TestClock::new()`][crate::TestClock::new()] was called the clock started at time zero, and thus
    /// this property contains the value 0.
    ///
    /// Readable | Writeable | Construct Only
    /// <details><summary><h4>Clock</h4></summary>
    ///
    ///
    /// #### `timeout`
    ///  Readable | Writeable
    ///
    ///
    /// #### `window-size`
    ///  Readable | Writeable
    ///
    ///
    /// #### `window-threshold`
    ///  Readable | Writeable
    /// </details>
    /// <details><summary><h4>Object</h4></summary>
    ///
    ///
    /// #### `name`
    ///  Readable | Writeable | Construct
    ///
    ///
    /// #### `parent`
    ///  The parent of the object. Please note, that when changing the 'parent'
    /// property, we don't emit [`notify`][struct@crate::glib::Object#notify] and [`deep-notify`][struct@crate::gst::Object#deep-notify]
    /// signals due to locking issues. In some cases one can use
    /// [`element-added`][struct@crate::gst::Bin#element-added] or [`element-removed`][struct@crate::gst::Bin#element-removed] signals on the parent to
    /// achieve a similar effect.
    ///
    /// Readable | Writeable
    /// </details>
    ///
    /// # Implements
    ///
    /// [`trait@gst::prelude::ClockExt`], [`trait@gst::prelude::ObjectExt`], [`trait@glib::ObjectExt`]
    #[doc(alias = "GstTestClock")]
    pub struct TestClock(Object<ffi::GstTestClock, ffi::GstTestClockClass>) @extends gst::Clock, gst::Object;

    match fn {
        type_ => || ffi::gst_test_clock_get_type(),
    }
}

impl TestClock {
    /// Creates a new test clock with its time set to zero.
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// a [`TestClock`][crate::TestClock] cast to [`gst::Clock`][crate::gst::Clock].
    #[doc(alias = "gst_test_clock_new")]
    pub fn new() -> TestClock {
        assert_initialized_main_thread!();
        unsafe { gst::Clock::from_glib_full(ffi::gst_test_clock_new()).unsafe_cast() }
    }

    /// Creates a new test clock with its time set to the specified time.
    ///
    /// MT safe.
    /// ## `start_time`
    /// a `GstClockTime` set to the desired start time of the clock.
    ///
    /// # Returns
    ///
    /// a [`TestClock`][crate::TestClock] cast to [`gst::Clock`][crate::gst::Clock].
    #[doc(alias = "gst_test_clock_new_with_start_time")]
    #[doc(alias = "new_with_start_time")]
    pub fn with_start_time(start_time: gst::ClockTime) -> TestClock {
        assert_initialized_main_thread!();
        unsafe {
            gst::Clock::from_glib_full(ffi::gst_test_clock_new_with_start_time(
                start_time.into_glib(),
            ))
            .unsafe_cast()
        }
    }

    /// Advances the time of the `self` by the amount given by `delta`. The
    /// time of `self` is monotonically increasing, therefore providing a
    /// `delta` which is negative or zero is a programming error.
    ///
    /// MT safe.
    /// ## `delta`
    /// a positive `GstClockTimeDiff` to be added to the time of the clock
    #[doc(alias = "gst_test_clock_advance_time")]
    pub fn advance_time(&self, delta: gst::ClockTimeDiff) {
        unsafe {
            ffi::gst_test_clock_advance_time(self.to_glib_none().0, delta);
        }
    }

    /// A "crank" consists of three steps:
    /// 1: Wait for a `GstClockID` to be registered with the [`TestClock`][crate::TestClock].
    /// 2: Advance the [`TestClock`][crate::TestClock] to the time the `GstClockID` is waiting, unless
    ///  the clock time is already passed the clock id (Since: 1.18).
    /// 3: Release the `GstClockID` wait.
    /// A "crank" can be though of as the notion of
    /// manually driving the clock forward to its next logical step.
    ///
    /// # Returns
    ///
    /// [`true`] if the crank was successful, [`false`] otherwise.
    ///
    /// MT safe.
    #[doc(alias = "gst_test_clock_crank")]
    pub fn crank(&self) -> bool {
        unsafe { from_glib(ffi::gst_test_clock_crank(self.to_glib_none().0)) }
    }

    /// Retrieve the requested time for the next pending clock notification.
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// a `GstClockTime` set to the time of the next pending clock
    /// notification. If no clock notifications have been requested
    /// `GST_CLOCK_TIME_NONE` will be returned.
    #[doc(alias = "gst_test_clock_get_next_entry_time")]
    #[doc(alias = "get_next_entry_time")]
    pub fn next_entry_time(&self) -> Option<gst::ClockTime> {
        unsafe {
            from_glib(ffi::gst_test_clock_get_next_entry_time(
                self.to_glib_none().0,
            ))
        }
    }

    /// Determine the number of pending clock notifications that have been
    /// requested from the `self`.
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// the number of pending clock notifications.
    #[doc(alias = "gst_test_clock_peek_id_count")]
    pub fn peek_id_count(&self) -> u32 {
        unsafe { ffi::gst_test_clock_peek_id_count(self.to_glib_none().0) }
    }

    /// Sets the time of `self` to the time given by `new_time`. The time of
    /// `self` is monotonically increasing, therefore providing a `new_time`
    /// which is earlier or equal to the time of the clock as given by
    /// [`ClockExtManual::time()`][crate::gst::prelude::ClockExtManual::time()] is a programming error.
    ///
    /// MT safe.
    /// ## `new_time`
    /// a `GstClockTime` later than that returned by [`ClockExtManual::time()`][crate::gst::prelude::ClockExtManual::time()]
    #[doc(alias = "gst_test_clock_set_time")]
    pub fn set_time(&self, new_time: gst::ClockTime) {
        unsafe {
            ffi::gst_test_clock_set_time(self.to_glib_none().0, new_time.into_glib());
        }
    }

    /// Blocks until at least `count` clock notifications have been requested from
    /// `self`. There is no timeout for this wait, see the main description of
    /// [`TestClock`][crate::TestClock].
    ///
    /// # Deprecated
    ///
    /// use [`wait_for_multiple_pending_ids()`][Self::wait_for_multiple_pending_ids()] instead.
    /// ## `count`
    /// the number of pending clock notifications to wait for
    #[doc(alias = "gst_test_clock_wait_for_pending_id_count")]
    pub fn wait_for_pending_id_count(&self, count: u32) {
        unsafe {
            ffi::gst_test_clock_wait_for_pending_id_count(self.to_glib_none().0, count);
        }
    }

    #[doc(alias = "clock-type")]
    pub fn clock_type(&self) -> gst::ClockType {
        ObjectExt::property(self, "clock-type")
    }

    #[doc(alias = "clock-type")]
    pub fn set_clock_type(&self, clock_type: gst::ClockType) {
        ObjectExt::set_property(self, "clock-type", clock_type)
    }

    /// When a [`TestClock`][crate::TestClock] is constructed it will have a certain start time set.
    /// If the clock was created using [`with_start_time()`][Self::with_start_time()] then
    /// this property contains the value of the `start_time` argument. If
    /// [`new()`][Self::new()] was called the clock started at time zero, and thus
    /// this property contains the value 0.
    #[doc(alias = "start-time")]
    pub fn start_time(&self) -> u64 {
        ObjectExt::property(self, "start-time")
    }

    //#[doc(alias = "gst_test_clock_id_list_get_latest_time")]
    //pub fn id_list_get_latest_time(pending_list: /*Unimplemented*/&[&gst::ClockID]) -> Option<gst::ClockTime> {
    //    unsafe { TODO: call ffi:gst_test_clock_id_list_get_latest_time() }
    //}

    #[doc(alias = "clock-type")]
    pub fn connect_clock_type_notify<F: Fn(&Self) + Send + Sync + 'static>(
        &self,
        f: F,
    ) -> SignalHandlerId {
        unsafe extern "C" fn notify_clock_type_trampoline<
            F: Fn(&TestClock) + Send + Sync + 'static,
        >(
            this: *mut ffi::GstTestClock,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(&from_glib_borrow(this))
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                c"notify::clock-type".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_clock_type_trampoline::<F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl Default for TestClock {
    fn default() -> Self {
        Self::new()
    }
}

unsafe impl Send for TestClock {}
unsafe impl Sync for TestClock {}