1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gstreamer.Task; 26 27 private import glib.ConstructionException; 28 private import glib.RecMutex; 29 private import gobject.ObjectG; 30 private import gstreamer.ObjectGst; 31 private import gstreamer.TaskPool; 32 private import gstreamer.c.functions; 33 public import gstreamer.c.types; 34 35 36 /** 37 * #GstTask is used by #GstElement and #GstPad to provide the data passing 38 * threads in a #GstPipeline. 39 * 40 * A #GstPad will typically start a #GstTask to push or pull data to/from the 41 * peer pads. Most source elements start a #GstTask to push data. In some cases 42 * a demuxer element can start a #GstTask to pull data from a peer element. This 43 * is typically done when the demuxer can perform random access on the upstream 44 * peer element for improved performance. 45 * 46 * Although convenience functions exist on #GstPad to start/pause/stop tasks, it 47 * might sometimes be needed to create a #GstTask manually if it is not related to 48 * a #GstPad. 49 * 50 * Before the #GstTask can be run, it needs a #GRecMutex that can be set with 51 * gst_task_set_lock(). 52 * 53 * The task can be started, paused and stopped with gst_task_start(), gst_task_pause() 54 * and gst_task_stop() respectively or with the gst_task_set_state() function. 55 * 56 * A #GstTask will repeatedly call the #GstTaskFunction with the user data 57 * that was provided when creating the task with gst_task_new(). While calling 58 * the function it will acquire the provided lock. The provided lock is released 59 * when the task pauses or stops. 60 * 61 * Stopping a task with gst_task_stop() will not immediately make sure the task is 62 * not running anymore. Use gst_task_join() to make sure the task is completely 63 * stopped and the thread is stopped. 64 * 65 * After creating a #GstTask, use gst_object_unref() to free its resources. This can 66 * only be done when the task is not running anymore. 67 * 68 * Task functions can send a #GstMessage to send out-of-band data to the 69 * application. The application can receive messages from the #GstBus in its 70 * mainloop. 71 * 72 * For debugging purposes, the task will configure its object name as the thread 73 * name on Linux. Please note that the object name should be configured before the 74 * task is started; changing the object name after the task has been started, has 75 * no effect on the thread name. 76 */ 77 public class Task : ObjectGst 78 { 79 /** the main Gtk struct */ 80 protected GstTask* gstTask; 81 82 /** Get the main Gtk struct */ 83 public GstTask* getTaskStruct(bool transferOwnership = false) 84 { 85 if (transferOwnership) 86 ownedRef = false; 87 return gstTask; 88 } 89 90 /** the main Gtk struct as a void* */ 91 protected override void* getStruct() 92 { 93 return cast(void*)gstTask; 94 } 95 96 /** 97 * Sets our main struct and passes it to the parent class. 98 */ 99 public this (GstTask* gstTask, bool ownedRef = false) 100 { 101 this.gstTask = gstTask; 102 super(cast(GstObject*)gstTask, ownedRef); 103 } 104 105 106 /** */ 107 public static GType getType() 108 { 109 return gst_task_get_type(); 110 } 111 112 /** 113 * Create a new Task that will repeatedly call the provided @func 114 * with @user_data as a parameter. Typically the task will run in 115 * a new thread. 116 * 117 * The function cannot be changed after the task has been created. You 118 * must create a new #GstTask to change the function. 119 * 120 * This function will not yet create and start a thread. Use gst_task_start() or 121 * gst_task_pause() to create and start the GThread. 122 * 123 * Before the task can be used, a #GRecMutex must be configured using the 124 * gst_task_set_lock() function. This lock will always be acquired while 125 * @func is called. 126 * 127 * Params: 128 * func = The #GstTaskFunction to use 129 * userData = User data to pass to @func 130 * notify = the function to call when @user_data is no longer needed. 131 * 132 * Returns: A new #GstTask. 133 * 134 * MT safe. 135 * 136 * Throws: ConstructionException GTK+ fails to create the object. 137 */ 138 public this(GstTaskFunction func, void* userData, GDestroyNotify notify) 139 { 140 auto __p = gst_task_new(func, userData, notify); 141 142 if(__p is null) 143 { 144 throw new ConstructionException("null returned by new"); 145 } 146 147 this(cast(GstTask*) __p, true); 148 } 149 150 /** 151 * Wait for all tasks to be stopped. This is mainly used internally 152 * to ensure proper cleanup of internal data structures in test suites. 153 * 154 * MT safe. 155 */ 156 public static void cleanupAll() 157 { 158 gst_task_cleanup_all(); 159 } 160 161 /** 162 * Get the #GstTaskPool that this task will use for its streaming 163 * threads. 164 * 165 * MT safe. 166 * 167 * Returns: the #GstTaskPool used by @task. gst_object_unref() 168 * after usage. 169 */ 170 public TaskPool getPool() 171 { 172 auto __p = gst_task_get_pool(gstTask); 173 174 if(__p is null) 175 { 176 return null; 177 } 178 179 return ObjectG.getDObject!(TaskPool)(cast(GstTaskPool*) __p, true); 180 } 181 182 /** 183 * Get the current state of the task. 184 * 185 * Returns: The #GstTaskState of the task 186 * 187 * MT safe. 188 */ 189 public GstTaskState getState() 190 { 191 return gst_task_get_state(gstTask); 192 } 193 194 /** 195 * Joins @task. After this call, it is safe to unref the task 196 * and clean up the lock set with gst_task_set_lock(). 197 * 198 * The task will automatically be stopped with this call. 199 * 200 * This function cannot be called from within a task function as this 201 * would cause a deadlock. The function will detect this and print a 202 * g_warning. 203 * 204 * Returns: %TRUE if the task could be joined. 205 * 206 * MT safe. 207 */ 208 public bool join() 209 { 210 return gst_task_join(gstTask) != 0; 211 } 212 213 /** 214 * Pauses @task. This method can also be called on a task in the 215 * stopped state, in which case a thread will be started and will remain 216 * in the paused state. This function does not wait for the task to complete 217 * the paused state. 218 * 219 * Returns: %TRUE if the task could be paused. 220 * 221 * MT safe. 222 */ 223 public bool pause() 224 { 225 return gst_task_pause(gstTask) != 0; 226 } 227 228 /** 229 * Resume @task in case it was paused. If the task was stopped, it will 230 * remain in that state and this function will return %FALSE. 231 * 232 * Returns: %TRUE if the task could be resumed. 233 * 234 * MT safe. 235 * 236 * Since: 1.18 237 */ 238 public bool resume() 239 { 240 return gst_task_resume(gstTask) != 0; 241 } 242 243 /** 244 * Call @enter_func when the task function of @task is entered. @user_data will 245 * be passed to @enter_func and @notify will be called when @user_data is no 246 * longer referenced. 247 * 248 * Params: 249 * enterFunc = a #GstTaskThreadFunc 250 * userData = user data passed to @enter_func 251 * notify = called when @user_data is no longer referenced 252 */ 253 public void setEnterCallback(GstTaskThreadFunc enterFunc, void* userData, GDestroyNotify notify) 254 { 255 gst_task_set_enter_callback(gstTask, enterFunc, userData, notify); 256 } 257 258 /** 259 * Call @leave_func when the task function of @task is left. @user_data will 260 * be passed to @leave_func and @notify will be called when @user_data is no 261 * longer referenced. 262 * 263 * Params: 264 * leaveFunc = a #GstTaskThreadFunc 265 * userData = user data passed to @leave_func 266 * notify = called when @user_data is no longer referenced 267 */ 268 public void setLeaveCallback(GstTaskThreadFunc leaveFunc, void* userData, GDestroyNotify notify) 269 { 270 gst_task_set_leave_callback(gstTask, leaveFunc, userData, notify); 271 } 272 273 /** 274 * Set the mutex used by the task. The mutex will be acquired before 275 * calling the #GstTaskFunction. 276 * 277 * This function has to be called before calling gst_task_pause() or 278 * gst_task_start(). 279 * 280 * MT safe. 281 * 282 * Params: 283 * mutex = The #GRecMutex to use 284 */ 285 public void setLock(RecMutex mutex) 286 { 287 gst_task_set_lock(gstTask, (mutex is null) ? null : mutex.getRecMutexStruct()); 288 } 289 290 /** 291 * Set @pool as the new GstTaskPool for @task. Any new streaming threads that 292 * will be created by @task will now use @pool. 293 * 294 * MT safe. 295 * 296 * Params: 297 * pool = a #GstTaskPool 298 */ 299 public void setPool(TaskPool pool) 300 { 301 gst_task_set_pool(gstTask, (pool is null) ? null : pool.getTaskPoolStruct()); 302 } 303 304 /** 305 * Sets the state of @task to @state. 306 * 307 * The @task must have a lock associated with it using 308 * gst_task_set_lock() when going to GST_TASK_STARTED or GST_TASK_PAUSED or 309 * this function will return %FALSE. 310 * 311 * MT safe. 312 * 313 * Params: 314 * state = the new task state 315 * 316 * Returns: %TRUE if the state could be changed. 317 */ 318 public bool setState(GstTaskState state) 319 { 320 return gst_task_set_state(gstTask, state) != 0; 321 } 322 323 /** 324 * Starts @task. The @task must have a lock associated with it using 325 * gst_task_set_lock() or this function will return %FALSE. 326 * 327 * Returns: %TRUE if the task could be started. 328 * 329 * MT safe. 330 */ 331 public bool start() 332 { 333 return gst_task_start(gstTask) != 0; 334 } 335 336 /** 337 * Stops @task. This method merely schedules the task to stop and 338 * will not wait for the task to have completely stopped. Use 339 * gst_task_join() to stop and wait for completion. 340 * 341 * Returns: %TRUE if the task could be stopped. 342 * 343 * MT safe. 344 */ 345 public bool stop() 346 { 347 return gst_task_stop(gstTask) != 0; 348 } 349 }