Max 5 API Reference
00001 #ifndef _EXT_SYSTHREAD_H_ 00002 #define _EXT_SYSTHREAD_H_ 00003 00004 #ifdef __cplusplus 00005 extern "C" { 00006 #endif 00007 00008 /** An opaque thread instance pointer. 00009 @ingroup threading 00010 */ 00011 typedef void *t_systhread; 00012 00013 00014 /** An opaque mutex handle. 00015 @ingroup threading 00016 */ 00017 typedef void *t_systhread_mutex; 00018 00019 00020 /** An opaque cond handle. 00021 @ingroup threading 00022 */ 00023 typedef void *t_systhread_cond; 00024 00025 00026 /** systhread_mutex_new() flags 00027 @ingroup threading 00028 */ 00029 typedef enum { 00030 SYSTHREAD_MUTEX_NORMAL = 0x00000000, ///< Normal 00031 SYSTHREAD_MUTEX_ERRORCHECK = 0x00000001, ///< Error-checking 00032 SYSTHREAD_MUTEX_RECURSIVE = 0x00000002 ///< Recursive 00033 } e_max_systhread_mutex_flags; 00034 00035 00036 /** 00037 Create a new thread. 00038 @ingroup threading 00039 00040 @param entryproc A method to call in the new thread when the thread is created. 00041 @param arg An argument to pass to the method specified for entryproc. 00042 Typically this might be a pointer to your object's struct. 00043 @param stacksize Not used. Pass 0 for this argument. 00044 @param priority Not used. Pass 0 for this argument. 00045 @param flags Not used. Pass 0 for this argument. 00046 @param thread The address of a #t_systhread where this thread's instance pointer will be stored. 00047 @return A Max error code as defined in #e_max_errorcodes. 00048 */ 00049 long systhread_create(method entryproc, void *arg, long stacksize, long priority, long flags, t_systhread *thread); 00050 00051 00052 /** 00053 Forcefully kill a thread -- not recommended. 00054 @ingroup threading 00055 00056 @param thread The thread to kill. 00057 @return A Max error code as defined in #e_max_errorcodes. 00058 */ 00059 long systhread_terminate(t_systhread thread); 00060 00061 00062 /** 00063 Suspend the execution of the calling thread. 00064 @ingroup threading 00065 00066 @param milliseconds The number of milliseconds to suspend the execution of the calling thread. 00067 The actual amount of time may be longer depending on various factors. 00068 */ 00069 void systhread_sleep(long milliseconds); 00070 00071 00072 /** 00073 Exit the calling thread. 00074 Call this from within a thread made using systhread_create() when the thread is no longer needed. 00075 00076 @ingroup threading 00077 @param status You will typically pass 0 for status. 00078 This value will be accessible by systhread_join(), if needed. 00079 */ 00080 void systhread_exit(long status); 00081 00082 00083 /** 00084 Wait for thread to quit and get return value from systhread_exit(). 00085 00086 @ingroup threading 00087 @param thread The thread to join. 00088 @param retval The address of a long to hold the return value (status) from systhread_exit(). 00089 @return A Max error code as defined in #e_max_errorcodes. 00090 00091 @remark If your object is freed, and your thread function accesses memory from your object, 00092 then you will obviously have a memory violation. 00093 A common use of systhread_join() is to prevent this situation by waiting (in your free method) 00094 for the thread to exit. 00095 */ 00096 long systhread_join(t_systhread thread, unsigned int* retval); // 00097 00098 00099 /** 00100 Return the thread instance pointer for the calling thread. 00101 @ingroup threading 00102 @return The thread instance pointer for the thread from which this function is called. 00103 */ 00104 t_systhread systhread_self(void); 00105 00106 00107 char *systhread_getstackbase(void); 00108 00109 00110 // private 00111 void systhread_init(void); 00112 void systhread_mainstacksetup(void); 00113 void systhread_timerstacksetup(void); 00114 short systhread_stackcheck(void); 00115 00116 00117 /** Check to see if the function currently being executed is in the main thread. 00118 @ingroup threading 00119 @return Returns true if the function is being executed in the main thread, otherwise false. 00120 */ 00121 short systhread_ismainthread(void); 00122 00123 00124 /** Check to see if the function currently being executed is in the scheduler thread. 00125 @ingroup threading 00126 @return Returns true if the function is being executed in the main thread, otherwise false. 00127 */ 00128 short systhread_istimerthread(void); 00129 00130 00131 00132 00133 /** 00134 Create a new mutex, which can be used to place thread locks around critical code. 00135 The mutex should be freed with systhread_mutex_free(). 00136 @ingroup mutex 00137 00138 @param pmutex The address of a variable to store the mutex pointer. 00139 @param flags Flags to determine the behaviour of the mutex, as defined in #e_max_systhread_mutex_flags. 00140 @return A Max error code as defined in #e_max_errorcodes. 00141 00142 @remark One reason to use systhread_mutex_new() instead of @ref critical is to 00143 create non-recursive locks, which are lighter-weight than recursive locks. 00144 */ 00145 long systhread_mutex_new(t_systhread_mutex *pmutex,long flags); 00146 00147 00148 /** 00149 Free a mutex created with systhread_mutex_new(). 00150 @ingroup mutex 00151 @param pmutex The mutex instance pointer. 00152 @return A Max error code as defined in #e_max_errorcodes. 00153 */ 00154 long systhread_mutex_free(t_systhread_mutex pmutex); 00155 00156 00157 /** 00158 Enter block of locked code code until a systhread_mutex_unlock() is reached. 00159 It is important to keep the code in this block as small as possible. 00160 @ingroup mutex 00161 @param pmutex The mutex instance pointer. 00162 @return A Max error code as defined in #e_max_errorcodes. 00163 @see systhread_mutex_trylock() 00164 */ 00165 long systhread_mutex_lock(t_systhread_mutex pmutex); 00166 00167 00168 /** 00169 Exit a block of code locked with systhread_mutex_lock(). 00170 @ingroup mutex 00171 @param pmutex The mutex instance pointer. 00172 @return A Max error code as defined in #e_max_errorcodes. 00173 */ 00174 long systhread_mutex_unlock(t_systhread_mutex pmutex); 00175 00176 00177 /** 00178 Try to enter block of locked code code until a systhread_mutex_unlock() is reached. 00179 If the lock cannot be entered, this function will return non-zero. 00180 00181 @ingroup mutex 00182 @param pmutex The mutex instance pointer. 00183 @return Returns non-zero if there was a problem entering. 00184 @see systhread_mutex_lock() 00185 */ 00186 long systhread_mutex_trylock(t_systhread_mutex pmutex); 00187 00188 00189 /** 00190 Convenience utility that combines systhread_mutex_new() and systhread_mutex_lock(). 00191 @ingroup mutex 00192 @param pmutex The address of a variable to store the mutex pointer. 00193 @param flags Flags to determine the behaviour of the mutex, as defined in #e_max_systhread_mutex_flags. 00194 @return A Max error code as defined in #e_max_errorcodes. 00195 */ 00196 long systhread_mutex_newlock(t_systhread_mutex *pmutex,long flags); 00197 00198 00199 00200 long systhread_cond_new(t_systhread_cond *pcond, long flags); 00201 long systhread_cond_free(t_systhread_cond pcond); 00202 long systhread_cond_wait(t_systhread_cond pcond, t_systhread_mutex pmutex); 00203 long systhread_cond_signal(t_systhread_cond pcond); 00204 long systhread_cond_broadcast(t_systhread_cond pcond); 00205 00206 00207 #ifdef __cplusplus 00208 } 00209 #endif 00210 00211 #endif // _EXT_SYSTHREAD_H_ 00212
Copyright © 2008, Cycling '74