osdThread.c File Reference

#include <stddef.h>
#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <limits.h>
#include <vxWorks.h>
#include <taskLib.h>
#include <taskVarLib.h>
#include <sysLib.h>
#include "errlog.h"
#include "ellLib.h"
#include "epicsThread.h"
#include "cantProceed.h"
#include "epicsAssert.h"
#include "vxLib.h"
#include "epicsExit.h"

Include dependency graph for osdThread.c:

Go to the source code of this file.

Classes
struct	epicsThreadOSD

Macros
#define	_VSB_CONFIG_FILE   <../lib/h/config/vsbConfig.h>
#define	ALLOT_JOIN(tid)
#define	ARCH_STACK_FACTOR   1
#define	ID_LIST_CHUNK   512
#define	THREAD_SEM_FLAGS   (SEM_DELETE_SAFE|SEM_INVERSION_SAFE|SEM_Q_PRIORITY)
#define	EPICS_THREAD_ONCE_DONE   &threadOnceComplete
#define	PREPARE_JOIN(tid, joinable)
#define	AWAIT_JOIN(tid)
#define	TASK_FLAGS   (VX_FP_TASK)

Functions
LIBCOM_API void	osdThreadHooksRun (epicsThreadId id)
void	atRebootRegister (void)
void	epicsThreadRealtimeLock (void)
unsigned int	epicsThreadGetStackSize (epicsThreadStackSizeClass stackSizeClass)
void	epicsThreadOnce (epicsThreadOnceId *id, void(*func)(void *), void *arg)
void	epicsThreadEntry (EPICSTHREADFUNC func, void *parm)
epicsThreadId	epicsThreadCreateOpt (const char *name, EPICSTHREADFUNC funptr, void *parm, const epicsThreadOpts *opts)
	Allocate and start a new OS thread. More...
void	epicsThreadMustJoin (epicsThreadId id)
void	epicsThreadSuspendSelf ()
void	epicsThreadResume (epicsThreadId id)
void	epicsThreadExitMain (void)
unsigned int	epicsThreadGetPriority (epicsThreadId id)
unsigned int	epicsThreadGetPrioritySelf (void)
void	epicsThreadSetPriority (epicsThreadId id, unsigned int osip)
epicsThreadBooleanStatus	epicsThreadHighestPriorityLevelBelow (unsigned int priority, unsigned *pPriorityJustBelow)
epicsThreadBooleanStatus	epicsThreadLowestPriorityLevelAbove (unsigned int priority, unsigned *pPriorityJustAbove)
int	epicsThreadIsEqual (epicsThreadId id1, epicsThreadId id2)
int	epicsThreadIsSuspended (epicsThreadId id)
void	epicsThreadSleep (double seconds)
	Block the calling thread for at least the specified time. More...
epicsThreadId	epicsThreadGetIdSelf (void)
epicsThreadId	epicsThreadGetId (const char *name)
const char *	epicsThreadGetNameSelf (void)
void	epicsThreadGetName (epicsThreadId id, char *name, size_t size)
LIBCOM_API void	epicsThreadMap (EPICS_THREAD_HOOK_ROUTINE func)
void	epicsThreadShowAll (unsigned int level)
void	epicsThreadShow (epicsThreadId id, unsigned int level)
epicsThreadPrivateId	epicsThreadPrivateCreate ()
void	epicsThreadPrivateDelete (epicsThreadPrivateId id)
void	epicsThreadPrivateSet (epicsThreadPrivateId id, void *pvt)
void *	epicsThreadPrivateGet (epicsThreadPrivateId id)
double	epicsThreadSleepQuantum ()
	Query a value approximating the OS timer/scheduler resolution. More...
LIBCOM_API int	epicsThreadGetCPUs (void)

Variables
int	taskIdListSize = 0

Macro Definition Documentation

#define _VSB_CONFIG_FILE   <../lib/h/config/vsbConfig.h>

Definition at line 15 of file osdThread.c.

#define ALLOT_JOIN

(

tid

)

Definition at line 49 of file osdThread.c.

#define ARCH_STACK_FACTOR   1

Definition at line 56 of file osdThread.c.

#define AWAIT_JOIN

(

tid

)

Definition at line 226 of file osdThread.c.

#define EPICS_THREAD_ONCE_DONE   &threadOnceComplete

