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
Introduction
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:
epeq___dump_queues();
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
RDCS$LIB:EPICURELIB/LIBRARY,-
SYS$SHARE:VAXCRTL.EXE/SHARE
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.
epeq_add_event
(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
epeq_check_event
(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
epeq_flush_all
(void)epeq_flush_all()
Flush all events (empty the priority event queues).
epeq_flush_selected
(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.
epeq_get_event
(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.
epeq_init
(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.
Keywords: EPICURE, EPEQ
Distribution:
Normal
Security, Privacy, Legal
rwest@fsus04.fnal.gov