Security-163.tar.gz

[apple/security.git] / cdsa / cdsa_utilities / threading.h

/*
 * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
 * 
 * The contents of this file constitute Original Code as defined in and are
 * subject to the Apple Public Source License Version 1.2 (the 'License').
 * You may not use this file except in compliance with the License. Please obtain
 * a copy of the License at http://www.apple.com/publicsource and read it before
 * using this file.
 * 
 * This Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
 * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
 * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
 * specific language governing rights and limitations under the License.
 */


//
// threading - generic thread support
//
#ifndef _H_THREADING
#define _H_THREADING

#include <Security/utilities.h>
#include <Security/debugging.h>

#if _USE_THREADS == _USE_PTHREADS
# include <pthread.h>
#endif

#include <Security/threading_internal.h>


namespace Security {


//
// Potentially, debug-logging all Mutex activity can really ruin your
// performance day. We take some measures to reduce the impact, but if
// you really can't stomach any overhead, define THREAD_NDEBUG to turn
// (only) thread debug-logging off. NDEBUG will turn this on automatically.
// On the other hand, throwing out all debug code will change the ABI of
// Mutexi in incompatible ways. Thus, we still generate the debug-style out-of-line
// code even with THREAD_NDEBUG, so that debug-style code will work with us.
// If you want to ditch it completely, #define THREAD_CLEAN_NDEBUG.
//
#if defined(NDEBUG) || defined(THREAD_CLEAN_NDEBUG)
# if !defined(THREAD_NDEBUG)
#  define THREAD_NDEBUG
# endif
#endif


//
// An abstraction of a per-thread untyped storage slot of pointer size.
// Do not use this in ordinary code; this is for implementing other primitives only.
// Use a PerThreadPointer or ThreadNexus.
//
#if _USE_THREADS == _USE_PTHREADS

class ThreadStoreSlot {
public:
	typedef void Destructor(void *);
    ThreadStoreSlot(Destructor *destructor = NULL);
    ~ThreadStoreSlot();

    void *get() const			{ return pthread_getspecific(mKey); }
    operator void * () const	{ return get(); }
    void operator = (void *value) const
    {
        if (int err = pthread_setspecific(mKey, value))
            UnixError::throwMe(err);
    }

private:
    pthread_key_t mKey;
};

#endif //_USE_PTHREADS


//
// Per-thread pointers are patterned after the pthread TLS (thread local storage)
// facility.
// Let's be clear on what gets destroyed when, here. Following the pthread lead,
// when a thread dies its PerThreadPointer object(s) are properly destroyed.
// However, if a PerThreadPointer itself is destroyed, NOTHING HAPPENS. Yes, there are
// reasons for this. This is not (on its face) a bug, so don't yell. But be aware...
//
#if _USE_THREADS == _USE_PTHREADS

template <class T>
class PerThreadPointer : public ThreadStoreSlot {
public:
	PerThreadPointer(bool cleanup = true) : ThreadStoreSlot(cleanup ? destructor : NULL) { }
	operator bool() const		{ return get() != NULL; }
	operator T * () const		{ return reinterpret_cast<T *>(get()); }
    T *operator -> () const		{ return static_cast<T *>(*this); }
    T &operator * () const		{ return *static_cast<T *>(get()); }
    void operator = (T *t)		{ ThreadStoreSlot::operator = (t); }
	
private:
	static void destructor(void *element)
	{ delete reinterpret_cast<T *>(element); }
};

#elif _USE_THREADS == _USE_NO_THREADS

template <class T>
class PerThreadPointer {
public:
	PerThreadPointer(bool cleanup = true) : mCleanup(cleanup) { }
    ~PerThreadPointer()			{ /* no cleanup - see comment above */ }
	operator bool() const		{ return mValue != NULL; }
	operator T * () const		{ return mValue; }
    T *operator -> () const		{ return mValue; }
    T &operator * () const		{ assert(mValue); return *mValue; }
    void operator = (T *t)		{ mValue = t; }

private:
    T *mValue;
    bool mCleanup;
};

#else
# error Unsupported threading model
#endif //_USE_THREADS


//
// Basic Mutex operations.
// This will be some as-cheap-as-feasible locking primitive that only
// controls one bit (locked/unlocked), plus whatever you contractually
// put under its control.
//
#if _USE_THREADS == _USE_PTHREADS

class Mutex {
    NOCOPY(Mutex)
    
