C++ and C descriptions for a thread. More...

#include <stddef.h>
#include "libComAPI.h"
#include "compilerDependencies.h"
#include "epicsEvent.h"
#include "epicsMutex.h"
#include "osdThread.h"

Include dependency graph for epicsThread.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	epicsThreadOpts

class	epicsThreadRunable
	Interface used with class epicsThread. More...

class	epicsThread
	An OS thread. More...

class	epicsThreadPrivateBase

class	epicsThreadPrivateBase::unableToCreateThreadPrivate

class	epicsThreadPrivate< T >

Macros
#define	EPICS_THREAD_ONCE_INIT 0

#define	EPICS_THREAD_OPTS_INIT

#define	EPICS_THREAD_CAN_JOIN

Some Named Thread Priorities
#define	epicsThreadPriorityMax 99

#define	epicsThreadPriorityMin 0

#define	epicsThreadPriorityLow 10

#define	epicsThreadPriorityMedium 50

#define	epicsThreadPriorityHigh 90

#define	epicsThreadPriorityCAServerLow 20

#define	epicsThreadPriorityCAServerHigh 40

#define	epicsThreadPriorityScanLow 60

#define	epicsThreadPriorityScanHigh 70

#define	epicsThreadPriorityIocsh 91

#define	epicsThreadPriorityBaseMax 91

Typedefs
typedef void(*	EPICSTHREADFUNC )(void *parm)

typedef epicsThreadId	epicsThreadOnceId

typedef void(*	EPICS_THREAD_HOOK_ROUTINE )(epicsThreadId id)

typedef struct epicsThreadPrivateOSD *	epicsThreadPrivateId

Enumerations
enum	epicsThreadStackSizeClass { epicsThreadStackSmall, epicsThreadStackMedium, epicsThreadStackBig }

enum	epicsThreadBooleanStatus { epicsThreadBooleanStatusFail, epicsThreadBooleanStatusSuccess }

Functions
LIBCOM_API unsigned int epicsStdCall	epicsThreadGetStackSize (epicsThreadStackSizeClass size)

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

LIBCOM_API void	epicsThreadRealtimeLock (void)

LIBCOM_API void epicsStdCall	epicsThreadExitMain (void) EPICS_DEPRECATED

LIBCOM_API epicsThreadId	epicsThreadCreateOpt (const char name, EPICSTHREADFUNC funptr, void parm, const epicsThreadOpts *opts)
	Allocate and start a new OS thread. More...

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)

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)
	Block the calling thread for at least the specified time. More...

LIBCOM_API double epicsStdCall	epicsThreadSleepQuantum (void)
	Query a value approximating the OS timer/scheduler resolution. More...

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)

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)

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)

void	epicsThreadCallEntryPoint (void *)

Detailed Description

The epicsThread API is meant as a somewhat minimal interface for multithreaded applications. It can be implemented on a wide variety of systems with the restriction that the system MUST support a multithreaded environment. A POSIX pthreads version is provided.

The interface provides the following thread facilities, with restrictions as noted:

Life cycle: a thread starts life as a result of a call to epicsThreadCreate. It terminates when the thread function returns. It should not return until it has released all resources it uses. If a thread is expected to terminate as a natural part of its life cycle then the thread function must return.
epicsThreadOnce: this provides the ability to have an initialization function that is guaranteed to be called exactly once.
main: if a main routine finishes its work but wants to leave other threads running it can call epicsThreadExitMain, which should be the last statement in main.
Priorities: ranges between 0 and 99 with a higher number meaning higher priority. A number of constants are defined for iocCore specific threads. The underlying implementation may collapse the range 0 to 99 into a smaller range; even a single priority. User code should never rely on the existence of multiple thread priorities to guarantee correct behavior.
Stack Size: epicsThreadCreate accepts a stack size parameter. Three generic sizes are available: small, medium,and large. Portable code should always use one of the generic sizes. Some implementation may ignore the stack size request and use a system default instead. Virtual memory systems providing generous stack sizes can be expected to use the system default.
epicsThreadId: every epicsThread has an Id which gets returned by epicsThreadCreate and is valid as long as that thread still exists. A value of 0 always means no thread. If a threadId is used after the thread has terminated,the results are not defined (but will normally lead to bad things happening). Thus code that looks after other threads MUST be aware of threads terminating.

Definition in file epicsThread.h.

Macro Definition Documentation

#define EPICS_THREAD_OPTS_INIT

Value:

{ \

epicsThreadPriorityLow, epicsThreadStackMedium, 0}

