callback.h
Process database deferred execution utility.
Defines
-
NUM_CALLBACK_PRIORITIES
-
priorityLow
-
priorityMedium
-
priorityHigh
-
callbackSetCallback(PFUN, PCALLBACK)
Assigns callbackPvt::callback
-
callbackSetPriority(PRIORITY, PCALLBACK)
Assigns callbackPvt::priority
-
callbackGetPriority(PRIORITY, PCALLBACK)
Assigns callbackPvt::priority
-
callbackSetUser(USER, PCALLBACK)
Assigns callbackPvt::user
-
callbackGetUser(USER, PCALLBACK)
Read and return callbackPvt::user
Typedefs
-
typedef epicsCallback CALLBACK
Deprecated alias for epicsCallback
Name conflicts with definition from windows.h. Portable applications should prefer epicsCallback and define the EPICS_NO_CALLBACK pre-processor macro to hide this typedef.
- Since
3.15.6 Deprecated in favor of epicsCallback typedef
-
typedef void (*CALLBACKFUNC)(struct callbackPvt*)
Functions
-
void callbackInit(void)
-
void callbackStop(void)
-
void callbackCleanup(void)
-
int callbackRequest(epicsCallback *pCallback)
Queue immediate callback request.
Each epicsCallback may be queued multiple times. epicsCallback object must not be modified while queued, and must remain valid while queued or executing.
- Parameters:
pCallback – Caller expected to initialize or zero all members before first call.
- Returns:
Zero on success. Errors if callback members not initialized correctly, or if queue is full.
-
void callbackSetProcess(epicsCallback *pcallback, int Priority, void *pRec)
Setup callback to process a record
- Parameters:
pcallback – Callback to initialize.
Priority – priorityLow, priorityMedium, or priorityHigh
pRec – A record pointer (dbCommon or specific recordType)
- Pre:
Callback must be zero initialized.
-
int callbackRequestProcessCallback(epicsCallback *pCallback, int Priority, void *pRec)
(Re)Initialize callback object and queue
Shorthand for callbackSetProcess() followed by callbackRequest()
- Pre:
Callback object must be zero initialized before first call.
-
void callbackRequestDelayed(epicsCallback *pCallback, double seconds)
Queue delayed callback request
Each epicsCallback has a single timer. Repeated calls before expiration will cancel and reschedule timer. epicsCallback object must not be modified while queued, and must remain valid while queued or executing.
epicsCallback::timer must be zeroed before the first call, and left unmodified for subsequent calls. Each epicsCallback is allocated a timer on first call. There is no way to free this allocation. Reuse of epicsCallback is strongly recommended.
- Parameters:
pCallback – Callback object. Caller expected to initialize or zero all members prior to first call.
seconds – Relative to call time. Expected to be >= 0.
- Returns:
Zero on success. Errors if callback members not initialized correctly, or if queue is full.
-
void callbackCancelDelayed(epicsCallback *pcallback)
Cancel delayed callback.
Usage not recommended. Caller can not distinguish between successful cancellation, or expiration. In the later case the callback may still be queued or executing.
- Parameters:
pcallback – Callback object previously passed to callbackRequestDelayed()
- Post:
Timer is cancelled. However, callback may be queued or executing.
-
void callbackRequestProcessCallbackDelayed(epicsCallback *pCallback, int Priority, void *pRec, double seconds)
(Re)Initialize callback object and queue
Shorthand for callbackSetProcess() followed by callbackRequestDelayed()
- Pre:
Callback object must be zero initialized before first call.
-
int callbackSetQueueSize(int size)
Set callback queue depth
- Parameters:
size – A positive integer
- Returns:
-1 if too late to change depth
- Pre:
Must be called before iocInit()
-
int callbackQueueStatus(const int reset, callbackQueueStats *result)
Query configuration and statistics from callback system
- Since
7.0.2. Also present in 3.16.2
- Parameters:
reset – If non-zero, reset maxUsed after reading.
result – NULL, or location for results
- Returns:
-2 if result is NULL. reset happens anyway.
-
void callbackQueueShow(const int reset)
-
int callbackParallelThreads(int count, const char *prio)
Setup multiple worker threads for specified priority
By default, only one thread is run for each priority (3 in total).
Calling with count==0 will take the count from the callbackParallelThreadsDefault global variable (initialized to the number of CPU cores initially available to the main thread). Calling with count>0 sets the number of worker threads directly. Calling with count<0 computes the count based on the number of CPU cores currently available to the calling thread, eg. Passing -2 on an 8 core system will start 6 worker threads. The iocsh wrapper also accepts positive or negative percentages for count, which allows to refer to a fraction of the currently available CPU cores, always rounding the number of created threads down. In any case, at least one worker thread will always run.
An empty prio name or the special value “*” will modify all priorities. Otherwise, only the named priority is modified. The prio names are case insensitive.
- Since
3.15.0.2
- Parameters:
count – If zero, reset to default (callbackParallelThreadsDefault global/iocsh variable). If positive, exact number of worker threads to create. If negative, reserve this many CPUs to not run parallel callback threads.
prio – Priority name. eg. “*”, “LOW”, “MEDIUM” or “HIGH”.
- Returns:
zero on success, non-zero if called after iocInit() or with invalid arguments.
- Pre:
Must be called before iocInit()
-
struct epicsCallback
- #include <callback.h>
Handle for delayed work.
- Since
3.15.6 epicsCallback typedef added. CALLBACK typedef deprecated.
- Pre:
Must be zero initialized prior to first use.
-
struct callbackQueueStats
- #include <callback.h>