epicsThread.h

Go to the documentation of this file.

/*************************************************************************\
* Copyright (c) 2002 The University of Chicago, as Operator of Argonne
*     National Laboratory.
* Copyright (c) 2002 The Regents of the University of California, as
*     Operator of Los Alamos National Laboratory.
* Copyright (c) 2013 ITER Organization.
* SPDX-License-Identifier: EPICS
* EPICS BASE is distributed subject to a Software License Agreement found
* in file LICENSE that is included with this distribution.
\*************************************************************************/

#ifndef epicsThreadh
#define epicsThreadh

#include <stddef.h>

#include "libComAPI.h"

#ifdef __cplusplus
extern "C" {
#endif

typedef void (*EPICSTHREADFUNC)(void *parm);

#define epicsThreadPriorityMax          99
#define epicsThreadPriorityMin           0

/* some generic values */
#define epicsThreadPriorityLow          10
#define epicsThreadPriorityMedium       50
#define epicsThreadPriorityHigh         90

/* some iocCore specific values */
#define epicsThreadPriorityCAServerLow  20
#define epicsThreadPriorityCAServerHigh 40
#define epicsThreadPriorityScanLow      60
#define epicsThreadPriorityScanHigh     70
#define epicsThreadPriorityIocsh        91
#define epicsThreadPriorityBaseMax      91

typedef enum {
    epicsThreadStackSmall, epicsThreadStackMedium, epicsThreadStackBig
} epicsThreadStackSizeClass;

typedef enum {
    epicsThreadBooleanStatusFail, epicsThreadBooleanStatusSuccess
} epicsThreadBooleanStatus;

LIBCOM_API unsigned int epicsStdCall epicsThreadGetStackSize(
    epicsThreadStackSizeClass size);

typedef struct epicsThreadOSD *epicsThreadId;

typedef epicsThreadId epicsThreadOnceId;
#define EPICS_THREAD_ONCE_INIT 0

LIBCOM_API void epicsStdCall epicsThreadOnce(
    epicsThreadOnceId *id, EPICSTHREADFUNC, void *arg);

LIBCOM_API void epicsThreadRealtimeLock(void);

LIBCOM_API void epicsStdCall epicsThreadExitMain(void);

typedef struct epicsThreadOpts {
    unsigned int priority;
    unsigned int stackSize;
    unsigned int joinable;
} epicsThreadOpts;

#define EPICS_THREAD_OPTS_INIT { \
    epicsThreadPriorityLow, epicsThreadStackMedium, 0}

LIBCOM_API epicsThreadId epicsThreadCreateOpt (
    const char * name,
    EPICSTHREADFUNC funptr, void * parm,
    const epicsThreadOpts *opts );
LIBCOM_API epicsThreadId epicsStdCall epicsThreadCreate (
    const char * name, unsigned int priority, unsigned int stackSize,
    EPICSTHREADFUNC funptr,void * parm );
LIBCOM_API epicsThreadId epicsStdCall epicsThreadMustCreate (
    const char * name, unsigned int priority, unsigned int stackSize,
    EPICSTHREADFUNC funptr,void * parm );

/* This gets undefined in osdThread.h on VxWorks < 6.9 */
#define EPICS_THREAD_CAN_JOIN

LIBCOM_API void epicsThreadMustJoin(epicsThreadId id);
LIBCOM_API void epicsStdCall epicsThreadSuspendSelf(void);
LIBCOM_API void epicsStdCall epicsThreadResume(epicsThreadId id);
LIBCOM_API unsigned int epicsStdCall epicsThreadGetPriority(
    epicsThreadId id);
LIBCOM_API unsigned int epicsStdCall epicsThreadGetPrioritySelf(void);
LIBCOM_API void epicsStdCall epicsThreadSetPriority(
    epicsThreadId id,unsigned int priority);
LIBCOM_API epicsThreadBooleanStatus epicsStdCall
    epicsThreadHighestPriorityLevelBelow (
        unsigned int priority, unsigned *pPriorityJustBelow);
LIBCOM_API epicsThreadBooleanStatus epicsStdCall
    epicsThreadLowestPriorityLevelAbove (
        unsigned int priority, unsigned *pPriorityJustAbove);
LIBCOM_API int epicsStdCall epicsThreadIsEqual(
    epicsThreadId id1, epicsThreadId id2);
LIBCOM_API int epicsStdCall epicsThreadIsSuspended(epicsThreadId id);
LIBCOM_API void epicsStdCall epicsThreadSleep(double seconds);
LIBCOM_API double epicsStdCall epicsThreadSleepQuantum(void);
LIBCOM_API epicsThreadId epicsStdCall epicsThreadGetIdSelf(void);
LIBCOM_API epicsThreadId epicsStdCall epicsThreadGetId(const char *name);
LIBCOM_API int epicsThreadGetCPUs(void);

LIBCOM_API const char * epicsStdCall epicsThreadGetNameSelf(void);

LIBCOM_API void epicsStdCall epicsThreadGetName(
    epicsThreadId id, char *name, size_t size);