#define ID_LIST_CHUNK   512

Definition at line 66 of file osdThread.c.

#define PREPARE_JOIN	(		tid,
			joinable
	)

Definition at line 225 of file osdThread.c.

#define TASK_FLAGS   (VX_FP_TASK)

Definition at line 251 of file osdThread.c.

#define THREAD_SEM_FLAGS   (SEM_DELETE_SAFE|SEM_INVERSION_SAFE|SEM_Q_PRIORITY)

Definition at line 108 of file osdThread.c.

Function Documentation

void atRebootRegister

(

void

)

Definition at line 22 of file atReboot.cpp.

{
    sysAtReboot_t sysAtReboot = (sysAtReboot_t) epicsFindSymbol("_sysAtReboot");

    if (sysAtReboot) {
        STATUS status = sysAtReboot(epicsExitCallAtExits);

        if (status) {
            printf("atReboot: sysAtReboot returned error %d\n", status);
        }
    } else {
        printf("BSP routine sysAtReboot() not found, epicsExit() will not be\n"
               "called by reboot.  For reduced functionality, call\n"
               "    rebootHookAdd(epicsExitCallAtExits)\n");
    }
}

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 253 of file osdThread.c.

{
    unsigned int stackSize;
    int tid;

    epicsThreadInit();

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

    if (stackSize < 100) {
        errlogPrintf("epicsThreadCreate %s illegal stackSize %d\n",
            name, stackSize);
        return 0;
    }

    tid = taskCreate((char *)name,getOssPriorityValue(opts->priority),
        TASK_FLAGS, stackSize,
        (FUNCPTR)epicsThreadEntry, (int)funptr, (int)parm,
        0,0,0,0,0,0,0,0);
    if (tid == ERROR) {
        errlogPrintf("epicsThreadCreate %s failure %s\n",
            name, strerror(errno));
        return 0;
    }

    PREPARE_JOIN(tid, opts->joinable);
    taskActivate(tid);

    return (epicsThreadId)tid;
}

void epicsThreadEntry	(	EPICSTHREADFUNC	func,
		void *	parm
	)

Definition at line 230 of file osdThread.c.

{
    int tid = taskIdSelf();

    taskVarAdd(tid,(int *)(char *)&papTSD);
    papTSD = NULL; /* Initialize for this thread */

    osdThreadHooksRun((epicsThreadId)tid);

    (*func)(parm);

    epicsExitCallAtThreadExits ();
    free(papTSD);
    taskVarDelete(tid,(int *)(char *)&papTSD);

    AWAIT_JOIN(tid);
}

void 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 353 of file osdThread.c.

{
    errlogPrintf("epicsThreadExitMain was called for vxWorks. Why?\n");
}

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 574 of file osdThread.c.

{
    return 1;
}

epicsThreadId 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 442 of file osdThread.c.

{
    int tid = taskNameToId((char *)name);
    return((epicsThreadId)(tid==ERROR?0:tid));
}

epicsThreadId epicsThreadGetIdSelf

(

void

)

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

Definition at line 437 of file osdThread.c.

{
    return((epicsThreadId)taskIdSelf());
}

void 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 453 of file osdThread.c.

{
    int tid = (int)id;
    strncpy(name,taskName(tid),size-1);
    name[size-1] = '\0';
}

const char* 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 448 of file osdThread.c.

{
    return taskName(taskIdSelf());
}

unsigned int epicsThreadGetPriority

(

epicsThreadId

id

)

Return thread OSI priority

Definition at line 358 of file osdThread.c.

{
    int tid = (int)id;
    STATUS status;
    int priority = 0;

    status = taskPriorityGet(tid,&priority);
    if(status) errlogPrintf("epicsThreadGetPriority failed\n");
    return(getOsiPriorityValue(priority));
}

unsigned int epicsThreadGetPrioritySelf

(

void

)

Return thread OSI priority

Definition at line 369 of file osdThread.c.

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

unsigned int 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 137 of file osdThread.c.

{

    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];
}

epicsThreadBooleanStatus 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 385 of file osdThread.c.

{
    unsigned newPriority = priority - 1;
    if (newPriority <= 99) {
        *pPriorityJustBelow = newPriority;
        return epicsThreadBooleanStatusSuccess;
    }
    return epicsThreadBooleanStatusFail;
}