    void check(int err)	{ if (err) UnixError::throwMe(err); }

public:
    Mutex(bool log = true);
	~Mutex();
    void lock();
	bool tryLock();
    void unlock();

private:
    pthread_mutex_t me;
	
	bool debugLog;						// log *this* mutex
	unsigned long useCount;				// number of locks succeeded
	unsigned long contentionCount;		// number of contentions (valid only if debugLog)
	static bool debugHasInitialized;	// global: debug state set up
	static bool loggingMutexi;			// global: we are debug-logging mutexi
};

#elif _USE_THREADS == _USE_NO_THREADS

class Mutex {
public:
    void lock(bool = true) { }
    void unlock() { }
    bool tryLock() { return true; }
};

#else
# error Unsupported threading model
#endif //_USE_THREADS


//
// A CountingMutex adds a counter to a Mutex.
// NOTE: This is not officially a semaphore, even if it happens to be implemented with
//  one on some platforms.
//
class CountingMutex : public Mutex {
    // note that this implementation works for any system implementing Mutex *somehow*
public:
    CountingMutex() : mCount(0) { }
    ~CountingMutex() { assert(mCount == 0); }

    void enter();
    bool tryEnter();
    void exit();

    // these methods do not lock - use only while you hold the lock
    unsigned int count() const { return mCount; }
    bool isIdle() const { return mCount == 0; }

    // convert Mutex lock to CountingMutex enter/exit. Expert use only
    void finishEnter();
	void finishExit();
   
private:
    unsigned int mCount;
};
 

//
// A guaranteed-unlocker stack-based class.
// By default, this will use lock/unlock methods, but you can provide your own
// alternates (to, e.g., use enter/exit, or some more specialized pair of operations).
//
// NOTE: StLock itself is not thread-safe. It is intended for use (usually on the stack)
// by a single thread.
//
template <class Lock,
	void (Lock::*_lock)() = &Lock::lock,
	void (Lock::*_unlock)() = &Lock::unlock>
class StLock {
public:
	StLock(Lock &lck) : me(lck)			{ (me.*_lock)(); mActive = true; }
	StLock(Lock &lck, bool option) : me(lck), mActive(option) { }
	~StLock()							{ if (mActive) (me.*_unlock)(); }

	bool isActive() const				{ return mActive; }
	void lock()							{ if(!mActive) { (me.*_lock)(); mActive = true; }}
	void unlock()						{ if(mActive) { (me.*_unlock)(); mActive = false; }}
	void release()						{ assert(mActive); mActive = false; }

	operator const Lock &() const		{ return me; }
	
protected:
	Lock &me;
	bool mActive;
};


//
// Atomic increment/decrement operations.
// The default implementation uses a Mutex. However, many architectures can do
// much better than that.
// Be very clear on the nature of AtomicCounter. It implies no memory barriers of
// any kind. This means that (1) you cannot protect any other memory region with it
// (use a Mutex for that), and (2) it may not enforce cross-processor ordering, which
// means that you have no guarantee that you'll see modifications by other processors
// made earlier (unless another mechanism provides the memory barrier).
// On the other hand, if your compiler has brains, this is blindingly fast...
//
template <class Integer = int>
class StaticAtomicCounter {
protected:

#if defined(_HAVE_ATOMIC_OPERATIONS)
    AtomicWord mValue;
public:
    operator Integer() const	{ return mValue; }

    // infix versions (primary)
    Integer operator ++ ()		{ return atomicIncrement(mValue); }
    Integer operator -- ()		{ return atomicDecrement(mValue); }
    