LIBCOM_API int epicsStdCall epicsThreadIsOkToBlock(void);
LIBCOM_API void epicsStdCall epicsThreadSetOkToBlock(int isOkToBlock);

LIBCOM_API void epicsStdCall epicsThreadShowAll(unsigned int level);
LIBCOM_API void epicsStdCall epicsThreadShow(
    epicsThreadId id,unsigned int level);

typedef void (*EPICS_THREAD_HOOK_ROUTINE)(epicsThreadId id);

LIBCOM_API int epicsThreadHookAdd(EPICS_THREAD_HOOK_ROUTINE hook);

LIBCOM_API int epicsThreadHookDelete(EPICS_THREAD_HOOK_ROUTINE hook);

LIBCOM_API void epicsThreadHooksShow(void);

LIBCOM_API void epicsThreadMap(EPICS_THREAD_HOOK_ROUTINE func);

typedef struct epicsThreadPrivateOSD * epicsThreadPrivateId;
LIBCOM_API epicsThreadPrivateId epicsStdCall epicsThreadPrivateCreate(void);
LIBCOM_API void epicsStdCall epicsThreadPrivateDelete(epicsThreadPrivateId id);
LIBCOM_API void epicsStdCall epicsThreadPrivateSet(epicsThreadPrivateId,void *);
LIBCOM_API void * epicsStdCall epicsThreadPrivateGet(epicsThreadPrivateId);

#ifdef __cplusplus
}
#endif

#ifdef __cplusplus

#include "epicsEvent.h"
#include "epicsMutex.h"

class LIBCOM_API epicsThreadRunable {
public:
    virtual ~epicsThreadRunable () = 0;
    virtual void run () = 0;
    virtual void show ( unsigned int level ) const;
};

extern "C" void epicsThreadCallEntryPoint ( void * );

class LIBCOM_API epicsThread {
public:
    epicsThread ( epicsThreadRunable &,const char *name, unsigned int stackSize,
        unsigned int priority=epicsThreadPriorityLow );
    ~epicsThread () throw ();
    void start () throw ();
    void exitWait () throw ();
    bool exitWait ( const double delay ) throw ();
    static void exit ();
    void resume () throw ();
    void getName ( char * name, size_t size ) const throw ();
    epicsThreadId getId () const throw ();
    unsigned int getPriority () const throw ();
    void setPriority ( unsigned int ) throw ();
    bool priorityIsEqual ( const epicsThread & ) const throw ();
    bool isSuspended () const throw ();
    bool isCurrentThread () const throw ();
    bool operator == ( const epicsThread & ) const throw ();
    void show ( unsigned level ) const throw ();

    /* these operate on the current thread */
    static void suspendSelf () throw ();
    static void sleep (double seconds) throw ();
    static const char * getNameSelf () throw ();
    static bool isOkToBlock () throw ();
    static void setOkToBlock ( bool isOkToBlock ) throw ();

    /* exceptions */
    class unableToCreateThread;
private:
    epicsThreadRunable & runable;
    epicsThreadId id;
    epicsMutex mutex;
    epicsEvent event;
    epicsEvent exitEvent;
    bool * pThreadDestroyed;
    bool begin;
    bool cancel;
    bool terminated;
    bool joined;

    bool beginWait () throw ();
    epicsThread ( const epicsThread & );
    epicsThread & operator = ( const epicsThread & );
    friend void epicsThreadCallEntryPoint ( void * );
    void printLastChanceExceptionMessage (
        const char * pExceptionTypeName,
        const char * pExceptionContext );
    /* exceptions */
    class exitException {};
};

class LIBCOM_API epicsThreadPrivateBase {
public:
    class unableToCreateThreadPrivate {}; /* exception */
protected:
    static void throwUnableToCreateThreadPrivate ();
};

template < class T >
class epicsThreadPrivate :
    private epicsThreadPrivateBase {
public:
    epicsThreadPrivate ();
    ~epicsThreadPrivate () throw ();
    T * get () const throw ();
    void set (T *) throw ();
private:
    epicsThreadPrivateId id;
};

#endif /* __cplusplus */

#include "osdThread.h"

#ifdef __cplusplus

template <class T>
inline epicsThreadPrivate<T>::epicsThreadPrivate ()
{
    this->id = epicsThreadPrivateCreate ();
    if ( this->id == 0 ) {
        epicsThreadPrivateBase::throwUnableToCreateThreadPrivate ();
    }
}

template <class T>
inline epicsThreadPrivate<T>::~epicsThreadPrivate () throw ()
{
    epicsThreadPrivateDelete ( this->id );
}

template <class T>
inline T *epicsThreadPrivate<T>::get () const throw ()
{
    return static_cast<T *> ( epicsThreadPrivateGet (this->id) );
}

template <class T>
inline void epicsThreadPrivate<T>::set (T *pIn) throw ()
{
    epicsThreadPrivateSet ( this->id, static_cast<void *> (pIn) );
}

#endif /* ifdef __cplusplus */

#endif /* epicsThreadh */