root/threadman/trunk/threadman.h

/* $Id$ $URL$ */
#ifndef THREADMAN_DOT_AITCH
#define THREADMAN_DOT_AITCH

/**\file threadman.h
 * Declaration of ThreadMan
 * \author Trent Apted <tapted@it.usyd.edu.au>
 * $Rev$
 * $Date$
 */

#include <vector>

//forward decs
class SyncThreads;
struct SDL_Thread;
struct SDL_mutex;

/** Singleton Manager for SDL Threads that we want to detach */
class ThreadMan {
public:
    /** Thread priorities. Note we do not support high priority -- it
     * needs root perms on Linux and screws around with Windows' crappy
     * round robin process scheduler.
     * Note also that on Windows, these are relative to the parent while
     * on POSIX they are absolute.
     */
    enum PRIORITY {
        INHERIT,      ///< Inherit from parent process
        NORMAL,       ///< Normal or nice(0)
        BELOW_NORMAL, ///< Below Normal or nice(5)
        LOW,          ///< Low or nice (10)
        IDLE          ///< Idle of nice(19)
    };
    typedef int (*THREAD)(void*); ///< Type for threads
    struct Runner; //forward dec

    ///\name Member Functions for running threads
    //@{
    /**
     * Run a thread and forget about it, to be cleaned on the next call to run(), if it has finished.
     *
     * \param fn The thread to run (like that passed to SDL_CreateThread)
     * \param data The data to pass to the thread
     * \param sync If true, use synchronised mode. In synchronised mode, only one thread exists for each distinct
     *             \a fn and we reuse it when each call finishes, rather than cleaning up. stopSync() will stop
     *             all threads started in this fashion (waiting for \a fn to finish if it is currently running).
     * \param pri The thread priority
     * \param thr if non-null this is assigned to the SDL_Thread that will (eventually) run the function
     */
    bool run(THREAD fn, void* data = 0, bool sync = false, PRIORITY pri = INHERIT, SDL_Thread **thr = 0);
    bool run(Runner *fn, void* data = 0, bool sync = false, PRIORITY pri = INHERIT, SDL_Thread **thr = 0);
    //@}

    /** Stop all synchronised threads (does not block) */
    void stopSync();
    /** Wait for all synchronised threads to finish (may block) */
    void joinSync();
    /** Stop asynchronous threads, wait for them to finish (may block) */
    void stopAsync();

    /** Return a reference to the singleton, creating it if it doesn't exist yet */
    static ThreadMan& tman();

    /**\name Static version of run() */
    //@{
    static bool srun(THREAD fn, void* data = 0, bool sync = false, PRIORITY pri = INHERIT, SDL_Thread **thr = 0) {
        return tman().run(fn, data, sync, pri, thr);
    }
    static bool srun(Runner *fn, void* data = 0, bool sync = false, PRIORITY pri = INHERIT, SDL_Thread **thr = 0) {
        return tman().run(fn, data, sync, pri, thr);
    }
    //@}

    /** Set the priority of *this* thread */
    static void setMyPriority(PRIORITY pri);
    /** Sleep this thread for X ms */
    static void sleep(unsigned ms);
    /** Get the thread ID */
    static int thread_id();

    ///\name Runner classes, for more flexible thread starting -- work in progress
    //@{
    /** Superclass runner */
    struct Runner {
        bool cleanup;
        explicit Runner(bool clean) : cleanup(clean) {}
        virtual int run(void* data) = 0;
        virtual bool operator==(const Runner &rhs) const = 0;
        virtual ~Runner() {}
    };
    /** Functor runner, taking any single pointer argument, returning something castable to int */
    template <class F, class Arg = void>
        struct F1Runner : public Runner {
            F f;
            F1Runner(const F& ff, bool clean = false) : Runner(clean), f(ff) {}
            virtual int run(void* data) {return static_cast<int>(f(static_cast<Arg*>(data)));}
            virtual bool operator==(const Runner &rhs) const {
                const F1Runner *r = dynamic_cast<const F1Runner*>(&rhs);
                return r && r->f == f;
            }
        };
    /** Functor runner, taking a no argument, returning something castable to int */
    template <class F>
        struct F0Runner : public Runner {
            F f;
            F0Runner(const F& ff, bool clean = false) : Runner(clean), f(ff) {}
            virtual int run(void* data) {return static_cast<int>(f());}
            virtual bool operator==(const Runner &rhs) const {
                const F0Runner *r = dynamic_cast<const F0Runner*>(&rhs);
                return r && r->f == f;
            }
        };
    /** Member function runner -- taking no argument (data is `this`), returning an int */
    template <class T, class Ret>
    struct MFRunner : public Runner {
        Ret (T::*f)();
        MFRunner(Ret (T::*mf)(), bool clean = false) : Runner(clean), f(mf) {}
        virtual int run(void* data) {return (static_cast<T*>(data)->*f)() ;}
        virtual bool operator==(const Runner &rhs) const {
            const MFRunner *r = dynamic_cast<const MFRunner*>(&rhs);
            return r && r->f == f;
        }
    };
    /** Match the member function runner */
    template <class T, class Ret>
    static Runner* runner(Ret (T::*func)() ) {
        return new MFRunner<T, Ret>(func);
    }
    /** Match no-arg runner for functions */
    template <class Ret>
    static Runner* runner(Ret (*func)() ) {
        return new F0Runner<Ret (*)()>(func);
    }
    /** Match 1-arg runner for functions */
    template <class Ret, class Arg>
    static Runner* runner(Ret (*func)(Arg*) ) {
        return new F1Runner<Ret (*)(Arg*), Arg>(func);
    }
    /** Match functors with no arguments */
    template <class F>
    static Runner* runner(const F& func) {
        return new F0Runner<F>(func);
    }
    /** Match functors with 1 argument -- needs a different name! */
    template <class Arg, class F>
    static Runner* runner1(const F& func) {
        return new F1Runner<F, Arg>(func);
    }
    //@}

    /** Constructor -- creates the mutex and syncman */
    ThreadMan();
    /** Destructor -- destroys mutex and syncman */
    ~ThreadMan();

private:
    /** Cleanup struct -- ThreadMan repeatedly calls done(); to ask if it is finished */
    struct ThreadKiller {
        SDL_Thread *thr;      ///< Handle on the thread
        bool finished;        ///< Set to true by the thread, when entry point returns

        /** Cleanup the thread, if we know we won't block, and return true */
        bool done();
        int wait();

        /** Constructor just copies the thread handle */
        ThreadKiller(SDL_Thread *t);
        /** Compare == if we handle the same thread */
        bool operator==(SDL_Thread *t);
    };

    typedef std::vector<ThreadKiller> THREADS; ///< type for managed threads

    THREADS threads;      ///< Managed threads
    SDL_mutex *thrmut;    ///< Mutex for accessing \a threads
    SyncThreads *syncman; ///< Synchronised threads

    /** Check for finished threads to Wait/Join */
    void thread_cleanup();

    ThreadMan& operator=(const ThreadMan& rhs); ///< No Assignment
    ThreadMan(const ThreadMan& rhs);            ///< No copy construction
public:
    /**\internal Indicate that we can now call SDL_WaitThread(\a t) without blocking */
    void thread_done(SDL_Thread *t);
    /**\internal Add a killer for \a t */
    void thread_add(SDL_Thread *t);
};

#endif