EPICURE Software Release Note 142.2<P> <b> EPICURE Priority Event Queue Services</b>

EPICURE Software Release Note 142.2

EPICURE Priority Event Queue Services

David M. Kline


The primary purpose of the EPICURE Priority Event Queue services are to provide ``soft'' real-time processes with a mechanism to insert events in a priority order. In addition, it provides source-code portability between C on VAX and AXP based systems. Future releases of the EPEQ services will provide source-code portability to other C on various operating systems such as Windows NT, OSF/1, and others which are Unix based. The services implement two software abstraction layers which provide a standard interface that is portable to other operating systems. The first layer provides routines that manage priority queues; the second provides routines and stubs for dependencies inherent in other operating systems. To illustrate, if the second layer were to be developed for C compliers under Windows NT, EPEQ services can be used on Alpha, Pentium, PowerPC, and HP PA-RISC based workstations, and other Intel 486 and 386 PCs.

Processes initialize priority event queue services by calling the epeq_init() routine, specifying the size of the auxiliary data area and the number of priority queues. The auxiliary data area is used by processes to pass data that is associated with a particular event. The number of priority event queues is specified once and cannot be modified. The lowest priority queue is zero (0); the highest priority queue is the value passed by the ``maxpq'' parameter minus one (see section ``User Services''). If the ``maxpq'' parameter is omitted, the default number of priority queues is one (1). In that case, the benefits in using these services are portability between operating systems and optimization in accessing the event queue and the auxiliary data area. In addition, an automatic priority boost (APB) algorithm is provided and can be enabled or disabled. The APB algorithm scans the priority queues and removes events and inserts them into a higher priority queue given a criteria determined by the user. The user can specify the amount of time between queue scans, the number of scans to occur before the event is boosted, and how many priority queues to boost the event (see section ``User Services'').

Events are inserted by the epeq_add_event() service specifying an event type code at a particular priority. If the priority is omitted, the event is inserted into the lowest priority queue. Events are processed by using the epeq_get_event() service routine. The code with the highest priority is returned to the caller. The process then calls the routine associated with that particular event. While processing the event, other events can be inserted into the priority queues through interrupt service routines (ISR). The ISR can insert another event at a higher priority guaranteeing its delivery at the next invocation of epeq_get_event(). In effect, lower priority events that are waiting in the priority queues can be preempted; however, the lower priority event currently executing will run to completion without interruption. This kind of processing implements a FIFO processing methodology. In addition, the epeq_check_event() service allows the user to check and receive an event without risk of incurring a wait if the priority queues are all empty. The service routine scans for the event with the highest priority. It is removed and presented to the process for interpretation. A particular priority queue can be specified by the ``pri'' parameter. If passed, the service routine will remove an event only from that priority queue, bypassing all others.

Events can be flushed from the priority queue entirely or selectively. The epeq_flush_all() service flushes all events from every priority queue. Events can be selectively flushed by the epeq_flush_selected() service. A series of event codes can be specified to be flushed and at a particular priority. If the priority is not specified, the events are removed from all priority queues (see section ``User Services'').

Another service routine is available that writes the contents of the priority queues to the standard output device (i.e. stdout). The routine begins at the highest priority queue and outputs the event codes without removing them. This routine is not mentioned in the section ``User Services'' but is available and has the following calling sequence:


On VAX and AXP systems under OpenVMS, the EPEQ services are incorporated into EPICURELIB and are referenced by the Linker command:

        $ link myprogram,...,sys$input:/options

Furthermore, when porting to other operating systems, the source-code (EPEQ.C) can be obtained from the directory EPICURE_ROOT:[WORK.EPEQ.RELEASES] on the WARNER cluster.

The following section describes the service routines and their calling sequence.

User Services

The service routines begin with the prefix and allow for some optional parameters. These parameters are identified by enclosed brackets []. In addition, Appendix A provides a programming example.


