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"
#include "compilerDependencies.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) EPICS_DEPRECATED;

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 */