document dbScan.h

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<<prio
+ * @since 3.16.0.1
+ */
 DBCORE_API unsigned int scanIoImmediate(IOSCANPVT pios, int prio);
+/** @brief 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
+ */
 DBCORE_API void scanIoSetComplete(IOSCANPVT, io_scan_complete, void *usr);
 
 #ifdef __cplusplus