pfQueue(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQueue(3pf)NAME
pfNewQueue, pfInsertQueueElt, pfInsertFrontQueueElt, pfRemoveQueueElt,
pfAttemptRemoveQueueElt, pfGetQueueClassType, pfQueueArrayLen,
pfGetQueueArrayLen, pfGetQueueNum, pfAddQueueServiceProc,
pfGetQueueNumServiceProcs, pfGetQueueServiceProcPID, pfQueueSortMode,
pfGetQueueSortMode, pfGetQueueElementSize, pfQueueInputRange,
pfGetQueueInputRange, pfQueueOutputRange, pfGetQueueOutputRange,
pfQueueSortFunc, pfGetQueueSortFunc, pfGetQueueSortProcPID,
pfNotifyQueueSortProc, pfSignalAllQueueServiceProcs,
pfGetNumGlobalQueueServiceProcs, pfGetGlobalQueueServiceProcPID,
pfGetGlobalQueueServiceProcQueue - Multiprocess-safe dynamically-sized
queue utility
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfQueue * pfNewQueue(int eltSize, int nElts, void *arena);
void pfInsertQueueElt(pfQueue* queue, void *elt);
void pfInsertFrontQueueElt(pfQueue* queue, void *elt);
void * pfRemoveQueueElt(pfQueue* queue);
void * pfAttemptRemoveQueueElt(pfQueue* queue);
pfType * pfGetQueueClassType(void);
void pfQueueArrayLen(pfQueue* queue, int length);
int pfGetQueueArrayLen(pfQueue* queue);
int pfGetQueueNum(pfQueue* queue);
int pfAddQueueServiceProc(pfQueue *queue,
pfQueueServiceFuncType func);
int pfGetQueueNumServiceProcs(pfQueue* queue);
int pfGetQueueServiceProcPID(pfQueue* queue,
int which);
void pfQueueSortMode(pfQueue *queue, int boolean);
int pfGetQueueSortMode(pfQueue *queue);
int pfGetQueueElementSize(pfQueue *queue);
void pfQueueInputRange(pfQueue *queue, int low,
int high);
Page 1
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQueue(3pf)
void pfGetQueueInputRange(pfQueue *queue, int *low,
int *high);
void pfQueueOutputRange(pfQueue *queue, int low,
int high);
void pfGetQueueOutputRange(pfQueue *queue, int *low,
int *high);
void pfQueueSortFunc(pfQueue *queue,
pfQueueSortFuncType func);
pfQueueSortFuncType pfGetQueueSortFunc(pfQueue *queue);
int pfGetQueueSortProcPID(pfQueue *queue);
void pfNotifyQueueSortProc(pfQueue *queue);
int pfSignalAllQueueServiceProcs(int count, int token);
int pfGetNumGlobalQueueServiceProcs(void);
int pfGetGlobalQueueServiceProcPID(int n);
pfQueue* pfGetGlobalQueueServiceProcQueue(int n);
typedef int (*pfQueueServiceFuncType)(void *data);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfQueue is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfQueue. Casting an object of
class pfQueue to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfQueue can also be used with these functions
designed for objects of class pfMemory.
Page 2
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQueue(3pf)
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
DESCRIPTION
The pfQueue data type is implemented as a dynamically sized array of
arbitrary, but homogeneously-sized, elements.
pfNewQueue creates and returns a handle to a new pfQueue. eltSize
specifies the size in bytes of an individual queue element. The element
size is fixed at creation time and cannot be changed later. nElts is the
initial length of the queue array; nElts * eltSize bytes will be
allocated for the queue array. The argument arena specifies a malloc
arena out of which the pfQueue is to be allocated or NULL for allocation
from the process heap. pfQueues can be deleted with pfDelete.
pfGetQueueClassType returns the pfType* for the class pfQueue. The
pfType* returned by pfGetQueueClassType is the same as the pfType*
returned by invoking pfGetType on any instance of class pfQueue. Because
OpenGL Performer allows subclassing of built-in types, when decisions are
made based on the type of an object, it is usually better to use
pfIsOfType to test if an object is of a type derived from a Performer
type rather than to test for strict equality of the pfType*'s.
A pfQueue dynamically increases its array size by a factor of 2 and zeros
the additional memory whenever it runs out of array memory. This way the
array size quickly reaches its final size without many reallocations of
memory. However, some memory (up to one half if the total allocation) at
the end of the array may be wasted. If you know the exact number of
elements in the array, you can specify the pfQueue array length either
when creating it (the nElts argument to pfNewQueue) or with
pfQueueArrayLen. pfGetQueueArrayLen returns the current array length of
queue.
pfInsertQueueElt adds an element, elt to the queue. The queue array is
grown automatically if adding an element forces the number of elements to
be greater then the length of the queue array.
Normally, a queue element is inserted at the back of the queue, and all
Page 3
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQueue(3pf)
the elements that where inserted first must be removed before the element
itself is removed. The pfInsertFrontQueueElt call adds an element to the
.in 0.125i front.in 0.125i
of the queue, so it will be the next element removed. This function is
used internally by performer to help kill queue service processes
cleanly.
pfRemoveQueueElt removes and returns an element from the queue.
Note that both inserting and removing from a pfQueue can be done from
multiple processes without collision, but that the pfQueue enforces with
locks that only one process can actually be inserting into the queue and
one process removing from the queue at one time.
Also note that calls to remove will block waiting for an element to be
inserted onto the queue when the queue is empty.
pfAttemptRemoveQueueElt removes and returns an element from the queue.
Unlike pfRemoveQueueElt, this command doesn't block if the queue is
empty. Instead, it returns a NULL pointer.
pfGetQueueNum returns the number of elements currently stored in the
pfQueue.
pfAddQueueServiceProc will use sproc to create a thread to service
elements of a queue. The process ID of the spawned process is provided
to the caller as the return value. This new thread will share all of the
caller's address space and will simply invoke the supplied function,
func, to service a queue element whenever the queue is non-empty. Thus,
this process simply loops calling pfQueueRemove and then calling func
with the element just removed from the queue.
The number of currently active service processes is returned by
pfGetQueueNumServiceProcs.
The process ID of a particular service process can be obtained through
pfGetQueueServiceProcPID.
Further information regarding all processes allocated to service all
queues can be queried through three global routines.
pfGetNumGlobalQueueServiceProcs returns the number of processes that have
been sproc'd by all pfQueue's to service queues.
pfGetGlobalQueueServiceProcPID returns the process id of the nth service
process created. pfGetGlobalQueueServiceProcQueue returns the pfQueue
associated with a particular service process.
pfQueueSortMode changes the fundamental mode of a queue. A queue is
either sorting (sort mode is non-zero) or false (sort mode is zero). When
a queue is in sorting mode, a special process, called the sort proc, is
created. The sort proc calls a user defined function call the sort
function to sort the elements of the queue. A sorting queue is divided
into three parts, the input queue, the sort list, and the output queue.
Page 4
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQueue(3pf)
Elements can be added and removed from a queue in the same way whether a
queue is in sorting or non-sorting mode. Both the input queue and the
output queue have high and low watermarks.
When the number of elements on the input queue exceeds the high water
mark, the number of elements on the output queue drops below the low
water mark, or pfNotifyQueuetSortProc is called, the sort process wakes
up an performs three steps. If the input queue is above the high water
mark, it copies elements into the sort list (which is a pfList structure)
down to the low water mark. The sort proc then calls the sort function,
which sorts the list. Finally, if the output queue has dropped below the
low water mark, the sort proc removes elements from the end of the sort
list and puts them on the output queue up to the high water mark. The
sort proc knows nothing about the elements of the queue. Only the sort
function, supplied by the application, actually sorts the elements based
on understanding the priorities of their contents. If a sort function
hasn't been provided before attempting to change the queue to sorting
mode, then an error message is generated and the call is ignored.
pfGetQueueSortMode returns the current sort mode value. A non-zero value
indicates sorting mode. A zero value indicates non-sorting, or normal
mode.
pfGetQueueElementSize returns the size of the queue elements in bytes. In
most cases, the queue is working with pointer elements. In that case, the
size will be sizeof(void *).
pfQueueInputRange sets the high and low water marks for the input queue.
This queue is active when the queue is in sorting mode. Changes to the
low and high values won't take effect until the next time the queue
transitions from non-sorting to sorting mode. The default values for
input range are 0 for the low water mark, and 3 for the high water mark.
pfGetQueueInputRange returns currently set water mark values. Values read
by this function may not have taken effect yet.
pfQueueOutputRange sets the high and low water marks for the output
queue. This queue is active when the queue is in sorting mode. Changes to
the low and high values won't take effect until the next time the queue
transitions from non-sorting to sorting mode. The default values for
output range are 2 for the low water mark, and 5 for the high water mark.
pfGetQueueOutputRange returns currently set water mark values. Values
read by this function may not have taken effect yet.
pfQueueSortFunc provides a pointer to a function used to sort the
elements of queue when the queue is in sorting mode. The function should
take a single argument, a pointer to a pfQueueSortFuncData structure, and
return void. The pointer will contain a pointer to a pfList containing
pointers to the elements to be sorted, the current values for the high
and low water marks for the input and output queues, and volatile
integers indicating the current size of the input and output queues. The
sort function should do a single sort of the elements in the pfList and
return. The default value of the sort function pointer is NULL. A queue
Page 5
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfQueue(3pf)
can not enter sorting mode without a valid sort function pointer. Changes
to the sorting function don't take effect until the next transition from
non sorting to sorting mode.
The volatile integer values are used for very latency sensitive
operations, or sort algorithms that may be lengthy. The sort function can
periodically check the size of the input and output queues, and return
early, leaving the list in an incompletely sorted state if necessary.
pfGetQueueSortFunc returns a pointer to the current sorting function.
This may not be the sort function currently in use.
pfGetQueueSortProcPID returns the process id of the sorting process. This
value can be used to change the run priority of the process, or move it
to another CPU. If the queue is not in sorting mode, the process id with
be zero.
pfNotifyQueueSortProc signals the sort proc to run the sort function now,
rather than waiting for the high or low water marks for the input or
output queues to signal a sorting run. This function can be called when
the application knows that the sorted queue is out of order or needs
culling.
pfSignalAllQueueServiceProcs places a count copies of token at the
beginning of the queue, then P's the exit semaphore count times. This
function is used to cleanly terminate all the readers of a sort queue.
The token is generally a token signalling the reader to exit. P'ing on
the semaphore causes the pfSignalAllQueueServiceProcs function to sleep
until all the readers have exited. An exit token is used to ensure that
the reader isn't sleeping waiting for the next token and never exits.
BUGS
pfQueues currently only support an element size of sizeof(void*).
SEE ALSO
pfDelete, pfImageCache, pfClipTexture
Page 6