int epicsThreadIsEqual	(	epicsThreadId	id1,
		epicsThreadId	id2
	)

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

Definition at line 409 of file osdThread.c.

{
    return((id1==id2) ? 1 : 0);
}

int 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 414 of file osdThread.c.

{
    int tid = (int)id;
    return((int)taskIsSuspended(tid));
}

epicsThreadBooleanStatus 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 396 of file osdThread.c.

{
    unsigned newPriority = priority + 1;

    newPriority = priority + 1;
    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 460 of file osdThread.c.

{
    int noTasks = 0;
    int i;
    int result;

    result = semTake(epicsThreadListMutex, WAIT_FOREVER);
    assert(result == OK);
    while (noTasks == 0) {
        noTasks = taskIdListGet(taskIdList, taskIdListSize);
        if (noTasks == taskIdListSize) {
            taskIdList = realloc(taskIdList, (taskIdListSize+ID_LIST_CHUNK)*sizeof(int));
            assert(taskIdList);
            taskIdListSize += ID_LIST_CHUNK;
            noTasks = 0;
        }
    }
    for (i = 0; i < noTasks; i++) {
        func ((epicsThreadId)taskIdList[i]);
    }
    semGive(epicsThreadListMutex);
}

void epicsThreadMustJoin

(

epicsThreadId

id

)

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

Definition at line 291 of file osdThread.c.

{
#ifdef EPICS_THREAD_CAN_JOIN
    const char *fn = "epicsThreadMustJoin";
    int tid = (int) id;
    SEM_ID joinSem;
    STATUS status;

    if (!tid)
        return;

    joinSem = (SEM_ID) taskSpareFieldGet(tid, joinField);
    if ((int) joinSem == ERROR) {
        errlogPrintf("%s: Thread %#x no longer exists.\n", fn, tid);
        return;
    }

    if (tid == taskIdSelf()) {
        if (joinSem) {
            taskSpareFieldSet(tid, joinField, 0);
            semDelete(joinSem);
        }
        else {
            errlogPrintf("%s: Thread '%s' (%#x) can't self-join.\n",
                fn, epicsThreadGetNameSelf(), tid);
        }
        return;
    }

    if (!joinSem) {
        cantProceed("%s: Thread '%s' (%#x) is not joinable.\n",
            fn, taskName(tid), tid);
        return;
    }

    semGive(joinSem);   /* Rendezvous with thread */

    status = taskWait(tid, WAIT_FOREVER);
    if (status && errno != S_objLib_OBJ_ID_ERROR) {
        perror(fn);
        cantProceed("%s: ", fn);
    }
#endif
}

void epicsThreadOnce	(	epicsThreadOnceId *	id,
		void(*)(void *)	func,
		void *	arg
	)

Definition at line 159 of file osdThread.c.

{
    static struct epicsThreadOSD threadOnceComplete;
    #define EPICS_THREAD_ONCE_DONE &threadOnceComplete
    int result;

    epicsThreadInit();
    result = semTake(epicsThreadOnceMutex, WAIT_FOREVER);
    assert(result == OK);
    if (*id != EPICS_THREAD_ONCE_DONE) {
        if (*id == EPICS_THREAD_ONCE_INIT) { /* first call */
            *id = epicsThreadGetIdSelf();    /* mark active */
            semGive(epicsThreadOnceMutex);
            func(arg);
            result = semTake(epicsThreadOnceMutex, WAIT_FOREVER);
            assert(result == OK);
            *id = EPICS_THREAD_ONCE_DONE;    /* mark done */
        } else if (*id == epicsThreadGetIdSelf()) {
            semGive(epicsThreadOnceMutex);
            cantProceed("Recursive epicsThreadOnce() initialization\n");
        } else
            while (*id != EPICS_THREAD_ONCE_DONE) {
                /* Another thread is in the above func(arg) call. */
                semGive(epicsThreadOnceMutex);
                epicsThreadSleep(epicsThreadSleepQuantum());
                result = semTake(epicsThreadOnceMutex, WAIT_FOREVER);
                assert(result == OK);
            }
    }
    semGive(epicsThreadOnceMutex);
}

epicsThreadPrivateId epicsThreadPrivateCreate

(

void

)

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

Definition at line 509 of file osdThread.c.

{
    static int lock = 0;
    epicsThreadPrivateId id;

    epicsThreadInit();
    /*lock is necessary because ++nepicsThreadPrivate may not be indivisible*/
    while(!vxTas(&lock)) taskDelay(1);
    id = (epicsThreadPrivateId)++nepicsThreadPrivate;
    lock = 0;
    return(id);
}

void epicsThreadPrivateDelete

(

epicsThreadPrivateId

id

)

Free a thread local variable

Definition at line 522 of file osdThread.c.

{
    /*nothing to delete */
    return;
}

void* epicsThreadPrivateGet

(

epicsThreadPrivateId

)

Fetch the current value of a thread local variable

Definition at line 554 of file osdThread.c.

{
    int int_id = (int)id;

    /*
     * If epicsThreadPrivateGet() is called before epicsThreadPrivateSet()
     * for any particular thread, the value returned is always NULL.
     */
    if ( papTSD && int_id <= (int) papTSD[0] ) {
        return papTSD[int_id];
    }
    return NULL;
}

void epicsThreadPrivateSet	(	epicsThreadPrivateId	,
		void *
	)

Update thread local variable

Definition at line 532 of file osdThread.c.

{
    int int_id = (int)id;
    int nepicsThreadPrivateOld = 0;

    if (papTSD) nepicsThreadPrivateOld = (int)papTSD[0];

    if (!papTSD || nepicsThreadPrivateOld < int_id) {
        void **papTSDold = papTSD;
        int i;

        papTSD = callocMustSucceed(int_id + 1,sizeof(void *),
            "epicsThreadPrivateSet");
        papTSD[0] = (void *)(int_id);
        for (i = 1; i <= nepicsThreadPrivateOld; i++) {
            papTSD[i] = papTSDold[i];
        }
        free (papTSDold);
    }
    papTSD[int_id] = pvt;
}

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 134 of file osdThread.c.

{}

void epicsThreadResume

(

epicsThreadId

id

)

Resume a thread suspended with epicsThreadSuspendSelf()

Definition at line 344 of file osdThread.c.

{
    int tid = (int)id;
    STATUS status;

    status = taskResume(tid);
    if(status) errlogPrintf("epicsThreadResume failed\n");
}

void epicsThreadSetPriority	(	epicsThreadId	id,
		unsigned int	priority
	)

Change OSI priority of target thread.

Definition at line 374 of file osdThread.c.

{
    int tid = (int)id;
    STATUS status;
    int priority = 0;

    priority = getOssPriorityValue(osip);
    status = taskPrioritySet(tid,priority);
    if(status) errlogPrintf("epicsThreadSetPriority failed\n");
}

void epicsThreadShow	(	epicsThreadId	id,
		unsigned int	level
	)

Print info about a single EPICS thread.

Definition at line 488 of file osdThread.c.

{
    int tid = (int)id;

    if (level > 1) level = 1;
    if (tid)
        taskShow(tid, level);
}

void 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 483 of file osdThread.c.

{
    taskShow(0,2);
}

void 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 420 of file osdThread.c.

{
    STATUS status;
    int ticks;

    if (seconds > 0.0) {
        seconds *= sysClkRateGet();
        seconds += 0.99999999;  /* 8 9s here is optimal */
        ticks = (seconds >= INT_MAX) ? INT_MAX : (int) seconds;
    }
    else {  /* seconds <= 0 or NAN */
        ticks = 0;
    }
    status = taskDelay(ticks);
    if(status) errlogPrintf("epicsThreadSleep\n");
}

double 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 568 of file osdThread.c.

{
    double HZ = sysClkRateGet ();
    return 1.0 / HZ;
}

void epicsThreadSuspendSelf

(

void

)

Block the current thread until epicsThreadResume().

Definition at line 336 of file osdThread.c.

{
    STATUS status;

    status = taskSuspend(taskIdSelf());
    if(status) errlogPrintf("epicsThreadSuspendSelf failed\n");
}

LIBCOM_API void osdThreadHooksRun

(

epicsThreadId

id

)

Definition at line 105 of file osdThreadHooks.c.

{
    threadHookInit();

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

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

Variable Documentation

int taskIdListSize = 0

Definition at line 68 of file osdThread.c.