williamr@2: /*
williamr@2: * ==============================================================================
williamr@2: *  Name        : pthread.h
williamr@2: *  Part of     : pthread
williamr@2: *  Interface   : POSIX, pthread
williamr@2: *  Description : POSIX thread exported header file 
williamr@2: *  Version     : 
williamr@2: 
williamr@2: Copyright © 2005-2006 Nokia Corporation
williamr@2: All rights reserved.
williamr@2: * © Portions copyright (c) 2007 Symbian Software Ltd. All rights reserved.
williamr@2: Redistribution and use in source and binary forms, with or without 
williamr@2: modification, are permitted provided that the following conditions are met:
williamr@2:  * Redistributions of source code must retain the above copyright notice, this 
williamr@2:    list of conditions and the following disclaimer. 
williamr@2:  * Redistributions in binary form must reproduce the above copyright notice, 
williamr@2:    this list of conditions and the following disclaimer in the documentation 
williamr@2:    and/or other materials provided with the distribution. 
williamr@2:  * Neither the name of the <ORGANIZATION> nor the names of its contributors 
williamr@2:    may be used to endorse or promote products derived from this software 
williamr@2:    without specific prior written permission. 
williamr@2:    
williamr@2: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
williamr@2: AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
williamr@2: IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
williamr@2: DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
williamr@2: FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
williamr@2: DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
williamr@2: SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
williamr@2: CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
williamr@2: OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
williamr@2: OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
williamr@2: * ==============================================================================
williamr@2: */
williamr@2: #ifndef  PTHREAD_H
williamr@2: #define  PTHREAD_H
williamr@2: 
williamr@2: #include <pthreadtypes.h>
williamr@2: #include <sched.h>
williamr@2: #include <e32def.h>
williamr@2: #include <stddef.h>
williamr@2: #include <time.h>
williamr@2: #include <limits.h>
williamr@2: #include <pthreadalias.h>
williamr@2: 
williamr@2: #define POSIX_THREAD_DESTRUCTOR_ITERATIONS  4
williamr@2: #define POSIX_THREAD_KEYS_MAX               128
williamr@2: #define PTHREAD_STACK_MIN                   0x2000
williamr@2: #define POSIX_THREAD_THREADS_MAX            64
williamr@2: #define PTHREAD_THREADS_MAX                 1024
williamr@2: #define POSIX_SEM_NSEMS_MAX                 256
williamr@2: #define SEM_NSEMS_MAX                       1024
williamr@2: #define _POSIX_SEM_VALUE_MAX                32767
williamr@2: #define SEM_VALUE_MAX                       INT_MAX
williamr@2: 
williamr@2: /* internal use*/
williamr@2: typedef enum 
williamr@2: {
williamr@2:     _ENeedsNormalInit =-3,
williamr@2:     _ENeedsRecursiveInit,
williamr@2:     _ENeedsErrorCheckInit,
williamr@2:     _EInitialized =1,
williamr@2:     _EDestroyed,
williamr@2:     _EInvalid,
williamr@2: }_handle_state;
williamr@2: 
williamr@2: enum _LockStatus
williamr@2: {
williamr@2:     _ELockNotCreated,
williamr@2:     _ELockCreating,
williamr@2:     _ELockCreated,
williamr@2: };
williamr@2: 
williamr@2: enum _OnceStatus
williamr@2: {
williamr@2:     _ENotDone,
williamr@2:     _EDoing,
williamr@2:     _EDone,
williamr@2: };
williamr@2: 
williamr@2: typedef int pthread_once_t;
williamr@2: 
williamr@2: struct _pthread_mutex_t;
williamr@2: typedef struct 
williamr@2: {
williamr@2:     _handle_state  iState;
williamr@2:     struct _pthread_mutex_t* iPtr;
williamr@2:     int   iReentry;
williamr@2: }pthread_mutex_t;
williamr@2: 
williamr@2: typedef struct 
williamr@2: {
williamr@2:     _handle_state iState;
williamr@2:     int iSharedType;
williamr@2:     int iMutexType;
williamr@2: }pthread_mutexattr_t;
williamr@2: 
williamr@2: 
williamr@2: struct _CondNode;
williamr@2: struct _CondQueue
williamr@2: {
williamr@2:   struct _CondNode*       iHead;
williamr@2:   struct _CondNode*       iTail;
williamr@2:   pthread_mutex_t iMutex;
williamr@2: };
williamr@2: 
williamr@2: typedef struct 
williamr@2: {
williamr@2:   _handle_state    iState;
williamr@2:   struct _CondQueue       iQueue;
williamr@2: }pthread_cond_t;
williamr@2: 
williamr@2: typedef struct _pthread_condattr_t*   pthread_condattr_t;
williamr@2: 
williamr@2: #define PTHREAD_ONCE_INIT _ENotDone
williamr@2: 
williamr@2: #define PTHREAD_MUTEX_INITIALIZER { _ENeedsNormalInit, NULL,0 }
williamr@2: #define PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP { _ENeedsRecursiveInit, NULL, 0 }
williamr@2: #define PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP { _ENeedsErrorCheckInit, NULL,0 }
williamr@2: 
williamr@2: #define PTHREAD_COND_INITIALIZER { _ENeedsNormalInit, NULL,NULL }
williamr@2: 
williamr@2: enum 
williamr@2: { 
williamr@2:     PTHREAD_CREATE_JOINABLE = 0,  /* Default */ 
williamr@2:     PTHREAD_CREATE_DETACHED = 1
williamr@2: };
williamr@2: 
williamr@2: enum 
williamr@2: { 
williamr@2:     PTHREAD_SCOPE_SYSTEM  = 1  /* Default */
williamr@2: };
williamr@2: 
williamr@2: enum 
williamr@2: {  
williamr@2:     PTHREAD_CANCEL_ASYNCHRONOUS = 0,  
williamr@2:     PTHREAD_CANCEL_DEFERRED = 1  /* Default */
williamr@2: };
williamr@2: 
williamr@2: enum 
williamr@2: {  
williamr@2:     PTHREAD_PROCESS_PRIVATE = 0,   
williamr@2: };
williamr@2: 
williamr@2: enum
williamr@2: {
williamr@2:   PTHREAD_MUTEX_NORMAL,
williamr@2:   PTHREAD_MUTEX_RECURSIVE,
williamr@2:   PTHREAD_MUTEX_ERRORCHECK,
williamr@2:   PTHREAD_MUTEX_DEFAULT = PTHREAD_MUTEX_NORMAL
williamr@2: };
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifdef __cplusplus
williamr@2: extern "C"
williamr@2: {
williamr@2: #endif    /* __cplusplus */
williamr@2: 
williamr@2: typedef void * (*thread_begin_routine)(void *);
williamr@2: /*
williamr@2: This function creates a thread, with attributes specified by attrib,
williamr@2: within a process. If attrib is NULL, then default attributes will be used.
williamr@2: On successful completion, pthread_create() will store the ID of the 
williamr@2: created thread in the location referenced by threadhdl.
williamr@2: */ 
williamr@2: IMPORT_C extern int pthread_create(pthread_t *threadhdl, pthread_attr_t *attrib, 
williamr@2:                    thread_begin_routine begin_routine , void * param);  
williamr@2: /*
williamr@2: This function return the handle to current thread.
williamr@2: */                    
williamr@2: IMPORT_C extern pthread_t pthread_self ();
williamr@2: 
williamr@2: /*
williamr@2: Compare two thread handles
williamr@2: */
williamr@2: IMPORT_C extern int pthread_equal(pthread_t t1,pthread_t t2);
williamr@2: /*
williamr@2: Waiting for thread termination
williamr@2: */
williamr@2: IMPORT_C extern int pthread_join(pthread_t thHandle, void **retValPtr);
williamr@2: /*
williamr@2: detach from thread 
williamr@2: */
williamr@2: IMPORT_C extern int pthread_detach(pthread_t thrHandle);
williamr@2: /*
williamr@2: exit current thread
williamr@2: */
williamr@2: IMPORT_C extern void pthread_exit(void *retValPtr);
williamr@2: /*
williamr@2: Initialise the thread attributes
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_init(pthread_attr_t *attrib);
williamr@2: /*
williamr@2: Destroy the thread attributes
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_destroy(pthread_attr_t *attrib);
williamr@2: /*
williamr@2: Get the detach_state of the current thread
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_getdetachstate(const pthread_attr_t *attrib,
williamr@2:                                          int *detState);
williamr@2: /*
williamr@2: Set the detach_state of the current thread
williamr@2: */                                         
williamr@2: IMPORT_C int pthread_attr_setdetachstate(pthread_attr_t *attrib, 
williamr@2:                                          int detState);                                         
williamr@2: /*
williamr@2: Get the stack size of the current thread
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_getstacksize(const pthread_attr_t *attrib,
williamr@2:                                        size_t *stkSize);
williamr@2: /*
williamr@2: Set the stack size of the current thread
williamr@2: */                                       
williamr@2: IMPORT_C int pthread_attr_setstacksize(pthread_attr_t *attrib, 
williamr@2:                                        size_t stkSize);                                       
williamr@2: 
williamr@2: /*
williamr@2: This function ensures that a piece of initialization code is executed at most once. 
williamr@2: The once_control argument must point to a static  variable statically initialized to PTHREAD_ONCE_INIT
williamr@2: 
williamr@2: */
williamr@2: typedef void (*thread_init_routine) (void);
williamr@2: IMPORT_C extern int pthread_once (pthread_once_t * once_control, 
williamr@2:                                   thread_init_routine init_routine);
williamr@2: 
williamr@2: /*
williamr@2: extern int pthread_key_create (pthread_key_t * key, void (*destructor) (void *));
williamr@2: extern int pthread_key_delete (pthread_key_t key);
williamr@2: extern int pthread_setspecific (pthread_key_t key, const void *value);
williamr@2: extern void* pthread_getspecific (pthread_key_t key);
williamr@2: */
williamr@2: 
williamr@2: /*
williamr@2: This function initializes the mutex attribute object attr and fills it with default values for the attributes.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutexattr_init (pthread_mutexattr_t * attr);
williamr@2: 
williamr@2: /*
williamr@2: This function destroys the mutex attribute object attr and marks it as a destroyed object.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutexattr_destroy (pthread_mutexattr_t * attr);
williamr@2: 
williamr@2: /*
williamr@2: This function retrieves the current value of the process shared attribute in 
williamr@2: attr and stores it in the location pointed to by pshared.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutexattr_getpshared (const pthread_mutexattr_t* attr, int* pshared);
williamr@2: 
williamr@2: /*
williamr@2: This function sets the current value of the process shared attribute in attr to the value specifed in the  
williamr@2: pshared variable.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutexattr_setpshared (pthread_mutexattr_t * attr, int pshared);
williamr@2: 
williamr@2: /*
williamr@2: This function retrieves the current value of the mutex kind attribute in attr and 
williamr@2: stores it in the location pointed to by type.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutexattr_gettype (pthread_mutexattr_t * attr, int *type);
williamr@2: 
williamr@2: 
williamr@2: /*
williamr@2: This function sets the current value of the mutex kind attribute in attr to the value specifed in the  type variable.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutexattr_settype (pthread_mutexattr_t * attr, int type);
williamr@2: 
williamr@2: /*
williamr@2: This function initializes the mutex object pointed to by mutex according to the mutex attributes specified in attr. 
williamr@2: If attr is NULL, default attributes are used instead.
williamr@2: 
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutex_init (pthread_mutex_t * mutex, const pthread_mutexattr_t * attr);
williamr@2: 
williamr@2: /*
williamr@2: This function destroys the mutex object.  The mutex must be unlocked on entrance.
williamr@2: This implementation requires even statically initialized mutexes to be explicitly destroyed.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutex_destroy (pthread_mutex_t * mutex);
williamr@2: 
williamr@2: /*
williamr@2: This function locks the given mutex. If the mutex is currently
williamr@2: unlocked, it becomes locked and owned by the calling thread, and
williamr@2: this function  returns immediately. If the mutex is already
williamr@2: locked by another thread, this function suspends the calling
williamr@2: thread until the mutex is unlocked. 
williamr@2: 
williamr@2: If the mutex is already locked by the calling thread, the behavior of
williamr@2: this function depends on the kind of the mutex. If the mutex is
williamr@2: of the  PTHREAD_MUTEX_NORMAL or PTHREAD_MUTEX_DEFAULT kind, the calling thread is suspended until the mutex
williamr@2: is unlocked, thus effectively causing the calling thread to
williamr@2: deadlock. If the mutex is of the PTHREAD_MUTEX_ERRORCHECK kind,
williamr@2: this function returns immediately with the error code EDEADLK.
williamr@2: If the mutex is of the PTHREAD_MUTEX_RECURSIVE kind, this function
williamr@2: succeeds and returns immediately, recording the number of times the
williamr@2: calling thread has locked the mutex. An equal number of
williamr@2: pthread_mutex_unlock operations must be performed before the mutex
williamr@2: returns to the unlocked state.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutex_lock (pthread_mutex_t * mutex);
williamr@2: 
williamr@2: 
williamr@2: /*
williamr@2: This function behaves identically to pthread_mutex_lock, except that if it cannot acquire the lock before 
williamr@2: the abs_timeout time, the call returns with the error code ETIMEDOUT. 
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutex_timedlock(pthread_mutex_t *mutex, const struct timespec *abstime);
williamr@2: 
williamr@2: /*
williamr@2: This function behaves identically to pthread_mutex_lock, except that it does not 
williamr@2: block the calling thread if the mutex is already locked by another thread (or by 
williamr@2: the calling thread in the case of a PTHREAD_MUTEX_RECURSIVE mutex). Instead, pthread_mutex_trylock 
williamr@2: returns immediately with the error code EAGAIN.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutex_trylock (pthread_mutex_t * mutex);
williamr@2: 
williamr@2: /*
williamr@2: This function unlocks the given mutex. The mutex is assumed
williamr@2: to be locked and owned by the calling thread on entrance to
williamr@2: this function. If the mutex is of the PTHREAD_MUTEX_NORMAL or PTHREAD_MUTEX_DEFAULT kind,
williamr@2: this function always returns it to the unlocked state. If it
williamr@2: is of the PTHREAD_MUTEX_RECURSIVE kind, it decrements the locking count of the
williamr@2: mutex (number of pthread_mutex_lock operations performed on it by
williamr@2: the calling thread), and only when this count reaches zero is the
williamr@2: mutex actually unlocked.
williamr@2: 
williamr@2: On PTHREAD_MUTEX_ERRORCHECK mutexes, this function actually checks
williamr@2: at run-time that the mutex is locked on entrance, and that it was
williamr@2: locked by the same thread that is now calling pthread_mutex_unlock.
williamr@2: If these conditions are not met, an error code is returned and the
williamr@2: mutex remains unchanged.  
williamr@2: */
williamr@2: IMPORT_C extern int pthread_mutex_unlock (pthread_mutex_t * mutex);
williamr@2: 
williamr@2: /*
williamr@2: This function initializes the condition attribute object attr and 
williamr@2: sets it with default values for the attributes. 
williamr@2: */
williamr@2: IMPORT_C extern int pthread_condattr_init (pthread_condattr_t * /*attr*/);
williamr@2: 
williamr@2: /*
williamr@2: This function destroys the condtion variable attribute object.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_condattr_destroy (pthread_condattr_t * attr);
williamr@2: /*
williamr@2: extern int pthread_condattr_getpshared (const pthread_condattr_t * attr, int *pshared);
williamr@2: extern int pthread_condattr_setpshared (pthread_condattr_t * attr, int pshared);
williamr@2: */
williamr@2: 
williamr@2: /*
williamr@2: This function initializes the condition variable object pointed to by cond 
williamr@2: using the attributes of the attr variable. If attr is NULL, default attributes 
williamr@2: are used instead.
williamr@2: */
williamr@2: IMPORT_C extern int pthread_cond_init (pthread_cond_t * cond, const pthread_condattr_t * /*attr*/);
williamr@2: 
williamr@2: /*
williamr@2: This function destroys the condition variable  object. 
williamr@2: */
williamr@2: IMPORT_C extern int pthread_cond_destroy (pthread_cond_t * cond);
williamr@2: 
williamr@2: /*
williamr@2: This function atomically unlocks mutex and waits on cond, 
williamr@2: as pthread_cond_wait does, but it also bounds the duration 
williamr@2: of the wait. If cond has not been signalled within the amount 
williamr@2: of time specified by abstime, the mutex mutex is re-acquired and 
williamr@2: pthread_cond_timedwait returns the error ETIMEDOUT. The abstime 
williamr@2: parameter specifies an absolute time, with the same origin as time(2) and gettimeofday(2). 
williamr@2: */
williamr@2: IMPORT_C extern int pthread_cond_timedwait (pthread_cond_t * cond,pthread_mutex_t * mutex,const struct timespec *abstime);
williamr@2: 
williamr@2: /*
williamr@2: This function atomically unlocks the mutex (as per pthread_unlock_mutex) 
williamr@2: and waits for the condition variable cond to be signalled. The thread 
williamr@2: execution is suspended and does not consume any CPU time until the condition 
williamr@2: variable is signalled. The mutex must be locked by the calling thread on entrance 
williamr@2: to pthread_cond_wait. Before returning to the calling thread, pthread_cond_wait 
williamr@2: re-acquires mutex (as per pthread_lock_mutex).
williamr@2: */
williamr@2: IMPORT_C extern int pthread_cond_wait (pthread_cond_t * cond, pthread_mutex_t * mutex);
williamr@2: 
williamr@2: /*
williamr@2: This function restarts one of the threads that are waiting on the condition 
williamr@2: variable cond. If no threads are waiting on cond, nothing happens. If several 
williamr@2: threads are waiting on cond, exactly one is restarted. 
williamr@2: 
williamr@2: */
williamr@2: IMPORT_C extern int pthread_cond_signal (pthread_cond_t * cond);
williamr@2: 
williamr@2: /*
williamr@2: This function restarts all the threads that are waiting on the 
williamr@2: condition variable cond. Nothing happens if no threads are waiting on cond. 
williamr@2: */
williamr@2: IMPORT_C extern int pthread_cond_broadcast (pthread_cond_t * cond);
williamr@2: 
williamr@2: 
williamr@2: typedef void (*destructor_routine)(void *);
williamr@2: /*
williamr@2: Thread-specific data key creation
williamr@2: */
williamr@2: IMPORT_C int pthread_key_create(pthread_key_t *key, destructor_routine dest);
williamr@2: 
williamr@2: /*
williamr@2: Thread-specific data key deletion
williamr@2: */
williamr@2: IMPORT_C int pthread_key_delete(pthread_key_t key);
williamr@2: 
williamr@2: /*
williamr@2: Setting Thread-specific data 
williamr@2: */
williamr@2: IMPORT_C int pthread_setspecific(pthread_key_t key, const void *val);
williamr@2: 
williamr@2: /*
williamr@2: Getting Thread-specific data 
williamr@2: */
williamr@2: IMPORT_C void* pthread_getspecific(pthread_key_t key);
williamr@2: 
williamr@2: /*
williamr@2: Getting contention scope 
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_getscope(const pthread_attr_t *attrib,
williamr@2:                                    int* scope);
williamr@2: /*
williamr@2: Setting contention scope 
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_setscope(pthread_attr_t *attrib,int conscope); 
williamr@2: 
williamr@2: /*
williamr@2: Setting scheduling policy
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_setschedpolicy(pthread_attr_t *attrib, 
williamr@2:                                          int policy);                                  
williamr@2: 
williamr@2: /*
williamr@2: Getting scheduling policy of the thread
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_getschedpolicy(const pthread_attr_t *attrib,
williamr@2:                                          int *policy);
williamr@2: 
williamr@2: /*
williamr@2: Getting scheduling param of the thread
williamr@2: */
williamr@2: IMPORT_C int pthread_attr_getschedparam(const pthread_attr_t *attrib,
williamr@2:                                         struct sched_param *param);
williamr@2: 
williamr@2: /*
williamr@2: Setting scheduling param
williamr@2: */                                        
williamr@2: IMPORT_C int pthread_attr_setschedparam(pthread_attr_t *attrib, 
williamr@2:                                         const struct sched_param *param);
williamr@2: 
williamr@2: /*
williamr@2: Getting dynamic scheduling param of the thread
williamr@2: */                                        
williamr@2: IMPORT_C int pthread_getschedparam(pthread_t thr, int *policy,
williamr@2:                                    struct sched_param *param);
williamr@2: 
williamr@2: /*
williamr@2: Dynamically Setting scheduling params
williamr@2: */                                   
williamr@2: IMPORT_C int pthread_setschedparam(pthread_t th, int policy, 
williamr@2:                                    const struct sched_param *param);
williamr@2:                                          
williamr@2: #ifdef __cplusplus
williamr@2: }                               /* End of  "C" */
williamr@2: #endif                          /* __cplusplus */
williamr@2: 
williamr@2: 
williamr@2: #endif /* PTHREAD_H */
williamr@2: