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 (default default is 2). 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 on the host. eg. Passing -2 on an 8 core system will start 6 worker threads. In all cases, at least one worker thread will always run.
A special prio name of “*” will modify all priorities. Otherwise, only the named priority is modified.
- 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, number of worker threads less than core count.
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>