1 pthread.h

     1 /*

     2 * ==============================================================================

     3 *  Name        : pthread.h

     4 *  Part of     : pthread

     5 *  Interface   : POSIX, pthread

     6 *  Description : POSIX thread exported header file 

     7 *  Version     : 

     8 

     9 Copyright © 2005-2006 Nokia Corporation

    10 All rights reserved.

    11 * © Portions copyright (c) 2007 Symbian Software Ltd. All rights reserved.

    12 Redistribution and use in source and binary forms, with or without 

    13 modification, are permitted provided that the following conditions are met:

    14  * Redistributions of source code must retain the above copyright notice, this 

    15    list of conditions and the following disclaimer. 

    16  * Redistributions in binary form must reproduce the above copyright notice, 

    17    this list of conditions and the following disclaimer in the documentation 

    18    and/or other materials provided with the distribution. 

    19  * Neither the name of the <ORGANIZATION> nor the names of its contributors 

    20    may be used to endorse or promote products derived from this software 

    21    without specific prior written permission. 

    22    

    23 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 

    24 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 

    25 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 

    26 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE

    27 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 

    28 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 

    29 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 

    30 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

    31 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 

    32 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    33 * ==============================================================================

    34 */

    35 #ifndef  PTHREAD_H

    36 #define  PTHREAD_H

    37 

    38 #include <pthreadtypes.h>

    39 #include <sched.h>

    40 #include <e32def.h>

    41 #include <stddef.h>

    42 #include <time.h>

    43 #include <limits.h>

    44 #include <pthreadalias.h>

    45 

    46 #define POSIX_THREAD_DESTRUCTOR_ITERATIONS  4

    47 #define POSIX_THREAD_KEYS_MAX               128

    48 #define PTHREAD_STACK_MIN                   0x2000

    49 #define POSIX_THREAD_THREADS_MAX            64

    50 #define PTHREAD_THREADS_MAX                 1024

    51 #define POSIX_SEM_NSEMS_MAX                 256

    52 #define SEM_NSEMS_MAX                       1024

    53 #define _POSIX_SEM_VALUE_MAX                32767

    54 #define SEM_VALUE_MAX                       INT_MAX

    55 

    56 /* internal use*/

    57 typedef enum 

    58 {

    59     _ENeedsNormalInit =-3,

    60     _ENeedsRecursiveInit,

    61     _ENeedsErrorCheckInit,

    62     _EInitialized =1,

    63     _EDestroyed,

    64     _EInvalid,

    65 }_handle_state;

    66 

    67 enum _LockStatus

    68 {

    69     _ELockNotCreated,

    70     _ELockCreating,

    71     _ELockCreated,

    72 };

    73 

    74 enum _OnceStatus

    75 {

    76     _ENotDone,

    77     _EDoing,

    78     _EDone,

    79 };

    80 

    81 typedef int pthread_once_t;

    82 

    83 struct _pthread_mutex_t;

    84 typedef struct 

    85 {

    86     _handle_state  iState;

    87     struct _pthread_mutex_t* iPtr;

    88     int   iReentry;

    89 }pthread_mutex_t;

    90 

    91 typedef struct 

    92 {

    93     _handle_state iState;

    94     int iSharedType;

    95     int iMutexType;

    96 }pthread_mutexattr_t;

    97 

    98 

    99 struct _CondNode;

   100 struct _CondQueue

   101 {

   102   struct _CondNode*       iHead;

   103   struct _CondNode*       iTail;

   104   pthread_mutex_t iMutex;

   105 };

   106 

   107 typedef struct 

   108 {

   109   _handle_state    iState;

   110   struct _CondQueue       iQueue;

   111 }pthread_cond_t;

   112 

   113 typedef struct _pthread_condattr_t*   pthread_condattr_t;

   114 

   115 #define PTHREAD_ONCE_INIT _ENotDone

   116 

   117 #define PTHREAD_MUTEX_INITIALIZER { _ENeedsNormalInit, NULL,0 }

   118 #define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP { _ENeedsRecursiveInit, NULL, 0 }

   119 #define PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP { _ENeedsErrorCheckInit, NULL,0 }

   120 

   121 #define PTHREAD_COND_INITIALIZER { _ENeedsNormalInit, NULL,NULL }

   122 

   123 enum 

   124 { 

   125     PTHREAD_CREATE_JOINABLE = 0,  /* Default */ 

   126     PTHREAD_CREATE_DETACHED = 1

   127 };

   128 

   129 enum 

   130 { 

   131     PTHREAD_SCOPE_SYSTEM  = 1  /* Default */

   132 };

   133 

   134 enum 

   135 {  

   136     PTHREAD_CANCEL_ASYNCHRONOUS = 0,  

   137     PTHREAD_CANCEL_DEFERRED = 1  /* Default */

   138 };

   139 

   140 enum 

   141 {  

   142     PTHREAD_PROCESS_PRIVATE = 0,   

   143 };

   144 

   145 enum

   146 {

   147   PTHREAD_MUTEX_NORMAL,

   148   PTHREAD_MUTEX_RECURSIVE,

   149   PTHREAD_MUTEX_ERRORCHECK,

   150   PTHREAD_MUTEX_DEFAULT = PTHREAD_MUTEX_NORMAL

   151 };

   152 

   153 

   154 

   155 #ifdef __cplusplus

   156 extern "C"

   157 {

   158 #endif    /* __cplusplus */

   159 

   160 typedef void * (*thread_begin_routine)(void *);

   161 /*

   162 This function creates a thread, with attributes specified by attrib,

   163 within a process. If attrib is NULL, then default attributes will be used.

   164 On successful completion, pthread_create() will store the ID of the 

   165 created thread in the location referenced by threadhdl.

   166 */ 

   167 IMPORT_C extern int pthread_create(pthread_t *threadhdl, pthread_attr_t *attrib, 

   168                    thread_begin_routine begin_routine , void * param);  

   169 /*

   170 This function return the handle to current thread.

   171 */                    

   172 IMPORT_C extern pthread_t pthread_self ();

   173 

   174 /*

   175 Compare two thread handles

   176 */

   177 IMPORT_C extern int pthread_equal(pthread_t t1,pthread_t t2);

   178 /*

   179 Waiting for thread termination

   180 */

   181 IMPORT_C extern int pthread_join(pthread_t thHandle, void **retValPtr);

   182 /*

   183 detach from thread 

   184 */

   185 IMPORT_C extern int pthread_detach(pthread_t thrHandle);

   186 /*

   187 exit current thread

   188 */

   189 IMPORT_C extern void pthread_exit(void *retValPtr);

   190 /*

   191 Initialise the thread attributes

   192 */

   193 IMPORT_C int pthread_attr_init(pthread_attr_t *attrib);

   194 /*

   195 Destroy the thread attributes

   196 */

   197 IMPORT_C int pthread_attr_destroy(pthread_attr_t *attrib);

   198 /*

   199 Get the detach_state of the current thread

   200 */

   201 IMPORT_C int pthread_attr_getdetachstate(const pthread_attr_t *attrib,

   202                                          int *detState);

   203 /*

   204 Set the detach_state of the current thread

   205 */                                         

   206 IMPORT_C int pthread_attr_setdetachstate(pthread_attr_t *attrib, 

   207                                          int detState);                                         

   208 /*

   209 Get the stack size of the current thread

   210 */

   211 IMPORT_C int pthread_attr_getstacksize(const pthread_attr_t *attrib,

   212                                        size_t *stkSize);

   213 /*

   214 Set the stack size of the current thread

   215 */                                       

   216 IMPORT_C int pthread_attr_setstacksize(pthread_attr_t *attrib, 

   217                                        size_t stkSize);                                       

   218 

   219 /*

   220 This function ensures that a piece of initialization code is executed at most once. 

   221 The once_control argument must point to a static  variable statically initialized to PTHREAD_ONCE_INIT

   222 

   223 */

   224 typedef void (*thread_init_routine) (void);

   225 IMPORT_C extern int pthread_once (pthread_once_t * once_control, 

   226                                   thread_init_routine init_routine);

   227 

   228 /*

   229 extern int pthread_key_create (pthread_key_t * key, void (*destructor) (void *));

   230 extern int pthread_key_delete (pthread_key_t key);

   231 extern int pthread_setspecific (pthread_key_t key, const void *value);

   232 extern void* pthread_getspecific (pthread_key_t key);

   233 */

   234 

   235 /*

   236 This function initializes the mutex attribute object attr and fills it with default values for the attributes.

   237 */

   238 IMPORT_C extern int pthread_mutexattr_init (pthread_mutexattr_t * attr);

   239 

   240 /*

   241 This function destroys the mutex attribute object attr and marks it as a destroyed object.

   242 */

   243 IMPORT_C extern int pthread_mutexattr_destroy (pthread_mutexattr_t * attr);

   244 

   245 /*

   246 This function retrieves the current value of the process shared attribute in 

   247 attr and stores it in the location pointed to by pshared.

   248 */

   249 IMPORT_C extern int pthread_mutexattr_getpshared (const pthread_mutexattr_t* attr, int* pshared);

   250 

   251 /*

   252 This function sets the current value of the process shared attribute in attr to the value specifed in the  

   253 pshared variable.

   254 */

   255 IMPORT_C extern int pthread_mutexattr_setpshared (pthread_mutexattr_t * attr, int pshared);

   256 

   257 /*

   258 This function retrieves the current value of the mutex kind attribute in attr and 

   259 stores it in the location pointed to by type.

   260 */

   261 IMPORT_C extern int pthread_mutexattr_gettype (pthread_mutexattr_t * attr, int *type);

   262 

   263 

   264 /*

   265 This function sets the current value of the mutex kind attribute in attr to the value specifed in the  type variable.

   266 */

   267 IMPORT_C extern int pthread_mutexattr_settype (pthread_mutexattr_t * attr, int type);

   268 

   269 /*

   270 This function initializes the mutex object pointed to by mutex according to the mutex attributes specified in attr. 

   271 If attr is NULL, default attributes are used instead.

   272 

   273 */

   274 IMPORT_C extern int pthread_mutex_init (pthread_mutex_t * mutex, const pthread_mutexattr_t * attr);

   275 

   276 /*

   277 This function destroys the mutex object.  The mutex must be unlocked on entrance.

   278 This implementation requires even statically initialized mutexes to be explicitly destroyed.

   279 */

   280 IMPORT_C extern int pthread_mutex_destroy (pthread_mutex_t * mutex);

   281 

   282 /*

   283 This function locks the given mutex. If the mutex is currently

   284 unlocked, it becomes locked and owned by the calling thread, and

   285 this function  returns immediately. If the mutex is already

   286 locked by another thread, this function suspends the calling

   287 thread until the mutex is unlocked. 

   288 

   289 If the mutex is already locked by the calling thread, the behavior of

   290 this function depends on the kind of the mutex. If the mutex is

   291 of the  PTHREAD_MUTEX_NORMAL or PTHREAD_MUTEX_DEFAULT kind, the calling thread is suspended until the mutex

   292 is unlocked, thus effectively causing the calling thread to

   293 deadlock. If the mutex is of the PTHREAD_MUTEX_ERRORCHECK kind,

   294 this function returns immediately with the error code EDEADLK.

   295 If the mutex is of the PTHREAD_MUTEX_RECURSIVE kind, this function

   296 succeeds and returns immediately, recording the number of times the

   297 calling thread has locked the mutex. An equal number of

   298 pthread_mutex_unlock operations must be performed before the mutex

   299 returns to the unlocked state.

   300 */

   301 IMPORT_C extern int pthread_mutex_lock (pthread_mutex_t * mutex);

   302 

   303 

   304 /*

   305 This function behaves identically to pthread_mutex_lock, except that if it cannot acquire the lock before 

   306 the abs_timeout time, the call returns with the error code ETIMEDOUT. 

   307 */

   308 IMPORT_C extern int pthread_mutex_timedlock(pthread_mutex_t *mutex, const struct timespec *abstime);

   309 

   310 /*

   311 This function behaves identically to pthread_mutex_lock, except that it does not 

   312 block the calling thread if the mutex is already locked by another thread (or by 

   313 the calling thread in the case of a PTHREAD_MUTEX_RECURSIVE mutex). Instead, pthread_mutex_trylock 

   314 returns immediately with the error code EAGAIN.

   315 */

   316 IMPORT_C extern int pthread_mutex_trylock (pthread_mutex_t * mutex);

   317 

   318 /*

   319 This function unlocks the given mutex. The mutex is assumed

   320 to be locked and owned by the calling thread on entrance to

   321 this function. If the mutex is of the PTHREAD_MUTEX_NORMAL or PTHREAD_MUTEX_DEFAULT kind,

   322 this function always returns it to the unlocked state. If it

   323 is of the PTHREAD_MUTEX_RECURSIVE kind, it decrements the locking count of the

   324 mutex (number of pthread_mutex_lock operations performed on it by

   325 the calling thread), and only when this count reaches zero is the

   326 mutex actually unlocked.

   327 

   328 On PTHREAD_MUTEX_ERRORCHECK mutexes, this function actually checks

   329 at run-time that the mutex is locked on entrance, and that it was

   330 locked by the same thread that is now calling pthread_mutex_unlock.

   331 If these conditions are not met, an error code is returned and the

   332 mutex remains unchanged.  

   333 */

   334 IMPORT_C extern int pthread_mutex_unlock (pthread_mutex_t * mutex);

   335 

   336 /*

   337 This function initializes the condition attribute object attr and 

   338 sets it with default values for the attributes. 

   339 */

   340 IMPORT_C extern int pthread_condattr_init (pthread_condattr_t * /*attr*/);

   341 

   342 /*

   343 This function destroys the condtion variable attribute object.

   344 */

   345 IMPORT_C extern int pthread_condattr_destroy (pthread_condattr_t * attr);

   346 /*

   347 extern int pthread_condattr_getpshared (const pthread_condattr_t * attr, int *pshared);

   348 extern int pthread_condattr_setpshared (pthread_condattr_t * attr, int pshared);

   349 */

   350 

   351 /*

   352 This function initializes the condition variable object pointed to by cond 

   353 using the attributes of the attr variable. If attr is NULL, default attributes 

   354 are used instead.

   355 */

   356 IMPORT_C extern int pthread_cond_init (pthread_cond_t * cond, const pthread_condattr_t * /*attr*/);

   357 

   358 /*

   359 This function destroys the condition variable  object. 

   360 */

   361 IMPORT_C extern int pthread_cond_destroy (pthread_cond_t * cond);

   362 

   363 /*

   364 This function atomically unlocks mutex and waits on cond, 

   365 as pthread_cond_wait does, but it also bounds the duration 

   366 of the wait. If cond has not been signalled within the amount 

   367 of time specified by abstime, the mutex mutex is re-acquired and 

   368 pthread_cond_timedwait returns the error ETIMEDOUT. The abstime 

   369 parameter specifies an absolute time, with the same origin as time(2) and gettimeofday(2). 

   370 */

   371 IMPORT_C extern int pthread_cond_timedwait (pthread_cond_t * cond,pthread_mutex_t * mutex,const struct timespec *abstime);

   372 

   373 /*

   374 This function atomically unlocks the mutex (as per pthread_unlock_mutex) 

   375 and waits for the condition variable cond to be signalled. The thread 

   376 execution is suspended and does not consume any CPU time until the condition 

   377 variable is signalled. The mutex must be locked by the calling thread on entrance 

   378 to pthread_cond_wait. Before returning to the calling thread, pthread_cond_wait 

   379 re-acquires mutex (as per pthread_lock_mutex).

   380 */

   381 IMPORT_C extern int pthread_cond_wait (pthread_cond_t * cond, pthread_mutex_t * mutex);

   382 

   383 /*

   384 This function restarts one of the threads that are waiting on the condition 

   385 variable cond. If no threads are waiting on cond, nothing happens. If several 

   386 threads are waiting on cond, exactly one is restarted. 

   387 

   388 */

   389 IMPORT_C extern int pthread_cond_signal (pthread_cond_t * cond);

   390 

   391 /*

   392 This function restarts all the threads that are waiting on the 

   393 condition variable cond. Nothing happens if no threads are waiting on cond. 

   394 */

   395 IMPORT_C extern int pthread_cond_broadcast (pthread_cond_t * cond);

   396 

   397 

   398 typedef void (*destructor_routine)(void *);

   399 /*

   400 Thread-specific data key creation

   401 */

   402 IMPORT_C int pthread_key_create(pthread_key_t *key, destructor_routine dest);

   403 

   404 /*

   405 Thread-specific data key deletion

   406 */

   407 IMPORT_C int pthread_key_delete(pthread_key_t key);

   408 

   409 /*

   410 Setting Thread-specific data 

   411 */

   412 IMPORT_C int pthread_setspecific(pthread_key_t key, const void *val);

   413 

   414 /*

   415 Getting Thread-specific data 

   416 */

   417 IMPORT_C void* pthread_getspecific(pthread_key_t key);

   418 

   419 /*

   420 Getting contention scope 

   421 */

   422 IMPORT_C int pthread_attr_getscope(const pthread_attr_t *attrib,

   423                                    int* scope);

   424 /*

   425 Setting contention scope 

   426 */

   427 IMPORT_C int pthread_attr_setscope(pthread_attr_t *attrib,int conscope); 

   428 

   429 /*

   430 Setting scheduling policy

   431 */

   432 IMPORT_C int pthread_attr_setschedpolicy(pthread_attr_t *attrib, 

   433                                          int policy);                                  

   434 

   435 /*

   436 Getting scheduling policy of the thread

   437 */

   438 IMPORT_C int pthread_attr_getschedpolicy(const pthread_attr_t *attrib,

   439                                          int *policy);

   440 

   441 /*

   442 Getting scheduling param of the thread

   443 */

   444 IMPORT_C int pthread_attr_getschedparam(const pthread_attr_t *attrib,

   445                                         struct sched_param *param);

   446 

   447 /*

   448 Setting scheduling param

   449 */                                        

   450 IMPORT_C int pthread_attr_setschedparam(pthread_attr_t *attrib, 

   451                                         const struct sched_param *param);

   452 

   453 /*

   454 Getting dynamic scheduling param of the thread

   455 */                                        

   456 IMPORT_C int pthread_getschedparam(pthread_t thr, int *policy,

   457                                    struct sched_param *param);

   458 

   459 /*

   460 Dynamically Setting scheduling params

   461 */                                   

   462 IMPORT_C int pthread_setschedparam(pthread_t th, int policy, 

   463                                    const struct sched_param *param);

   464                                          

   465 #ifdef __cplusplus

   466 }                               /* End of  "C" */

   467 #endif                          /* __cplusplus */

   468 

   469 

   470 #endif /* PTHREAD_H */

   471