Default initial values for epicsThreadOpts Applications should always use this macro to initialize an epicsThreadOpts structure. Additional fields may be added in the future, and the order of the fields might also change, thus code that assumes the above definition might break if these rules are not followed.

Definition at line 173 of file epicsThread.h.

Typedef Documentation

typedef void(* EPICS_THREAD_HOOK_ROUTINE)(epicsThreadId id)

Hooks called when a thread starts, map function called once for every thread.

Definition at line 308 of file epicsThread.h.

typedef struct epicsThreadPrivateOSD* epicsThreadPrivateId

Thread local storage

Definition at line 334 of file epicsThread.h.

Enumeration Type Documentation

enum epicsThreadStackSizeClass

Stack sizes for each stackSizeClass are implementation and CPU dependent.

Definition at line 91 of file epicsThread.h.

Function Documentation

LIBCOM_API unsigned int epicsStdCall epicsThreadGetStackSize ( epicsThreadStackSizeClass size )

Get a stack size value that can be given to epicsThreadCreate().

Parameters

size	one of the values epicsThreadStackSmall, epicsThreadStackMedium or epicsThreadStackBig.

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

Perform one-time initialization.

Run the provided function if it has not run, and is not running in some other thread.

For each unique epicsThreadOnceId, epicsThreadOnce guarantees that

myInitFunc will only be called only once.
myInitFunc will have returned before any other epicsThreadOnce call using the same epicsThreadOnceId returns.

static epicsThreadOnceId onceId = EPICS_THREAD_ONCE_INIT;
static void myInitFunc(void *arg) { ... }
static void some Function(void) {
 epicsThreadOnce(&onceId, &myInitFunc, NULL);
}

LIBCOM_API void epicsThreadRealtimeLock ( void )

When real-time scheduling is active, attempt any post-init operations that preserve real-time performance. For POSIX targets this locks the process into RAM, preventing swap-related VM faults.

LIBCOM_API void epicsStdCall epicsThreadExitMain ( void )

If the main routine is done but wants to let other threads run it can call this routine. This should be the last call in main, except the final return. On most systems epicsThreadExitMain never returns.This must only be called by the main thread.

Deprecated:: Deprecated for lack of use. Please report any usage. Recommended replacement is loop + epicsThreadSleep(), epicsEventMustWait(), or similar.

LIBCOM_API epicsThreadId epicsThreadCreateOpt	(	const char *	name,
		EPICSTHREADFUNC	funptr,
		void *	parm,
		const epicsThreadOpts *	opts
	)

Parameters

name	A name describing this thread. Appears in various log and error message.
funptr	The thread main function.
parm	Passed to thread main function.
opts	Modifiers for the new thread, or NULL to use target specific defaults.

Returns: NULL on error

LIBCOM_API epicsThreadId epicsStdCall epicsThreadCreate	(	const char *	name,
		unsigned int	priority,
		unsigned int	stackSize,
		EPICSTHREADFUNC	funptr,
		void *	parm
	)

Short-hand for epicsThreadCreateOpt() to create an un-joinable thread.

LIBCOM_API epicsThreadId epicsStdCall epicsThreadMustCreate	(	const char *	name,
		unsigned int	priority,
		unsigned int	stackSize,
		EPICSTHREADFUNC	funptr,
		void *	parm
	)

Short-hand for epicsThreadCreateOpt() to create an un-joinable thread. On error calls cantProceed()

LIBCOM_API void epicsThreadMustJoin ( epicsThreadId id )

Wait for a joinable thread to exit (return from its main function)

LIBCOM_API void epicsStdCall epicsThreadSuspendSelf ( void )

Block the current thread until epicsThreadResume().

LIBCOM_API void epicsStdCall epicsThreadResume ( epicsThreadId id )

Resume a thread suspended with epicsThreadSuspendSelf()

LIBCOM_API unsigned int epicsStdCall epicsThreadGetPriority ( epicsThreadId id )

Return thread OSI priority

LIBCOM_API unsigned int epicsStdCall epicsThreadGetPrioritySelf ( void )

Return thread OSI priority

LIBCOM_API void epicsStdCall epicsThreadSetPriority	(	epicsThreadId	id,
		unsigned int	priority
	)

Change OSI priority of target thread.

LIBCOM_API epicsThreadBooleanStatus epicsStdCall epicsThreadHighestPriorityLevelBelow	(	unsigned int	priority,
		unsigned *	pPriorityJustBelow
	)

