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