/* * implement.h * * Definitions that don't need to be public. * * Keeps all the internals out of pthread.h * * -------------------------------------------------------------------------- * * Pthreads-embedded (PTE) - POSIX Threads Library for embedded systems * Copyright(C) 2008 Jason Schmidlapp * * Contact Email: jschmidlapp@users.sourceforge.net * * * Pthreads-embedded (PTE) - POSIX Threads Library for embedded systems * Copyright(C) 2008 Jason Schmidlapp * * Contact Email: jschmidlapp@users.sourceforge.net * * * Based upon Pthreads-win32 - POSIX Threads Library for Win32 * Copyright(C) 1998 John E. Bossom * Copyright(C) 1999,2005 Pthreads-win32 contributors * * Contact Email: rpj@callisto.canberra.edu.au * * The original list of contributors to the Pthreads-win32 project * is contained in the file CONTRIBUTORS.ptw32 included with the * source code distribution. The list can also be seen at the * following World Wide Web location: * http://sources.redhat.com/pthreads-win32/contributors.html * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library in the file COPYING.LIB; * if not, write to the Free Software Foundation, Inc., * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA */ #ifndef _IMPLEMENT_H #define _IMPLEMENT_H #include "pte_osal.h" /* use local include files during development */ #include "semaphore.h" #include "sched.h" typedef enum { /* * This enumeration represents the state of the thread; * The thread is still "alive" if the numeric value of the * state is greater or equal "PThreadStateRunning". */ PThreadStateInitial = 0, /* Thread not running */ PThreadStateRunning, /* Thread alive & kicking */ PThreadStateSuspended, /* Thread alive but suspended */ PThreadStateCancelPending, /* Thread alive but is */ /* has cancelation pending. */ PThreadStateCanceling, /* Thread alive but is */ /* in the process of terminating */ /* due to a cancellation request */ PThreadStateException, /* Thread alive but exiting */ /* due to an exception */ PThreadStateLast } PThreadState; typedef struct pte_thread_t_ pte_thread_t; struct pte_thread_t_ { pte_osThreadHandle threadId; /* OS specific thread handle */ pthread_t ptHandle; /* This thread's permanent pthread_t handle */ pte_thread_t * prevReuse; /* Links threads on reuse stack */ volatile PThreadState state; void *exitStatus; void *parms; int ptErrno; int detachState; pthread_mutex_t threadLock; /* Used for serialised access to public thread state */ int sched_priority; /* As set, not as currently is */ pthread_mutex_t cancelLock; /* Used for async-cancel safety */ int cancelState; int cancelType; int cancelEvent; #ifdef PTE_CLEANUP_C jmp_buf start_mark; #endif /* PTE_CLEANUP_C */ int implicit: 1; void *keys; void *nextAssoc; }; /* * Special value to mark attribute objects as valid. */ #define PTE_ATTR_VALID ((unsigned long) 0xC4C0FFEE) struct pthread_attr_t_ { unsigned long valid; void *stackaddr; size_t stacksize; int detachstate; struct sched_param param; int inheritsched; int contentionscope; }; /* * ==================== * ==================== * Semaphores, Mutexes and Condition Variables * ==================== * ==================== */ struct sem_t_ { int value; pthread_mutex_t lock; pte_osSemaphoreHandle sem; }; #define PTE_OBJECT_AUTO_INIT ((void *) -1) #define PTE_OBJECT_INVALID 0 struct pthread_mutex_t_ { pte_osSemaphoreHandle handle; int lock_idx; /* Provides exclusive access to mutex state via the Interlocked* mechanism. 0: unlocked/free. 1: locked - no other waiters. -1: locked - with possible other waiters. */ int recursive_count; /* Number of unlocks a thread needs to perform before the lock is released (recursive mutexes only). */ int kind; /* Mutex type. */ pthread_t ownerThread; }; struct pthread_mutexattr_t_ { int pshared; int kind; }; /* * Possible values, other than PTE_OBJECT_INVALID, * for the "interlock" element in a spinlock. * * In this implementation, when a spinlock is initialised, * the number of cpus available to the process is checked. * If there is only one cpu then "interlock" is set equal to * PTE_SPIN_USE_MUTEX and u.mutex is a initialised mutex. * If the number of cpus is greater than 1 then "interlock" * is set equal to PTE_SPIN_UNLOCKED and the number is * stored in u.cpus. This arrangement allows the spinlock * routines to attempt an InterlockedCompareExchange on "interlock" * immediately and, if that fails, to try the inferior mutex. * * "u.cpus" isn't used for anything yet, but could be used at * some point to optimise spinlock behaviour. */ #define PTE_SPIN_UNLOCKED (1) #define PTE_SPIN_LOCKED (2) #define PTE_SPIN_USE_MUTEX (3) struct pthread_spinlock_t_ { int interlock; /* Locking element for multi-cpus. */ union { int cpus; /* No. of cpus if multi cpus, or */ pthread_mutex_t mutex; /* mutex if single cpu. */ } u; }; struct pthread_barrier_t_ { unsigned int nCurrentBarrierHeight; unsigned int nInitialBarrierHeight; int iStep; int pshared; sem_t semBarrierBreeched[2]; }; struct pthread_barrierattr_t_ { int pshared; }; struct pthread_key_t_ { unsigned key; void (*destructor) (void *); pthread_mutex_t keyLock; void *threads; }; typedef struct ThreadParms ThreadParms; typedef struct ThreadKeyAssoc ThreadKeyAssoc; struct ThreadParms { pthread_t tid; void *(*start) (void *); void *arg; }; struct pthread_cond_t_ { long nWaitersBlocked; /* Number of threads blocked */ long nWaitersGone; /* Number of threads timed out */ long nWaitersToUnblock; /* Number of threads to unblock */ sem_t semBlockQueue; /* Queue up threads waiting for the */ /* condition to become signalled */ sem_t semBlockLock; /* Semaphore that guards access to */ /* | waiters blocked count/block queue */ /* +-> Mandatory Sync.LEVEL-1 */ pthread_mutex_t mtxUnblockLock; /* Mutex that guards access to */ /* | waiters (to)unblock(ed) counts */ /* +-> Optional* Sync.LEVEL-2 */ pthread_cond_t next; /* Doubly linked list */ pthread_cond_t prev; }; struct pthread_condattr_t_ { int pshared; // TODO: use clock_id clockid_t clock_id; }; #define PTE_RWLOCK_MAGIC 0xfacade2 struct pthread_rwlock_t_ { pthread_mutex_t mtxExclusiveAccess; pthread_mutex_t mtxSharedAccessCompleted; pthread_cond_t cndSharedAccessCompleted; int nSharedAccessCount; int nExclusiveAccessCount; int nCompletedSharedAccessCount; int nMagic; }; struct pthread_rwlockattr_t_ { int pshared; }; /* * MCS lock queue node - see pte_MCS_lock.c */ struct pte_mcs_node_t_ { struct pte_mcs_node_t_ **lock; /* ptr to tail of queue */ struct pte_mcs_node_t_ *next; /* ptr to successor in queue */ unsigned int readyFlag; /* set after lock is released by predecessor */ unsigned int nextFlag; /* set after 'next' ptr is set by successor */ }; typedef struct pte_mcs_node_t_ pte_mcs_local_node_t; typedef struct pte_mcs_node_t_ *pte_mcs_lock_t; struct ThreadKeyAssoc { /* * Purpose: * This structure creates an association between a thread and a key. * It is used to implement the implicit invocation of a user defined * destroy routine for thread specific data registered by a user upon * exiting a thread. * * Graphically, the arrangement is as follows, where: * * K - Key with destructor * (head of chain is key->threads) * T - Thread that has called pthread_setspecific(Kn) * (head of chain is thread->keys) * A - Association. Each association is a node at the * intersection of two doubly-linked lists. * * T1 T2 T3 * | | | * | | | * K1 -----+-----A-----A-----> * | | | * | | | * K2 -----A-----A-----+-----> * | | | * | | | * K3 -----A-----+-----A-----> * | | | * | | | * V V V * * Access to the association is guarded by two locks: the key's * general lock (guarding the row) and the thread's general * lock (guarding the column). This avoids the need for a * dedicated lock for each association, which not only consumes * more handles but requires that: before the lock handle can * be released - both the key must be deleted and the thread * must have called the destructor. The two-lock arrangement * allows the resources to be freed as soon as either thread or * key is concluded. * * To avoid deadlock: whenever both locks are required, the key * and thread locks are always acquired in the order: key lock * then thread lock. An exception to this exists when a thread * calls the destructors, however this is done carefully to * avoid deadlock. * * An association is created when a thread first calls * pthread_setspecific() on a key that has a specified * destructor. * * An association is destroyed either immediately after the * thread calls the key destructor function on thread exit, or * when the key is deleted. * * Attributes: * thread * reference to the thread that owns the * association. This is actually the pointer to the * thread struct itself. Since the association is * destroyed before the thread exits, this can never * point to a different logical thread to the one that * created the assoc, i.e. after thread struct reuse. * * key * reference to the key that owns the association. * * nextKey * The pthread_t->keys attribute is the head of a * chain of associations that runs through the nextKey * link. This chain provides the 1 to many relationship * between a pthread_t and all pthread_key_t on which * it called pthread_setspecific. * * prevKey * Similarly. * * nextThread * The pthread_key_t->threads attribute is the head of * a chain of assoctiations that runs through the * nextThreads link. This chain provides the 1 to many * relationship between a pthread_key_t and all the * PThreads that have called pthread_setspecific for * this pthread_key_t. * * prevThread * Similarly. * * Notes: * 1) As soon as either the key or the thread is no longer * referencing the association, it can be destroyed. The * association will be removed from both chains. * * 2) An association is only created by * pthread_setspecific if the user provided a * destroyRoutine when they created the key. * * */ pte_thread_t * thread; pthread_key_t key; ThreadKeyAssoc *nextKey; ThreadKeyAssoc *nextThread; ThreadKeyAssoc *prevKey; ThreadKeyAssoc *prevThread; }; /* * Services available through EXCEPTION_PTE_SERVICES * and also used [as parameters to pte_throw()] as * generic exception selectors. */ #define PTE_EPS_EXIT (1) #define PTE_EPS_CANCEL (2) /* Useful macros */ #define PTE_MAX(a,b) ((a)<(b)?(b):(a)) #define PTE_MIN(a,b) ((a)>(b)?(b):(a)) /* Thread Reuse stack bottom marker. Must not be NULL or any valid pointer to memory. */ #define PTE_THREAD_REUSE_EMPTY ((pte_thread_t *) 1) extern int pte_processInitialized; extern pte_thread_t * pte_threadReuseTop; extern pte_thread_t * pte_threadReuseBottom; extern pthread_key_t pte_selfThreadKey; extern pthread_key_t pte_cleanupKey; extern pthread_cond_t pte_cond_list_head; extern pthread_cond_t pte_cond_list_tail; extern int pte_mutex_default_kind; extern int pte_concurrency; extern int pte_features; extern pte_osMutexHandle pte_thread_reuse_lock; extern pte_osMutexHandle pte_mutex_test_init_lock; extern pte_osMutexHandle pte_cond_list_lock; extern pte_osMutexHandle pte_cond_test_init_lock; extern pte_osMutexHandle pte_rwlock_test_init_lock; extern pte_osMutexHandle pte_spinlock_test_init_lock; #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /* * ===================== * ===================== * Forward Declarations * ===================== * ===================== */ int pte_is_attr (const pthread_attr_t * attr); int pte_cond_check_need_init (pthread_cond_t * cond); int pte_mutex_check_need_init (pthread_mutex_t * mutex); int pte_rwlock_check_need_init (pthread_rwlock_t * rwlock); int pte_spinlock_check_need_init (pthread_spinlock_t * lock); int pte_processInitialize (void); void pte_processTerminate (void); void pte_threadDestroy (pthread_t tid); void pte_threadExitAndDestroy (pthread_t tid); void pte_pop_cleanup_all (int execute); pthread_t pte_new (void); pthread_t pte_threadReusePop (void); void pte_threadReusePush (pthread_t thread); int pte_getprocessors (int *count); int pte_setthreadpriority (pthread_t thread, int policy, int priority); void pte_rwlock_cancelwrwait (void *arg); int pte_threadStart (void *vthreadParms); void pte_callUserDestroyRoutines (pthread_t thread); int pte_tkAssocCreate (pte_thread_t * thread, pthread_key_t key); void pte_tkAssocDestroy (ThreadKeyAssoc * assoc); int sem_wait_nocancel (sem_t * sem); unsigned int pte_relmillisecs (const struct timespec * abstime); void pte_mcs_lock_acquire (pte_mcs_lock_t * lock, pte_mcs_local_node_t * node); void pte_mcs_lock_release (pte_mcs_local_node_t * node); /* Declared in private.c */ void pte_throw (unsigned int exception); int pte_cancellable_wait (pte_osSemaphoreHandle semHandle, unsigned int* timeout); #define PTE_ATOMIC_EXCHANGE pte_osAtomicExchange #define PTE_ATOMIC_EXCHANGE_ADD pte_osAtomicExchangeAdd #define PTE_ATOMIC_COMPARE_EXCHANGE pte_osAtomicCompareExchange #define PTE_ATOMIC_DECREMENT pte_osAtomicDecrement #define PTE_ATOMIC_INCREMENT pte_osAtomicIncrement int pte_thread_detach_np(); int pte_thread_detach_and_exit_np(); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* _IMPLEMENT_H */