Lookup the next usage OSI priority such that priority > *pPriorityJustBelow if this is possible with the current target configuration and privlages.

LIBCOM_API epicsThreadBooleanStatus epicsStdCall epicsThreadLowestPriorityLevelAbove	(	unsigned int	priority,
		unsigned *	pPriorityJustAbove
	)

Lookup the next usage OSI priority such that priority < *pPriorityJustBelow if this is possible with the current target configuration and privlages.

LIBCOM_API int epicsStdCall epicsThreadIsEqual	(	epicsThreadId	id1,
		epicsThreadId	id2
	)

Test if two thread IDs actually refer to the same OS thread

LIBCOM_API int epicsStdCall epicsThreadIsSuspended ( epicsThreadId id )

How and why a thread can be suspended is implementation dependent. A thread calling epicsThreadSuspendSelf() should result in this routine returning true for that thread, but a thread may also be suspended for other reasons.

LIBCOM_API void epicsStdCall epicsThreadSleep ( double seconds )

Parameters

seconds Time to wait in seconds. Values <=0 blocks for the shortest possible time.

LIBCOM_API double epicsStdCall epicsThreadSleepQuantum ( void )

Returns: A value in seconds >=0

Warning: On targets other than vxWorks and RTEMS, the quantum value often isn't meaningful. Use of this function is discouraged in portable code.

LIBCOM_API epicsThreadId epicsStdCall epicsThreadGetIdSelf ( void )

Find an epicsThreadId associated with the current thread. For non-EPICS threads, a new epicsThreadId may be allocated.

LIBCOM_API epicsThreadId epicsStdCall epicsThreadGetId ( const char * name )

Attempt to find the first instance of a thread by name.

Returns: An epicsThreadId, or NULL if no such thread is currently running. Note that a non-NULL ID may still be invalid if this call races with thread exit.

Warning: Safe use of this function requires external knowledge that this thread will not return.

LIBCOM_API int epicsThreadGetCPUs ( void )

Return a value approximating the number of threads which this target can run in parallel. This value is advisory.

Returns: >=1

LIBCOM_API const char* epicsStdCall epicsThreadGetNameSelf ( void )

Return the name of the current thread.

Returns: Never NULL. Storage lifetime tied to epicsThreadId.

This is either a copy of the string passed to epicsThread*Create*(), or an arbitrary unique string for non-EPICS threads.

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

Copy out the thread name into the provided buffer.

Guaranteed to be null terminated. size is number of bytes in buffer to hold name (including terminator). Failure results in an empty string stored in name.

LIBCOM_API int epicsStdCall epicsThreadIsOkToBlock ( void )

Is it OK for a thread to block? This can be called by support code that does not know if it is called in a thread that should not block. For example the errlog system calls this to decide when messages should be displayed on the console.

LIBCOM_API void epicsStdCall epicsThreadSetOkToBlock ( int isOkToBlock )

When a thread is started the default is that it is not allowed to block. This method can be called to change the state. For example iocsh calls this to specify that it is OK to block.

LIBCOM_API void epicsStdCall epicsThreadShowAll ( unsigned int level )

Print to stdout information about all running EPICS threads.

Parameters

level 0 prints minimal output. Higher values print more details.

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

Print info about a single EPICS thread.

LIBCOM_API int epicsThreadHookAdd ( EPICS_THREAD_HOOK_ROUTINE hook )

Register a routine to be called by every new thread before the thread function gets run. Hook routines will often register a thread exit routine with epicsAtThreadExit() to release thread-specific resources they have allocated.

LIBCOM_API int epicsThreadHookDelete ( EPICS_THREAD_HOOK_ROUTINE hook )

Remove routine from the list of hooks run at thread creation time.

LIBCOM_API void epicsThreadHooksShow ( void )

Print the current list of hook function pointers.

LIBCOM_API void epicsThreadMap ( EPICS_THREAD_HOOK_ROUTINE func )

Call func once for every known thread.

LIBCOM_API epicsThreadPrivateId epicsStdCall epicsThreadPrivateCreate ( void )

Allocate a new thread local variable. This variable will initially hold NULL for each thread.

LIBCOM_API void epicsStdCall epicsThreadPrivateDelete ( epicsThreadPrivateId id )

Free a thread local variable

LIBCOM_API void epicsStdCall epicsThreadPrivateSet	(	epicsThreadPrivateId	,
		void *
	)

Update thread local variable

LIBCOM_API void* epicsStdCall epicsThreadPrivateGet ( epicsThreadPrivateId )

Fetch the current value of a thread local variable

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation