epicsThread.h File Reference

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

#include <stddef.h>
#include "libComAPI.h"
#include "osdThread.h"

Include dependency graph for epicsThread.h:

Go to the source code of this file.

Classes
struct	epicsThreadOpts

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 struct epicsThreadOSD *	epicsThreadId
typedef epicsThreadId	epicsThreadOnceId
typedef struct epicsThreadOpts	epicsThreadOpts
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)
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)

Detailed Description

C++ and C descriptions for a thread.

The epicsThread API is meant as a somewhat minimal interface for multithreaded applications. It can be implementedon 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_CAN_JOIN

Definition at line 193 of file epicsThread.h.

#define EPICS_THREAD_ONCE_INIT   0

Definition at line 109 of file epicsThread.h.

#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 167 of file epicsThread.h.

#define epicsThreadPriorityBaseMax   91

Definition at line 85 of file epicsThread.h.

#define epicsThreadPriorityCAServerHigh   40

Definition at line 81 of file epicsThread.h.

#define epicsThreadPriorityCAServerLow   20

Definition at line 80 of file epicsThread.h.

#define epicsThreadPriorityHigh   90

Definition at line 77 of file epicsThread.h.

#define epicsThreadPriorityIocsh   91

Definition at line 84 of file epicsThread.h.

#define epicsThreadPriorityLow   10

Definition at line 75 of file epicsThread.h.

#define epicsThreadPriorityMax   99

Definition at line 71 of file epicsThread.h.

#define epicsThreadPriorityMedium   50

Definition at line 76 of file epicsThread.h.

#define epicsThreadPriorityMin   0

Definition at line 72 of file epicsThread.h.

#define epicsThreadPriorityScanHigh   70

Definition at line 83 of file epicsThread.h.

#define epicsThreadPriorityScanLow   60

Definition at line 82 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 302 of file epicsThread.h.

typedef void(* EPICSTHREADFUNC) (void *parm)

Definition at line 66 of file epicsThread.h.

typedef struct epicsThreadOSD* epicsThreadId

(epicsThreadId)0 is guaranteed to be an invalid thread id

Definition at line 106 of file epicsThread.h.

typedef epicsThreadId epicsThreadOnceId

Definition at line 108 of file epicsThread.h.

typedef struct epicsThreadOpts epicsThreadOpts

For use with epicsThreadCreateOpt()

typedef struct epicsThreadPrivateOSD* epicsThreadPrivateId

Thread local storage

Definition at line 328 of file epicsThread.h.

Enumeration Type Documentation

enum epicsThreadBooleanStatus

Enumerator
epicsThreadBooleanStatusFail
epicsThreadBooleanStatusSuccess

Definition at line 93 of file epicsThread.h.

             {
    epicsThreadBooleanStatusFail, epicsThreadBooleanStatusSuccess
} epicsThreadBooleanStatus;

enum epicsThreadStackSizeClass

Stack sizes for each stackSizeClass are implementation and CPU dependent.

Enumerator
epicsThreadStackSmall
epicsThreadStackMedium
epicsThreadStackBig

Definition at line 89 of file epicsThread.h.

             {
    epicsThreadStackSmall, epicsThreadStackMedium, epicsThreadStackBig
} epicsThreadStackSizeClass;

Function Documentation

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.

Definition at line 33 of file epicsThread.cpp.

{
    epicsThreadOpts opts = EPICS_THREAD_OPTS_INIT;
    opts.priority = priority;
    opts.stackSize = stackSize;
    opts.joinable = 0;

    return epicsThreadCreateOpt(name, funptr, parm, &opts);
}

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

Allocate and start a new OS thread.

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

Definition at line 529 of file osdThread.c.

{
    unsigned int stackSize;
    epicsThreadOSD *pthreadInfo;
    int status;
    sigset_t blockAllSig, oldSig;

    epicsThreadInit();
    assert(pcommonAttr);

    if (!opts) {
        static const epicsThreadOpts opts_default = EPICS_THREAD_OPTS_INIT;
        opts = &opts_default;
    }
    stackSize = opts->stackSize;
    if (stackSize <= epicsThreadStackBig)
        stackSize = epicsThreadGetStackSize(stackSize);

    sigfillset(&blockAllSig);
    pthread_sigmask(SIG_SETMASK, &blockAllSig, &oldSig);

    pthreadInfo = init_threadInfo(name, opts->priority, stackSize, funptr,
        parm, opts->joinable);
    if (pthreadInfo==0)
        return 0;

    pthreadInfo->isEpicsThread = 1;
    setSchedulingPolicy(pthreadInfo, SCHED_FIFO);
    pthreadInfo->isRealTimeScheduled = 1;

    if (pthreadInfo->joinable) {
        /* extra ref for epicsThreadMustJoin() */
        epicsAtomicIncrIntT(&pthreadInfo->refcnt);
    }

    status = pthread_create(&pthreadInfo->tid, &pthreadInfo->attr,
        start_routine, pthreadInfo);
    if (status==EPERM) {
        /* Try again without SCHED_FIFO*/
        free_threadInfo(pthreadInfo);

        pthreadInfo = init_threadInfo(name, opts->priority, stackSize,
            funptr, parm, opts->joinable);
        if (pthreadInfo==0)
            return 0;

        pthreadInfo->isEpicsThread = 1;
        status = pthread_create(&pthreadInfo->tid, &pthreadInfo->attr,
            start_routine, pthreadInfo);
    }
    checkStatusOnce(status, "pthread_create");
    if (status) {
        if (pthreadInfo->joinable) {
            /* release extra ref which would have been for epicsThreadMustJoin() */
            epicsAtomicDecrIntT(&pthreadInfo->refcnt);
        }

        free_threadInfo(pthreadInfo);
        return 0;
    }

    status = pthread_sigmask(SIG_SETMASK, &oldSig, NULL);
    checkStatusOnce(status, "pthread_sigmask");
    return pthreadInfo;
}

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.

Definition at line 683 of file osdThread.c.

{
    epicsThreadOSD *pthreadInfo;

    epicsThreadInit();
    pthreadInfo = (epicsThreadOSD *)pthread_getspecific(getpthreadInfo);
    if(pthreadInfo==NULL)
        pthreadInfo = createImplicit();
    if(pthreadInfo->createFunc) {
        errlogPrintf("called from non-main thread\n");
        cantProceed("epicsThreadExitMain");
    }
    else {
    free_threadInfo(pthreadInfo);
    pthread_exit(0);
    }
}

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

Definition at line 990 of file osdThread.c.

{
    long ret;
#ifdef _SC_NPROCESSORS_ONLN
    ret = sysconf(_SC_NPROCESSORS_ONLN);
    if (ret > 0)
        return ret;
#endif
#ifdef _SC_NPROCESSORS_CONF
    ret = sysconf(_SC_NPROCESSORS_CONF);
    if (ret > 0)
        return ret;
#endif
    return 1;
}

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.

Definition at line 826 of file osdThread.c.

                                                                         {
    epicsThreadOSD *pthreadInfo;
    int status;

    assert(epicsThreadOnceCalled);
    status = mutexLock(&listLock);
    checkStatus(status,"pthread_mutex_lock epicsThreadGetId");
    if(status)
        return NULL;
    pthreadInfo=(epicsThreadOSD *)ellFirst(&pthreadList);
    while(pthreadInfo) {
    if(strcmp(name,pthreadInfo->name) == 0) break;
        pthreadInfo=(epicsThreadOSD *)ellNext(&pthreadInfo->node);
    }
    status = pthread_mutex_unlock(&listLock);
    checkStatus(status,"pthread_mutex_unlock epicsThreadGetId");

    return(pthreadInfo);
}

LIBCOM_API epicsThreadId epicsStdCall epicsThreadGetIdSelf

(

void

)

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

Definition at line 810 of file osdThread.c.

                                                                 {
    epicsThreadOSD *pthreadInfo;

    epicsThreadInit();
    pthreadInfo = (epicsThreadOSD *)pthread_getspecific(getpthreadInfo);
    if(pthreadInfo==NULL)
        pthreadInfo = createImplicit();
    assert ( pthreadInfo );
    return(pthreadInfo);
}

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.

Definition at line 857 of file osdThread.c.

{
    assert(epicsThreadOnceCalled);
    strncpy(name, pthreadInfo->name, size-1);
    name[size-1] = '\0';
}

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.

Definition at line 846 of file osdThread.c.

{
    epicsThreadOSD *pthreadInfo;

    epicsThreadInit();
    pthreadInfo = (epicsThreadOSD *)pthread_getspecific(getpthreadInfo);
    if(pthreadInfo==NULL)
        pthreadInfo = createImplicit();
    return(pthreadInfo->name);
}

LIBCOM_API unsigned int epicsStdCall epicsThreadGetPriority

(

epicsThreadId

id

)

Return thread OSI priority

Definition at line 701 of file osdThread.c.

{
    assert(epicsThreadOnceCalled);
    return(pthreadInfo->osiPriority);
}

LIBCOM_API unsigned int epicsStdCall epicsThreadGetPrioritySelf

(

void

)

Return thread OSI priority

Definition at line 707 of file osdThread.c.

{
    epicsThreadInit();
    return(epicsThreadGetPriority(epicsThreadGetIdSelf()));
}

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.

Definition at line 466 of file osdThread.c.

{
#if defined (OSITHREAD_USE_DEFAULT_STACK)
    return 0;
#elif defined(_POSIX_THREAD_ATTR_STACKSIZE) && _POSIX_THREAD_ATTR_STACKSIZE > 0
    if (stackSizeClass<epicsThreadStackSmall) {
        errlogPrintf("epicsThreadGetStackSize illegal argument (too small)");
        return stackSizeTable[epicsThreadStackBig];
    }

    if (stackSizeClass>epicsThreadStackBig) {
        errlogPrintf("epicsThreadGetStackSize illegal argument (too large)");
        return stackSizeTable[epicsThreadStackBig];
    }

    return stackSizeTable[stackSizeClass];
#else
    return 0;
#endif /*_POSIX_THREAD_ATTR_STACKSIZE*/
}

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.

Definition at line 740 of file osdThread.c.

{
    unsigned newPriority = priority - 1;
#if defined(_POSIX_THREAD_PRIORITY_SCHEDULING) && _POSIX_THREAD_PRIORITY_SCHEDULING > 0
    int diff;
    diff = pcommonAttr->maxPriority - pcommonAttr->minPriority;
    if(diff<0) diff = -diff;
    if(diff>1 && diff <100) newPriority -=  100/(diff+1);
#endif /* _POSIX_THREAD_PRIORITY_SCHEDULING */
    if (newPriority <= 99) {
        *pPriorityJustBelow = newPriority;
        return epicsThreadBooleanStatusSuccess;
    }
    return epicsThreadBooleanStatusFail;
}

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.

Definition at line 54 of file osdThreadHooks.c.

{
    epicsThreadHook *pHook;

    if (!hook) return 0;
    threadHookInit();

    pHook = calloc(1, sizeof(epicsThreadHook));
    if (!pHook) {
        fprintf(stderr, "epicsThreadHookAdd: calloc failed\n");
        return -1;
    }
    pHook->func = hook;

    if (epicsMutexLock(hookLock) == epicsMutexLockOK) {
        ellAdd(&hookList, &pHook->node);
        epicsMutexUnlock(hookLock);
        return 0;
    }
    fprintf(stderr, "epicsThreadHookAdd: Locking problem\n");
    return -1;
}

LIBCOM_API int epicsThreadHookDelete

(

EPICS_THREAD_HOOK_ROUTINE

hook

)

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

Definition at line 77 of file osdThreadHooks.c.

{
    if (!hook) return 0;
    threadHookInit();

    if (epicsMutexLock(hookLock) == epicsMutexLockOK) {
        epicsThreadHook *pHook = (epicsThreadHook *) ellFirst(&hookList);

        while (pHook) {
            if (hook == pHook->func) {
                ellDelete(&hookList, &pHook->node);
                break;
            }
            pHook = (epicsThreadHook *) ellNext(&pHook->node);
        }
        epicsMutexUnlock(hookLock);
        return 0;
    }
    fprintf(stderr, "epicsThreadHookAdd: Locking problem\n");
    return -1;
}

LIBCOM_API void epicsThreadHooksShow

(

void

)

Print the current list of hook function pointers.

Definition at line 123 of file osdThreadHooks.c.

{
    threadHookInit();

    if (epicsMutexLock(hookLock) == epicsMutexLockOK) {
        epicsThreadHook *pHook = (epicsThreadHook *) ellFirst(&hookList);

        while (pHook) {
            printf("  %p\n", pHook->func);
            pHook = (epicsThreadHook *) ellNext(&pHook->node);
        }
        epicsMutexUnlock(hookLock);
    }
    else {
        fprintf(stderr, "epicsThreadHooksShow: Locking problem\n");
    }
}

LIBCOM_API int epicsStdCall epicsThreadIsEqual	(	epicsThreadId	id1,
		epicsThreadId	id2
	)

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

Definition at line 776 of file osdThread.c.

{
    assert(epicsThreadOnceCalled);
    assert(p1);
    assert(p2);
    return(pthread_equal(p1->tid,p2->tid));
}

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.

Definition at line 358 of file epicsThread.cpp.

    {
        const int *pokToBlock;
        epicsThreadOnce(&okToBlockOnce, epicsThreadOnceIdInit, NULL);
        pokToBlock = (int *) epicsThreadPrivateGet(okToBlockPrivate);
        return (pokToBlock ? *pokToBlock : 0);
    }

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.

Definition at line 784 of file osdThread.c.

                                                                              {
    assert(epicsThreadOnceCalled);
    assert(pthreadInfo);
    return(pthreadInfo->isSuspended ? 1 : 0);
}

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.

Definition at line 757 of file osdThread.c.

{
    unsigned newPriority = priority + 1;

#if defined(_POSIX_THREAD_PRIORITY_SCHEDULING) && _POSIX_THREAD_PRIORITY_SCHEDULING > 0
    int diff;
    diff = pcommonAttr->maxPriority - pcommonAttr->minPriority;
    if(diff<0) diff = -diff;
    if(diff>1 && diff <100) newPriority += 100/(diff+1);
#endif /* _POSIX_THREAD_PRIORITY_SCHEDULING */

    if (newPriority <= 99) {
        *pPriorityJustAbove = newPriority;
        return epicsThreadBooleanStatusSuccess;
    }
    return epicsThreadBooleanStatusFail;
}

LIBCOM_API void epicsThreadMap

(

EPICS_THREAD_HOOK_ROUTINE

func

)

Call func once for every known thread.

Definition at line 864 of file osdThread.c.

{
    epicsThreadOSD *pthreadInfo;
    int status;

    epicsThreadInit();
    status = mutexLock(&listLock);
    checkStatus(status, "pthread_mutex_lock epicsThreadMap");
    if (status)
        return;
    pthreadInfo=(epicsThreadOSD *)ellFirst(&pthreadList);
    while (pthreadInfo) {
        func(pthreadInfo);
        pthreadInfo = (epicsThreadOSD *)ellNext(&pthreadInfo->node);
    }
    status = pthread_mutex_unlock(&listLock);
    checkStatus(status, "pthread_mutex_unlock epicsThreadMap");
}

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()

Definition at line 374 of file epicsThread.cpp.

    {
        epicsThreadId id = epicsThreadCreate (
            name, priority, stackSize, funptr, parm );
        assert ( id );
        return id;
    }

LIBCOM_API void epicsThreadMustJoin

(

epicsThreadId

id

)

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

Definition at line 632 of file osdThread.c.

{
    void *ret = NULL;
    int status;

    if(!id) {
        return;
    } else if(epicsAtomicCmpAndSwapIntT(&id->joinable, 1, 0)!=1) {
        if(epicsThreadGetIdSelf()==id) {
            errlogPrintf("Warning: %s thread self-join of unjoinable\n", id->name);

        } else {
            /* try to error nicely, however in all likelyhood de-ref of
             * 'id' has already caused SIGSEGV as we are racing thread exit,
             * which free's 'id'.
             */
            cantProceed("Error: %s thread not joinable.\n", id->name);
        }
        return;
    }

    status = pthread_join(id->tid, &ret);
    if(status == EDEADLK) {
        /* Thread can't join itself (directly or indirectly)
         * so we detach instead.
         */
        status = pthread_detach(id->tid);
        checkStatusOnce(status, "pthread_detach");
    } else checkStatusOnce(status, "pthread_join");
    free_threadInfo(id);
}

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

1. myInitFunc will only be called only once.
2. 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 epicsThreadPrivateId epicsStdCall epicsThreadPrivateCreate

(

void

)

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

Definition at line 934 of file osdThread.c.

{
    pthread_key_t *key;
    int status;

    epicsThreadInit();
    key = calloc(1,sizeof(pthread_key_t));
    if(!key)
        return NULL;
    status = pthread_key_create(key,0);
    checkStatus(status,"pthread_key_create epicsThreadPrivateCreate");
    if(status)
        return NULL;
    return((epicsThreadPrivateId)key);
}

LIBCOM_API void epicsStdCall epicsThreadPrivateDelete

(

epicsThreadPrivateId

id

)

Free a thread local variable

Definition at line 950 of file osdThread.c.

{
    pthread_key_t *key = (pthread_key_t *)id;
    int status;

    assert(epicsThreadOnceCalled);
    status = pthread_key_delete(*key);
    checkStatusQuit(status,"pthread_key_delete","epicsThreadPrivateDelete");
    free((void *)key);
}

LIBCOM_API void* epicsStdCall epicsThreadPrivateGet

(

epicsThreadPrivateId

)

Fetch the current value of a thread local variable

Definition at line 973 of file osdThread.c.

{
    pthread_key_t *key = (pthread_key_t *)id;

    assert(epicsThreadOnceCalled);
    return pthread_getspecific(*key);
}

LIBCOM_API void epicsStdCall epicsThreadPrivateSet	(	epicsThreadPrivateId	,
		void *
	)

Update thread local variable

Definition at line 961 of file osdThread.c.

{
    pthread_key_t *key = (pthread_key_t *)id;
    int status;

    assert(epicsThreadOnceCalled);
    if(errVerbose && !value)
        errlogPrintf("epicsThreadPrivateSet: setting value of 0\n");
    status = pthread_setspecific(*key,value);
    checkStatusQuit(status,"pthread_setspecific","epicsThreadPrivateSet");
}

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.

Definition at line 425 of file osdThread.c.

{
#if defined(_POSIX_MEMLOCK) && _POSIX_MEMLOCK > 0
    if (pcommonAttr->maxPriority > pcommonAttr->minPriority) {
        int status = mlockall(MCL_CURRENT | MCL_FUTURE);

        if (status) {
            const int err = errno;
            switch(err) {
#ifdef __linux__
            case ENOMEM:
                fprintf(stderr, "epicsThreadRealtimeLock "
                        "Warning: unable to lock memory.  RLIMIT_MEMLOCK is too small or missing CAP_IPC_LOCK\n");
                break;
            case EPERM:
                fprintf(stderr, "epicsThreadRealtimeLock "
                                "Warning: unable to lock memory.  missing CAP_IPC_LOCK\n");
                break;
#endif
            default:
                fprintf(stderr, "epicsThreadRealtimeLock "
                                "Warning: Unable to lock the virtual address space.\n"
                                "VM page faults may harm real-time performance. errno=%d\n",
                        err);
            }
        }
    }
#endif
}

LIBCOM_API void epicsStdCall epicsThreadResume

(

epicsThreadId

id

)

Resume a thread suspended with epicsThreadSuspendSelf()

Definition at line 423 of file osdThread.c.

{
    rtems_id tid = (rtems_id)id;
    rtems_status_code sc;

    sc = rtems_task_resume (tid);
    if (sc != RTEMS_SUCCESSFUL)
        errlogPrintf("epicsThreadResume failed: %s\n",
            rtems_status_text (sc));
}

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.

Definition at line 366 of file epicsThread.cpp.

    {
        const int *pokToBlock;
        epicsThreadOnce(&okToBlockOnce, epicsThreadOnceIdInit, NULL);
        pokToBlock = (isOkToBlock) ? &okToBlockYes : &okToBlockNo;
        epicsThreadPrivateSet(okToBlockPrivate, (void *)pokToBlock);
    }

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

Change OSI priority of target thread.

Definition at line 713 of file osdThread.c.

{
#if defined(_POSIX_THREAD_PRIORITY_SCHEDULING) && _POSIX_THREAD_PRIORITY_SCHEDULING > 0
    int status;
#endif /* _POSIX_THREAD_PRIORITY_SCHEDULING */

    assert(epicsThreadOnceCalled);
    assert(pthreadInfo);
    if(!pthreadInfo->isEpicsThread) {
        fprintf(stderr,"epicsThreadSetPriority called by non epics thread\n");
        return;
    }
    pthreadInfo->osiPriority = priority;
    if(!pthreadInfo->isRealTimeScheduled) return;

#if defined (_POSIX_THREAD_PRIORITY_SCHEDULING) && _POSIX_THREAD_PRIORITY_SCHEDULING > 0
    if(!pcommonAttr->usePolicy) return;
    pthreadInfo->schedParam.sched_priority = epicsThreadGetPosixPriority(pthreadInfo);
    status = pthread_attr_setschedparam(
        &pthreadInfo->attr,&pthreadInfo->schedParam);
    if(errVerbose) checkStatus(status,"pthread_attr_setschedparam");
    status = pthread_setschedparam(
        pthreadInfo->tid, pthreadInfo->schedPolicy, &pthreadInfo->schedParam);
    if(errVerbose) checkStatus(status,"pthread_setschedparam");
#endif /* _POSIX_THREAD_PRIORITY_SCHEDULING */
}

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

Print info about a single EPICS thread.

Definition at line 903 of file osdThread.c.

{
    epicsThreadOSD *pthreadInfo;
    int status;
    int found = 0;

    epicsThreadInit();
    if(!showThread) {
        epicsThreadShowInfo(0,level);
        return;
    }
    status = mutexLock(&listLock);
    checkStatus(status,"pthread_mutex_lock epicsThreadShowAll");
    if(status)
        return;
    pthreadInfo=(epicsThreadOSD *)ellFirst(&pthreadList);
    while(pthreadInfo) {
        if (((epicsThreadId)pthreadInfo == showThread)
         || ((epicsThreadId)pthreadInfo->tid == showThread)) {
            found = 1;
            epicsThreadShowInfo(pthreadInfo,level);
        }
        pthreadInfo=(epicsThreadOSD *)ellNext(&pthreadInfo->node);
    }
    status = pthread_mutex_unlock(&listLock);
    checkStatus(status,"pthread_mutex_unlock epicsThreadShowAll");
    if(status) return;
    if (!found)
        printf("Thread %#lx (%lu) not found.\n", (unsigned long)showThread, (unsigned long)showThread);
}

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.

Definition at line 883 of file osdThread.c.

{
    epicsThreadOSD *pthreadInfo;
    int status;

    epicsThreadInit();
    epicsThreadShow(0,level);
    status = mutexLock(&listLock);
    checkStatus(status,"pthread_mutex_lock epicsThreadShowAll");
    if(status)
        return;
    pthreadInfo=(epicsThreadOSD *)ellFirst(&pthreadList);
    while(pthreadInfo) {
        epicsThreadShowInfo(pthreadInfo,level);
        pthreadInfo=(epicsThreadOSD *)ellNext(&pthreadInfo->node);
    }
    status = pthread_mutex_unlock(&listLock);
    checkStatus(status,"pthread_mutex_unlock epicsThreadShowAll");
}

LIBCOM_API void epicsStdCall epicsThreadSleep

(

double

seconds

)

Block the calling thread for at least the specified time.

Parameters

seconds

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

Definition at line 790 of file osdThread.c.

{
    struct timespec delayTime;
    struct timespec remainingTime;
    double nanoseconds;

    if (seconds > 0) {
        delayTime.tv_sec = seconds;
        nanoseconds = (seconds - delayTime.tv_sec) *1e9;
        delayTime.tv_nsec = nanoseconds;
    }
    else {
        delayTime.tv_sec = 0;
        delayTime.tv_nsec = 0;
    }
    while (nanosleep(&delayTime, &remainingTime) == -1 &&
           errno == EINTR)
        delayTime = remainingTime;
}

LIBCOM_API double epicsStdCall epicsThreadSleepQuantum

(

void

)

Query a value approximating the OS timer/scheduler resolution.

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.

Definition at line 981 of file osdThread.c.

{
    double hz;
    hz = sysconf ( _SC_CLK_TCK );
    if(hz<=0)
        return 0.0;
    return 1.0 / hz;
}

LIBCOM_API void epicsStdCall epicsThreadSuspendSelf

(

void

)

Block the current thread until epicsThreadResume().

Definition at line 664 of file osdThread.c.

{
    epicsThreadOSD *pthreadInfo;

    epicsThreadInit();
    pthreadInfo = (epicsThreadOSD *)pthread_getspecific(getpthreadInfo);
    if(pthreadInfo==NULL)
        pthreadInfo = createImplicit();
    pthreadInfo->isSuspended = 1;
    epicsEventWait(pthreadInfo->suspendEvent);
}