gstreamer/auto/

task.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, Object, TaskPool, TaskState};
use glib::{prelude::*, translate::*};

glib::wrapper! {
    /// [`Task`][crate::Task] is used by [`Element`][crate::Element] and [`Pad`][crate::Pad] to provide the data passing
    /// threads in a [`Pipeline`][crate::Pipeline].
    ///
    /// A [`Pad`][crate::Pad] will typically start a [`Task`][crate::Task] to push or pull data to/from the
    /// peer pads. Most source elements start a [`Task`][crate::Task] to push data. In some cases
    /// a demuxer element can start a [`Task`][crate::Task] to pull data from a peer element. This
    /// is typically done when the demuxer can perform random access on the upstream
    /// peer element for improved performance.
    ///
    /// Although convenience functions exist on [`Pad`][crate::Pad] to start/pause/stop tasks, it
    /// might sometimes be needed to create a [`Task`][crate::Task] manually if it is not related to
    /// a [`Pad`][crate::Pad].
    ///
    /// Before the [`Task`][crate::Task] can be run, it needs a `GRecMutex` that can be set with
    /// [`TaskExtManual::set_lock()`][crate::prelude::TaskExtManual::set_lock()].
    ///
    /// The task can be started, paused and stopped with [`TaskExt::start()`][crate::prelude::TaskExt::start()], [`TaskExt::pause()`][crate::prelude::TaskExt::pause()]
    /// and [`TaskExt::stop()`][crate::prelude::TaskExt::stop()] respectively or with the [`TaskExt::set_state()`][crate::prelude::TaskExt::set_state()] function.
    ///
    /// A [`Task`][crate::Task] will repeatedly call the `GstTaskFunction` with the user data
    /// that was provided when creating the task with [`new()`][Self::new()]. While calling
    /// the function it will acquire the provided lock. The provided lock is released
    /// when the task pauses or stops.
    ///
    /// Stopping a task with [`TaskExt::stop()`][crate::prelude::TaskExt::stop()] will not immediately make sure the task is
    /// not running anymore. Use [`TaskExt::join()`][crate::prelude::TaskExt::join()] to make sure the task is completely
    /// stopped and the thread is stopped.
    ///
    /// After creating a [`Task`][crate::Task], use `gst_object_unref()` to free its resources. This can
    /// only be done when the task is not running anymore.
    ///
    /// Task functions can send a [`Message`][crate::Message] to send out-of-band data to the
    /// application. The application can receive messages from the [`Bus`][crate::Bus] in its
    /// mainloop.
    ///
    /// For debugging purposes, the task will configure its object name as the thread
    /// name on Linux. Please note that the object name should be configured before the
    /// task is started; changing the object name after the task has been started, has
    /// no effect on the thread name.
    ///
    /// # Implements
    ///
    /// [`TaskExt`][trait@crate::prelude::TaskExt], [`GstObjectExt`][trait@crate::prelude::GstObjectExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GstTask")]
    pub struct Task(Object<ffi::GstTask, ffi::GstTaskClass>) @extends Object;

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

impl Task {
    pub const NONE: Option<&'static Task> = None;

    /// Wait for all tasks to be stopped. This is mainly used internally
    /// to ensure proper cleanup of internal data structures in test suites.
    ///
    /// MT safe.
    #[doc(alias = "gst_task_cleanup_all")]
    pub fn cleanup_all() {
        assert_initialized_main_thread!();
        unsafe {
            ffi::gst_task_cleanup_all();
        }
    }
}

unsafe impl Send for Task {}
unsafe impl Sync for Task {}

/// Trait containing all [`struct@Task`] methods.
///
/// # Implementors
///
/// [`Task`][struct@crate::Task]
pub trait TaskExt: IsA<Task> + 'static {
    /// Get the [`TaskPool`][crate::TaskPool] that this task will use for its streaming
    /// threads.
    ///
    /// MT safe.
    ///
    /// # Returns
    ///
    /// the [`TaskPool`][crate::TaskPool] used by `self`. `gst_object_unref()`
    /// after usage.
    #[doc(alias = "gst_task_get_pool")]
    #[doc(alias = "get_pool")]
    fn pool(&self) -> TaskPool {
        unsafe { from_glib_full(ffi::gst_task_get_pool(self.as_ref().to_glib_none().0)) }
    }

    /// Get the current state of the task.
    ///
    /// # Returns
    ///
    /// The [`TaskState`][crate::TaskState] of the task
    ///
    /// MT safe.
    #[doc(alias = "gst_task_get_state")]
    #[doc(alias = "get_state")]
    fn state(&self) -> TaskState {
        unsafe { from_glib(ffi::gst_task_get_state(self.as_ref().to_glib_none().0)) }
    }

    /// Joins `self`. After this call, it is safe to unref the task
    /// and clean up the lock set with [`TaskExtManual::set_lock()`][crate::prelude::TaskExtManual::set_lock()].
    ///
    /// The task will automatically be stopped with this call.
    ///
    /// This function cannot be called from within a task function as this
    /// would cause a deadlock. The function will detect this and print a
    /// g_warning.
    ///
    /// # Returns
    ///
    /// [`true`] if the task could be joined.
    ///
    /// MT safe.
    #[doc(alias = "gst_task_join")]
    fn join(&self) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_task_join(self.as_ref().to_glib_none().0),
                "Failed to join task"
            )
        }
    }

    /// Pauses `self`. This method can also be called on a task in the
    /// stopped state, in which case a thread will be started and will remain
    /// in the paused state. This function does not wait for the task to complete
    /// the paused state.
    ///
    /// # Returns
    ///
    /// [`true`] if the task could be paused.
    ///
    /// MT safe.
    #[doc(alias = "gst_task_pause")]
    fn pause(&self) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_task_pause(self.as_ref().to_glib_none().0),
                "Failed to pause task"
            )
        }
    }

    /// Resume `self` in case it was paused. If the task was stopped, it will
    /// remain in that state and this function will return [`false`].
    ///
    /// # Returns
    ///
    /// [`true`] if the task could be resumed.
    ///
    /// MT safe.
    #[cfg(feature = "v1_18")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v1_18")))]
    #[doc(alias = "gst_task_resume")]
    fn resume(&self) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_task_resume(self.as_ref().to_glib_none().0),
                "Failed to resume task"
            )
        }
    }

    /// Set `pool` as the new GstTaskPool for `self`. Any new streaming threads that
    /// will be created by `self` will now use `pool`.
    ///
    /// MT safe.
    /// ## `pool`
    /// a [`TaskPool`][crate::TaskPool]
    #[doc(alias = "gst_task_set_pool")]
    fn set_pool(&self, pool: &impl IsA<TaskPool>) {
        unsafe {
            ffi::gst_task_set_pool(
                self.as_ref().to_glib_none().0,
                pool.as_ref().to_glib_none().0,
            );
        }
    }

    /// Sets the state of `self` to `state`.
    ///
    /// The `self` must have a lock associated with it using
    /// [`TaskExtManual::set_lock()`][crate::prelude::TaskExtManual::set_lock()] when going to GST_TASK_STARTED or GST_TASK_PAUSED or
    /// this function will return [`false`].
    ///
    /// MT safe.
    /// ## `state`
    /// the new task state
    ///
    /// # Returns
    ///
    /// [`true`] if the state could be changed.
    #[doc(alias = "gst_task_set_state")]
    fn set_state(&self, state: TaskState) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_task_set_state(self.as_ref().to_glib_none().0, state.into_glib()),
                "Failed to set task state"
            )
        }
    }

    /// Starts `self`. The `self` must have a lock associated with it using
    /// [`TaskExtManual::set_lock()`][crate::prelude::TaskExtManual::set_lock()] or this function will return [`false`].
    ///
    /// # Returns
    ///
    /// [`true`] if the task could be started.
    ///
    /// MT safe.
    #[doc(alias = "gst_task_start")]
    fn start(&self) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_task_start(self.as_ref().to_glib_none().0),
                "Failed to start task"
            )
        }
    }

    /// Stops `self`. This method merely schedules the task to stop and
    /// will not wait for the task to have completely stopped. Use
    /// [`join()`][Self::join()] to stop and wait for completion.
    ///
    /// # Returns
    ///
    /// [`true`] if the task could be stopped.
    ///
    /// MT safe.
    #[doc(alias = "gst_task_stop")]
    fn stop(&self) -> Result<(), glib::error::BoolError> {
        unsafe {
            glib::result_from_gboolean!(
                ffi::gst_task_stop(self.as_ref().to_glib_none().0),
                "Failed to stop task"
            )
        }
    }
}

impl<O: IsA<Task>> TaskExt for O {}