dbScan.h
Mechanics for interacting with Process Database record scanning utilities.
Scan Queue Overflow
Several of the thread backed scanning mechanisms have work queues which may overflow. Well written EPICS drivers should avoid this as described below.
I/O Intr scanning
An EPICS driver may use scanIoInit() to allocate a scan list. This scan list is associated with a record through dset::get_ioint_info , and triggered with scanIoRequest() (asynchronous) or scanIoImmediate() (synchronous).
scanIoSetComplete() may be used to request notification after any records on the list have begun processing. This may be used to defer future scanIoRequest() until past requests have been satisfied, which avoids possible overflowing of the underlying queue of the worker thread.
Named Event scanning
Event names may appear in the EVNT field of any record. When SCAN is also set to Event, the that record will process each time this Event occurs.
An eventRecord provides one way to trigger scanning.
eventNameToHandle() may be used by an EPICS driver to lookup/create a process-wide named scan list. Then call postEvent() to trigger scanning.
Legacy applications may use post_event() for the special numbered Events (1 through 255). post_event(1) is equivalent to eventNameToHandle("1") followed by a postEvent().
There is no way for a caller of postEvent() to avoid scan queue overflow.
Once Queue
The “once” queue is meant for special cases of one-time processing. eg. the initial PINI scanning. EPICS drivers may call scanOnceCallback() explicitly, but are encouraged where practical to call dbProcess() from a driver managed worker thread.
The process-wide “once” queue has a fixed size, which may be modified by scanOnceSetQueueSize() .
Typedefs
-
typedef struct event_list *EVENTPVT
Functions
-
long scanInit(void)
-
void scanRun(void)
-
void scanPause(void)
-
void scanStop(void)
-
void scanCleanup(void)
-
EVENTPVT eventNameToHandle(const char *event)
Lookup, or create, named Event record list.
- Since
3.15.0.1
- Parameters:
event – Name
- Returns:
Record list handle, or NULL on allocation failure.
-
void postEvent(EVENTPVT epvt)
Request scan of Event record list.
Queue request for callback worker thread(s) to scan records. Lookup named event list with eventNameToHandle() .
- Since
3.15.0.1
- Parameters:
epvt – Event list handle
-
void post_event(int event)
Process numbered Event record list.
- Deprecated:
In favor of postEvent()
- Parameters:
event – Event number in the range 1 through
NUM_TIME_EVENTS-1(255) inclusive.
-
double scanPeriod(int scan)
-
int scanOnceCallback(struct dbCommon *prec, once_complete cb, void *usr)
scanOnce Request immediate record processing from another thread.
Queue a request for record processing from the dedicated “Once” thread. Request may fail if Once queue overflows. See scanOnceSetQueueSize()
- Since
3.16.0.1 Added
- Parameters:
prec – Record to process
cb – Function called after target record dbProcess() Does not wait for async record completion.
usr – Argumentfor cb
- Returns:
Zero on success. Non-zero if the request could not be queued.
-
int scanOnceSetQueueSize(int size)
Set Once queue size.
Must be called prior to iocInit()
- Parameters:
size – New size. May be smaller
- Returns:
Zero on success
-
int scanOnceQueueStatus(const int reset, scanOnceQueueStats *result)
-
void scanOnceQueueShow(const int reset)
-
int scanppl(double rate)
-
int scanpel(const char *event_name)
-
int scanpiol(void)
-
void scanIoInit(IOSCANPVT *ppios)
Initialize “I/O Intr” source.
Afterwards this IOSCANPVT may be assigned during a get_ioint_info() callback. See typed_dset::get_ioint_info()
Note
There is currently no way to free this allocation.
- Parameters:
ppios – Pointer to scan list to be initialized
-
unsigned int scanIoRequest(IOSCANPVT pios)
Request processing of all associated records from callback threads.
- Parameters:
pios – The scan list
- Pre:
pios must be initialized by scanIoInit()
- Returns:
-
unsigned int scanIoImmediate(IOSCANPVT pios, int prio)
Process all records on the scan list for the specified priority.
Also executes the callback set by scanIoSetComplete()
- Since
3.16.0.1
- Parameters:
pios – The scan list
prio – one of priorityLow through priorityHigh (defined in callback.h). A value between 0 and NUM_CALLBACK_PRIORITIES-1 .
- Returns:
Zero if the scan list was empty or 1<<prio
-
void scanIoSetComplete(IOSCANPVT, io_scan_complete, void *usr)
Set scan list completion callback.
Replace the callback which will be invoked after record processing begins. Asynchronous record processing may be ongoing.
- Since
3.15.0.2
-
struct scanOnceQueueStats