diff --git a/modules/database/src/ioc/db/dbScan.h b/modules/database/src/ioc/db/dbScan.h index 1839ae321..7454dea75 100644 --- a/modules/database/src/ioc/db/dbScan.h +++ b/modules/database/src/ioc/db/dbScan.h @@ -62,8 +62,28 @@ DBCORE_API void post_event(int event); DBCORE_API void scanAdd(struct dbCommon *); DBCORE_API void scanDelete(struct dbCommon *); DBCORE_API double scanPeriod(int scan); -DBCORE_API int scanOnce(struct dbCommon *); -DBCORE_API int scanOnceCallback(struct dbCommon *, once_complete cb, void *usr); +/** Shorthand for scanOnceCallback(prec, NULL, NULL) + */ +DBCORE_API int scanOnce(struct dbCommon *prec); +/** @brief 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() + * + * @param prec Record to process + * @param cb Function called after target record dbProcess() + * Does not wait for async record completion. + * @param usr Argumentfor cb + * @return Zero on success. Non-zero if the request could not be queued. + */ +DBCORE_API int scanOnceCallback(struct dbCommon *prec, once_complete cb, void *usr); +/** @brief Set Once queue size + * + * Must be called prior to iocInit() + * + * @param size New size. May be smaller + * @return Zero on success + */ DBCORE_API int scanOnceSetQueueSize(int size); DBCORE_API int scanOnceQueueStatus(const int reset, scanOnceQueueStats *result); DBCORE_API void scanOnceQueueShow(const int reset); @@ -77,9 +97,39 @@ DBCORE_API int scanpel(const char *event_name); /*print io_event list*/ DBCORE_API int scanpiol(void); +/** @brief Initialize "I/O Intr" source + * @param ppios Pointer to scan list to be initialized + * + * 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. + */ DBCORE_API void scanIoInit(IOSCANPVT *ppios); +/** @brief Request processing of all associated records from callback threads + * @param pios The scan list + * @pre pios must be initialized by scanIoInit() + * @return + */ DBCORE_API unsigned int scanIoRequest(IOSCANPVT pios); +/** @brief Process all records on the scan list for the specificed priority. + * + * Also executes the callback set by scanIoSetComplete() + * + * @param pios The scan list + * @param prio one of priorityLow through priorityHigh (defined in callback.h). + * A value between 0 and NUM_CALLBACK_PRIORITIES-1 . + * @return Zero if the scan list was empty or 1<