(int)status = epeq_add_event( type [,dptr, dlen] [,pri] [,athead] ) Add an event to a priority queue. type event type code to be added to priority queue (tail). Passed by value. dptr optional pointer to the auxiliary data to be associated with the event type code. Pointer is passed by value, the auxiliary data is thus passed by reference. dlen optional length (in bytes) of the auxiliary data. If the length is 0 or not given or if the pointer is NULL, then no auxiliary data is stored with the event. Passed by value. pri optional parameter to insert the event on a particular priority queue. If no parameter, the event is inserted on the lowest priority queue (0). Passed by reference. athead optional parameter indicating that the event is to be inserted at the head of the priority queue. If the parameter is omitted or is a zero value, the event is inserted at the tail. Passed by value. status returns a condition value: EPEQ__SUCCESS success EPEQ__ONLYONE success, one element on queue EPEQ__BLKTRUNC warning, data truncated EPEQ__ALOMEMERR fatal, failure to allocate memory


(int)status = epeq_check_event( type [,dptr] [,pri] ) Scan for an event in the priority queues. If present, dequeue it and return the event code and auxiliary data. The ``pri'' parameter is provided to allow a specific priority queue to be scanned. If the parameter is not specified, scanning begins at the highest priority. type parameter returning the event type code found. Passed by reference. dptr optional pointer to buffer in which the auxiliary data associated with the event type code is copied. The buffer is passed by reference (pointer is by value). pri optional parameter specifying the priority queue to scan. Passed by reference. status returns a condition value: EPEQ__SUCCESS success EPEQ__ONLYONE success, one element on queue EPEQ__BLKTRUNC warning, data truncated EPEQ__EMPTY warning, priority queue empty EPEQ__RELMEMERR fatal, failure to release memory


(void)epeq_flush_all() Flush all events (empty the priority event queues).


(int)count = epeq_flush_selected( [pri] [,type] [,type...] ) Flush the selected event codes from the priority queue. The ``pri'' parameter can be used to specify which priority queue to flush. If the parameter is not specified, all priority queues are flushed. pri optional parameter specifying which priority to scan. Passed by reference. type list of event types to be flushed from the queue. Passed by value. count returns count of events flushed from the queue.


(int)type = epeq_get_event( [dptr] [,pri] ) Get an event from the head of the highest priority event queue. If the queue is empty, wait until an event appears on the queue. dptr optional pointer to buffer in which the auxiliary data associated with the event type code is returned. Buffer is passed by reference (pointer is by value). pri optional parameter returning the priority associated with the event code. Passed by reference. type returns an event type code as an int.


(int)status = epeq_init( [dsiz] [,maxpq] [,apbena ,apbtmo ,apbcnt ,apbost] ) Initialize the EPICURE priority queue (EPEQ) services. These services are primarily used by ``soft'' real-time processes that require the use of FIFO priority queues. Processes can insert events at the head or tail of a priority queue. The maximum number of priority queues is determined by the ``maxpq'' parameter. The lowest priority is zero and the highest is maxpq minus one. Another feature that is available automatically boosts events to a higher priority after a predetermined time. When the ``apbena'' parameter is set to TRUE, the automatic priority boost (APB) algorithm is enabled and periodically scans the priority queues. Refer to the ``apbtmo'', ``apbcnt'', ``apbost'' parameter descriptions for additional information. dsiz optional maximum size (in longwords) for the auxiliary data area in an event queue block. The default size has space for 4 bytes (1 longword) of auxiliary data. Passed by value. maxpq optional maximum number of priority queues. If parameter is omitted or is zero, the default number of priority queues is one. Passed by value. apbena optional parameter that enables or disables the automatic priority boost (APB) algorithm. A TRUE (1) value enables APB, and a FALSE (0) values disables APB. Passed by value. apbtmo optional parameter specifying (in milliseconds) how often the priority queues are scanned. The default value is 1000 milliseconds (or 1sec). The valid range is from 100mS to 5000mS. Passed by value. apbcnt optional parameter specifying the number of scans before a queue buffer is moved to a higher priority queue. The default value is one (1). Passed by value. apbost optional parameter specifying the maximum number of priority queues that a queue buffer can be boosted. The default value is one (1) priority. Passed by value. status returns a condition value: EPEQ__SUCCESS success EPEQ__ALOMEMERR fatal, failure to allocate memory EPEQ__EPEQINIT fatal, services previously initialized

Appendix A: Programming Examples

This page was intentionally left blank.




Security, Privacy, Legal