Merge branch '0.10'
[platform/upstream/gstreamer.git] / gst / gsttask.h
1 /* GStreamer
2  * Copyright (C) <1999> Erik Walthinsen <omega@cse.ogi.edu>
3  *               <2005> Wim Taymans <wim@fluendo.com>
4  *
5  * gsttask.h: Streaming tasks
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Library General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Library General Public License for more details.
16  *
17  * You should have received a copy of the GNU Library General Public
18  * License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20  * Boston, MA 02111-1307, USA.
21  */
22
23 #ifndef __GST_TASK_H__
24 #define __GST_TASK_H__
25
26 #include <gst/gstobject.h>
27 #include <gst/gsttaskpool.h>
28
29 G_BEGIN_DECLS
30
31 /**
32  * GstTaskFunction:
33  * @data: user data passed to the function
34  *
35  * A function that will repeatedly be called in the thread created by
36  * a #GstTask.
37  */
38 typedef void         (*GstTaskFunction)          (void *data);
39
40 /* --- standard type macros --- */
41 #define GST_TYPE_TASK                   (gst_task_get_type ())
42 #define GST_TASK(task)                  (G_TYPE_CHECK_INSTANCE_CAST ((task), GST_TYPE_TASK, GstTask))
43 #define GST_IS_TASK(task)               (G_TYPE_CHECK_INSTANCE_TYPE ((task), GST_TYPE_TASK))
44 #define GST_TASK_CLASS(tclass)          (G_TYPE_CHECK_CLASS_CAST ((tclass), GST_TYPE_TASK, GstTaskClass))
45 #define GST_IS_TASK_CLASS(tclass)       (G_TYPE_CHECK_CLASS_TYPE ((tclass), GST_TYPE_TASK))
46 #define GST_TASK_GET_CLASS(task)        (G_TYPE_INSTANCE_GET_CLASS ((task), GST_TYPE_TASK, GstTaskClass))
47 #define GST_TASK_CAST(task)             ((GstTask*)(task))
48
49 typedef struct _GstTask GstTask;
50 typedef struct _GstTaskClass GstTaskClass;
51 typedef struct _GstTaskPrivate GstTaskPrivate;
52
53 /**
54  * GstTaskState:
55  * @GST_TASK_STARTED: the task is started and running
56  * @GST_TASK_STOPPED: the task is stopped
57  * @GST_TASK_PAUSED: the task is paused
58  *
59  * The different states a task can be in
60  */
61 typedef enum {
62   GST_TASK_STARTED,
63   GST_TASK_STOPPED,
64   GST_TASK_PAUSED
65 } GstTaskState;
66
67 /**
68  * GST_TASK_STATE:
69  * @task: Task to get the state of
70  *
71  * Get access to the state of the task.
72  */
73 #define GST_TASK_STATE(task)            (GST_TASK_CAST(task)->state)
74
75 /**
76  * GST_TASK_GET_COND:
77  * @task: Task to get the cond of
78  *
79  * Get access to the cond of the task.
80  */
81 #define GST_TASK_GET_COND(task)         (&GST_TASK_CAST(task)->cond)
82 /**
83  * GST_TASK_WAIT:
84  * @task: Task to wait for
85  *
86  * Wait for the task cond to be signalled
87  */
88 #define GST_TASK_WAIT(task)             g_cond_wait(GST_TASK_GET_COND (task), GST_OBJECT_GET_LOCK (task))
89 /**
90  * GST_TASK_SIGNAL:
91  * @task: Task to signal
92  *
93  * Signal the task cond
94  */
95 #define GST_TASK_SIGNAL(task)           g_cond_signal(GST_TASK_GET_COND (task))
96 /**
97  * GST_TASK_BROADCAST:
98  * @task: Task to broadcast
99  *
100  * Send a broadcast signal to all waiting task conds
101  */
102 #define GST_TASK_BROADCAST(task)        g_cond_broadcast(GST_TASK_GET_COND (task))
103
104 /**
105  * GST_TASK_GET_LOCK:
106  * @task: Task to get the lock of
107  *
108  * Get access to the task lock.
109  */
110 #define GST_TASK_GET_LOCK(task)         (GST_TASK_CAST(task)->lock)
111
112 /**
113  * GstTaskThreadCallbacks:
114  * @enter_thread: a thread is entered, this callback is called when the new
115  *   thread enters its function.
116  * @leave_thread: a thread is exiting, this is called when the thread is about
117  *   to leave its function
118  *
119  * Custom GstTask thread callback functions that can be installed.
120  *
121  * Since: 0.10.24
122  */
123 typedef struct {
124   /* manage the lifetime of the thread */
125   void      (*enter_thread)     (GstTask *task, GThread *thread, gpointer user_data);
126   void      (*leave_thread)     (GstTask *task, GThread *thread, gpointer user_data);
127   /*< private >*/
128   gpointer     _gst_reserved[GST_PADDING];
129 } GstTaskThreadCallbacks;
130
131 /**
132  * GstTask:
133  * @state: the state of the task
134  * @cond: used to pause/resume the task
135  * @lock: The lock taken when iterating the task function
136  * @func: the function executed by this task
137  * @data: data passed to the task function
138  * @running: a flag indicating that the task is running
139  *
140  * The #GstTask object.
141  */
142 struct _GstTask {
143   GstObject      object;
144
145   /*< public >*/ /* with LOCK */
146   GstTaskState     state;
147   GCond            cond;
148
149   GRecMutex       *lock;
150
151   GstTaskFunction  func;
152   gpointer         data;
153
154   gboolean         running;
155
156   /*< private >*/
157   GThread         *thread;
158
159   GstTaskPrivate  *priv;
160
161   gpointer _gst_reserved[GST_PADDING];
162 };
163
164 struct _GstTaskClass {
165   GstObjectClass parent_class;
166
167   /*< private >*/
168   GstTaskPool *pool;
169
170   /*< private >*/
171   gpointer _gst_reserved[GST_PADDING];
172 };
173
174 void            gst_task_cleanup_all    (void);
175
176 GType           gst_task_get_type       (void);
177
178 GstTask*        gst_task_new            (GstTaskFunction func, gpointer data);
179 void            gst_task_set_lock       (GstTask *task, GRecMutex *mutex);
180 void            gst_task_set_priority   (GstTask *task, GThreadPriority priority);
181
182 GstTaskPool *   gst_task_get_pool       (GstTask *task);
183 void            gst_task_set_pool       (GstTask *task, GstTaskPool *pool);
184
185 void            gst_task_set_thread_callbacks  (GstTask *task,
186                                                 GstTaskThreadCallbacks *callbacks,
187                                                 gpointer user_data,
188                                                 GDestroyNotify notify);
189
190 GstTaskState    gst_task_get_state      (GstTask *task);
191 gboolean        gst_task_set_state      (GstTask *task, GstTaskState state);
192
193 gboolean        gst_task_start          (GstTask *task);
194 gboolean        gst_task_stop           (GstTask *task);
195 gboolean        gst_task_pause          (GstTask *task);
196
197 gboolean        gst_task_join           (GstTask *task);
198
199 G_END_DECLS
200
201 #endif /* __GST_TASK_H__ */