1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
// 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 {}

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Task>> Sealed for T {}
}

/// Trait containing all [`struct@Task`] methods.
///
/// # Implementors
///
/// [`Task`][struct@crate::Task]
pub trait TaskExt: IsA<Task> + sealed::Sealed + '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 {}