1 /*
2    (c) Copyright 2001-2009  The world wide DirectFB Open Source Community (directfb.org)
3    (c) Copyright 2000-2004  Convergence (integrated media) GmbH
4 
5    All rights reserved.
6 
7    Written by Denis Oliver Kropp <dok@directfb.org>,
8               Andreas Hundt <andi@fischlustig.de>,
9               Sven Neumann <neo@directfb.org>,
10               Ville Syrjälä <syrjala@sci.fi> and
11               Claudio Ciccani <klan@users.sf.net>.
12 
13    This library is free software; you can redistribute it and/or
14    modify it under the terms of the GNU Lesser General Public
15    License as published by the Free Software Foundation; either
16    version 2 of the License, or (at your option) any later version.
17 
18    This library is distributed in the hope that it will be useful,
19    but WITHOUT ANY WARRANTY; without even the implied warranty of
20    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
21    Lesser General Public License for more details.
22 
23    You should have received a copy of the GNU Lesser General Public
24    License along with this library; if not, write to the
25    Free Software Foundation, Inc., 59 Temple Place - Suite 330,
26    Boston, MA 02111-1307, USA.
27 */
28 
29 #ifndef __DIRECT__THREAD_H__
30 #define __DIRECT__THREAD_H__
31 
32 #include <sys/types.h>
33 
34 #include <direct/types.h>
35 #include <direct/conf.h>
36 #include <direct/mutex.h>
37 
38 typedef enum {
39      DTT_DEFAULT    =   0,
40      DTT_CLEANUP    =  -5,
41      DTT_INPUT      = -10,
42      DTT_OUTPUT     = -12,
43      DTT_MESSAGING  = -15,
44      DTT_CRITICAL   = -20
45 } DirectThreadType;
46 
47 typedef void * (*DirectThreadMainFunc)( DirectThread *thread, void *arg );
48 
49 typedef void   (*DirectThreadInitFunc)( DirectThread *thread, void *arg );
50 
51 
52 /*
53  * Add a handler being called at the beginning of new threads.
54  */
55 DirectThreadInitHandler *direct_thread_add_init_handler   ( DirectThreadInitFunc     func,
56                                                             void                    *arg );
57 
58 /*
59  * Remove the specified handler.
60  */
61 void                     direct_thread_remove_init_handler( DirectThreadInitHandler *handler );
62 
63 /*
64  * Create a new thread and start it.
65  * The thread type is relevant for the scheduling priority.
66  */
67 DirectThread *direct_thread_create     ( DirectThreadType      thread_type,
68                                          DirectThreadMainFunc  thread_main,
69                                          void                 *arg,
70                                          const char           *name );
71 
72 /*
73  * Returns the thread of the caller.
74  */
75 DirectThread *direct_thread_self       ( void );
76 
77 /*
78  * Returns the name of the specified thread.
79  */
80 const char   *direct_thread_get_name   ( DirectThread *thread );
81 
82 /*
83  * Returns the thread ID of the specified thread.
84  */
85 pid_t         direct_thread_get_tid    ( DirectThread *thread );
86 
87 /*
88  * Returns the name of the calling thread.
89  */
90 const char   *direct_thread_self_name  ( void );
91 
92 /*
93  * Changes the name of the calling thread.
94  */
95 void          direct_thread_set_name   ( const char   *name );
96 
97 /*
98  * Wait on the thread object to be notified via direct_thread_notify().
99  */
100 DirectResult  direct_thread_wait       ( DirectThread *thread,
101                                          int           timeout_ms );
102 
103 /*
104  * Notify the thread object waking up callers of direct_thread_wait().
105  */
106 void direct_thread_notify     ( DirectThread *thread );
107 
108 void direct_thread_lock       ( DirectThread *thread );
109 void direct_thread_unlock     ( DirectThread *thread );
110 
111 /*
112  * Kindly ask the thread to terminate (for joining without thread cancellation).
113  */
114 void direct_thread_terminate  ( DirectThread *thread );
115 
116 /*
117  * Cancel a running thread.
118  */
119 void direct_thread_cancel     ( DirectThread *thread );
120 
121 /*
122  * Returns true if the specified thread has been canceled.
123  */
124 bool direct_thread_is_canceled( DirectThread *thread );
125 
126 /*
127  * Detach a thread.
128  */
129 void direct_thread_detach     ( DirectThread *thread );
130 
131 /*
132  * Returns true if the specified thread has been detached.
133  */
134 bool direct_thread_is_detached( DirectThread *thread );
135 
136 /*
137  * Check if the calling thread is canceled.
138  * Must not be called by other threads than 'thread'.
139  * This function won't return if the thread is canceled.
140  */
141 void direct_thread_testcancel ( DirectThread *thread );
142 
143 /*
144  * Wait until a running thread is terminated.
145  */
146 void direct_thread_join       ( DirectThread *thread );
147 
148 /*
149  * Returns true if the specified thread has been join.
150  */
151 bool direct_thread_is_joined  ( DirectThread *thread );
152 
153 /*
154  * Free resources allocated by direct_thread_create.
155  * If the thread is still running it will be killed.
156  */
157 void direct_thread_destroy    ( DirectThread *thread );
158 
159 /*
160  * Utilities for stringification.
161  */
162 #if DIRECT_BUILD_TEXT
163 const char *direct_thread_type_name     ( DirectThreadType type );
164 const char *direct_thread_scheduler_name( DirectConfigThreadScheduler scheduler );
165 const char *direct_thread_policy_name   ( int policy );
166 #endif
167 
168 #endif
169 
170