#include "brttpkt.h" #include "stock.h" OrbreapThr * orbreapthr_new (int orb, double timeout, int queuesize) OrbreapThr * orbreapthr_new2 (char *orbname, char *select, char *reject, double tafter, double timeout, int queuesize) int orbreapthr_register_callback (OrbreapThr *orbth, void (*callback) (int reason, OrbreapThr *orbth, void *user_data), void *user_data) int orbreapthr_pause (OrbreapThr *orbth, int flush) int orbreapthr_continue (OrbreapThr *orbth) int orbreapthr_select (OrbreapThr *orbth, char *select) int orbreapthr_reject (OrbreapThr *orbth, char *reject) int orbreapthr_after (OrbreapThr *orbth, double after) int orbreapthr_seek (OrbreapThr *orbth, int which) int orbreapthr_get (OrbreapThr *orbth, int *pktid, char *srcname, double *time, char **packet, int *nbytes, int *bufsize) int orbreapthr_set_to_stop (OrbreapThr *orbth) int orbreapthr_is_stopped (OrbreapThr *orbth) int orbreapthr_stop_and_wait (OrbreapThr *orbth) int orbreapthr_destroy (OrbreapThr *orbth) int orbreapthr_data_available (OrbreapThr *orbth) int orbreapthr_set_timeout (OrbreapThr *orbth, double timeout) int orbreapthr_set_verbose (int verbose) OrbputThr * orbputthr_new (int orb, int queuesize) int orbputthr_stop (OrbputThr *orbth) int orbputthr_destroy (OrbputThr *orbth) int orbputthr_put (OrbputThr *orbth, char *srcname, double time, char *packet, int nbytes)
orbreapthr_new creates a new ORB reap thread object and returns a pointer to the object. This pointer is used as a handle for subsequent operations. The input ORB is specified by orb which must already be opened, subsetted and positioned. orbreapthr_new launches a thread that will reap packets from the input ORB. As the packets are reaped, they are pushed onto a MT-safe FIFO queue (see pmtfifo(3)). The maximum size of the queue is specified with queuesize which is a size in packets. The behavior of orbreapthr_get is determined by timeout, which is a blocking timeout value in seconds. If timeout is less than zero, then calls to orbreapthr_get will block indefinitely if there are no packets in the queue. If timeout is equal to zero, then calls to orbreapthr_get will always return without blocking regardless of data availability. If timeout is greater than zero, then orbreapthr_get will block for no more than timeout seconds if there are no packets in the queue.
orbreapthr_new2 also creates a new ORB reap thread object and in most respects behaves like orbreapthr_new. However, orbreapthr_new2 also opens the ORB named orbname with a call to orbopen(3), sends the orbserver select and reject expressions, if they are non-NULL, and positions the read pointer after epoch time tafter, unless tafter is less than zero in which case the read pointer is not initialized and by default should be at the most recent position in the ORB. The ORB opening, selecting, rejecting and positioning are all done within the run thread so orbreapthr_new2 will always return immediately.
orbreapthr_register_callback will register a callback function, callback, with an ORB reap thread object, orbth. User data is specified by user_data. The callback function is called by the ORB reap thread object for various reasons as follows.
void callback (int reason, OrbreapThr *orbth, void *user_data)
The reason for the callback is specified by reason. The associated Orb reap thread object is specified by orbth. User data defined in the orbreapthr_register_callback function is specified by user_data. Currently the only value for reason is ORBREAPTHR_NEWDATA, meaning new data has just been added to the internal pmtfifo(3) queue. Note that this callback is called from the ORB reap thread object processing thread. Therefore application programs should arrange for synchronization with the various application program threads.
orbreapthr_pause will pause the ORB packet reading of a running thread. If flush is set to non-zero, then all FIFO reading from other threads will be temporarily paused, the FIFO queue will be flushed and the FIFO reading from other threads will be resumed. This call should be made before calls to orbreap_select, orbreap_reject, orbreapthr_after and orbreapthr_seek in order to have more precise control over packets in the FIFO queue that would get processed by the reading threads.
orbreapthr_continue will continue the ORB packet reading of a running thread. This is normally paired with a call to orbreapthr_pause.
orbreapthr_select, orbreapthr_reject, orbreapthr_after and orbreapthr_set can be used to safely change the select and reject expressions and to reset the read pointer after a thread has already been created and is running. Precise control of the ORB packets in the FIFO queue can be accomplished by bracketing these calls with orbreapthr_pause and orbreapthr_continue.
orbreapthr_stop_and_wait stops the processing of the ORB reap thread and waits for the thread to exit. This should be called before orbreapthr_destroy. Generally, an orderly shutdown sequence looks like this:
orbreapthr_set_to_stop will tell the reap thread to stop processing and exit in an orderly fashion, returning immediately, and orbreapthr_is_stopped can be called to see if the reap thread has exited (returns 1 is it has exited or 0 if not). These can be used by the calling program to initiate reap thread shutdown and go off to do other things while the thread is shutting down.
orbreapthr_destroy frees all resources associated with an ORB reap thread object. Note that this does not kill the reap thread, which must be done first with orbreapthr_stop_and_wait or orbreapthr_set_to_stop.
orbreapthr_set_timeout resets the timeout value with timeout.
orbreapthr_set_verbose resets the verbosity level to verbose. Verbosity other than 0 will cause elog_notify(3) messages to be printed every time a thread is started, is exiting and is being joined.
orbreapthr_data_available returns 1 if data is available in the FIFO or 0 otherwise.
ORB data packets are retrieved from the FIFO with calls to orbreapthr_get which has arguments similar to orbreap(3). Note that the dynamic memory assignments for *packet are the same as for orbreap(3). The return codes for orbreapthr_get are as follows:
orbputthr_new creates a new ORB put thread object and returns a pointer to the object. This pointer is used as a handle for subsequent operations. The output ORB is specified by orb which must already be opened. orbputthr_new launches a thread that will read ORB packets from the internal FIFO and writes these packets to the output ORB. As the packets are put into the FIFO, with calls to orbputthr_put, they are pushed onto a MT-safe FIFO queue (see pmtfifo(3)). The maximum size of the queue is specified with queuesize which is a size in packets. This FIFO is always blocking, so when the queuesize has been filled, calls to orbputthr_put will block until the packets can be written to the output ORB.
orbputthr_stop stops the processing of the ORB put thread and kills the ORB put thread. This should be called before orbputthr_destroy. generally, an orderly shutdown sequence looks like this:
orbputthr_destroy frees all resources associated with an ORB put thread object. Note that this does not kill the put thread, which must be done first with orbputthr_stop.
ORB data packets are put onto the FIFO with calls to orbputthr_put which has arguments similar to orbput(3).
orbreapthr_stop and orbreapthr_destroy return 0 if OK or -1 if there is an error.
orbputthr_new returns an ORB put thread object handle (pointer to an OrbputThr structure) or NULL if there is an error.
orbputthr_stop, orbputthr_destroy and orbputthr_put return 0 if OK or -1 if there is an error.
If there is an error, then messages are left on the error register.