    // postfix versions
    Integer operator ++ (int)	{ return atomicIncrement(mValue) - 1; }
    Integer operator -- (int)	{ return atomicDecrement(mValue) + 1; }

    // generic offset
    Integer operator += (int delta) { return atomicOffset(mValue, delta); }

#else // no atomic integers, use locks

    Integer mValue;
    mutable Mutex mLock;
public:
    StaticAtomicCounter(Integer init = 0) : mValue(init), mLock(false) { }
    operator Integer() const	{ StLock<Mutex> _(mLock); return mValue; }
    Integer operator ++ ()		{ StLock<Mutex> _(mLock); return ++mValue; }
    Integer operator -- ()		{ StLock<Mutex> _(mLock); return --mValue; }
    Integer operator ++ (int)	{ StLock<Mutex> _(mLock); return mValue++; }
    Integer operator -- (int)	{ StLock<Mutex> _(mLock); return mValue--; }
    Integer operator += (int delta) { StLock<Mutex> _(mLock); return mValue += delta; }
#endif
};


template <class Integer = int>
class AtomicCounter : public StaticAtomicCounter<Integer> {
public:
    AtomicCounter(Integer init = 0)	{ mValue = 0; }
};


//
// A class implementing a separate thread of execution.
// Do not expect many high-level semantics to be portable. If you can,
// restrict yourself to expect parallel execution and little else.
//
#if _USE_THREADS == _USE_PTHREADS

class Thread {
    NOCOPY(Thread)
public:
    class Identity {
        friend class Thread;
        
        Identity(pthread_t id) : mIdent(id) { }
    public:
        Identity() { }
        
        static Identity current()	{ return pthread_self(); }

        bool operator == (const Identity &other) const
        { return pthread_equal(mIdent, other.mIdent); }
        
        bool operator != (const Identity &other) const
        { return !(*this == other); }
        
		// visible thread identifiers are FOR DEBUGGING ONLY
		// if you use this for production code, your code will rot after shipment :-)
        static const int idLength = 10;
        static void getIdString(char id[idLength]);
    
    private:
        pthread_t mIdent;
    };

public:
    Thread() { }				// constructor
    virtual ~Thread();	 		// virtual destructor
    void run();					// begin running the thread
    
public:
	static void yield();		// unstructured short-term processor yield
    
protected:
    virtual void action() = 0; 	// the action to be performed

private:
    Identity self;				// my own identity (instance constant)

    static void *runner(void *); // argument to pthread_create
};

#elif _USE_THREADS == _USE_NO_THREADS

class Thread {
    NOCOPY(Thread)
public:
	Thread() { }				// constructor
    virtual ~Thread() { }		// virtual destructor
    void run() { action(); }	// just synchronously run the action
    
public:
    class Identity {
    public:
        static Identity current() { return Identity(); }
	
        bool operator == (const Identity &) const		{ return true; }	// all the same
        bool operator != (const Identity &) const		{ return false; }

#if !defined(NDEBUG)
        static const idLength = 9;
        static void getIdString(char id[idLength]) { memcpy(id, "nothread", idLength); }
#endif
        
    private:
        Identity() { }
    };
	
public:
	void yield() { assert(false); }

protected:
    virtual void action() = 0;	// implement action of thread
};

#else
# error Unsupported threading model
#endif


//
// A "just run this function in a thread" variant of Thread
//
class ThreadRunner : public Thread {
    typedef void Action();
public:
    ThreadRunner(Action *todo);

private:
    void action();
    Action *mAction;
};


//
// A NestingMutex allows recursive re-entry by the same thread.
// Some pthread implementations support this through a mutex attribute.
// OSX's doesn't, naturally. This implementation works on all pthread platforms.
//
class NestingMutex {
public:
    NestingMutex();
    
    void lock();
    bool tryLock();
    void unlock();

private:
    Mutex mLock;
    Mutex mWait;
    Thread::Identity mIdent;
    uint32 mCount;
};

} // end namespace Security

#endif //_H_THREADING