pfQueue(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfQueue(3pf)NAME
pfQueue, pfGetNumGlobalQueueServiceProcs, pfGetGlobalQueueServiceProcPID,
pfGetGlobalQueueServiceProcQueue - Multiprocess-safe dynamically-sized
queue utility
FUNCTION SPECIFICATION
#include <Performer/pr/pfQueue.h>
pfQueue::pfQueue();
pfQueue::pfQueue(int eltSize, int nElts);
static pfType * pfQueue::getClassType(void);
void pfQueue::insert(void *elt);
void pfQueue::insertFront(void *elt);
void * pfQueue::remove(void);
void * pfQueue::attemptRemove(void);
void pfQueue::setArrayLen(int length);
int pfQueue::getArrayLen(void);
int pfQueue::getNum(void);
int -
pfQueue::addServiceProc(pfQueueServiceFuncType fnc);
int pfQueue::getNumServiceProcs(void);
int pfQueue::getServiceProcPID(int which);
void pfQueue::setSortMode(int boolean);
int pfQueue::getSortMode(void);
int pfQueue::getElementSize(void);
void pfQueue::setInputRange(int low, int high);
void pfQueue::getInputRange(int *low, int *high);
void pfQueue::setOutputRange(int low, int high);
void pfQueue::getOutputRange(int *low, int *high);
void pfQueue::setSortFunc(pfQueueSortFuncType func);
Page 1
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfQueue(3pf)
pfQueueSortFuncType pfQueue::getSortFunc(void);
int pfQueue::getSortProcPID(pfQueue *queue);
void pfQueue::notifySortProc(void);
int pfQueue::signalAllServiceProcs(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. This is also true for
ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
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.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
Page 2
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfQueue(3pf)
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
The pfQueue data type is implemented as a dynamically sized array of
arbitrary, but homogeneously-sized, elements.
The default constructor pfQueue creates a queue with an element size of 4
bytes. The element size is fixed at creation time and cannot be changed
later. Another constructor is provided that allows the elements size
eltSize and initial allocated queue length, nElts, to be specified for
the pfQueue. new(arena) allocates a pfQueue from the specified memory
arena, or from the process heap if arena is NULL. new allocates a pfQueue
from the default memory arena (see pfGetSharedArena). Like other
pfObjects, pfQueues cannot be created statically, automatically on the
stack or in arrays. pfQueues should be deleted with pfDelete rather than
with the delete operator.
pfQueue::getClassType returns the pfType* for the class pfQueue. The
pfType* returned by pfQueue::getClassType is the same as the pfType*
returned by invoking the virtual function getType 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 the member function isOfType 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 new pfQueue) or with
pfQueue::setArrayLen. pfQueue::getArrayLen returns the current array
length of the pfQueue.
pfQueue::insert adds an element, elt to the the pfQueue. 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
the elements that where inserted first must be removed before the element
itself is removed. The pfQueue::insertFront 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
Page 3
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfQueue(3pf)
cleanly.
pfQueue::remove 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.
pfQueue::attemptRemove removes and returns an element from the queue.
Unlike pfQueue::remove, this command doesn't block if the queue is empty.
Instead, it returns a NULL pointer.
pfQueue::getNum returns the number of elements currently stored in the
pfQueue.
pfQueue::addServiceProc 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 pfQueue::remove and then calling func
with the element just removed from the queue.
The number of currently active service processes is returned by
pfQueue::getNumServiceProcs.
The process ID of a particular service process can be obtained through
pfQueue::getServiceProcPID.
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.
pfQueue::setSortMode 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.
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
Page 4
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfQueue(3pf)
mark, the number of elements on the output queue drops below the low
water mark, or pfQueue::notifySortProc 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.
pfQueue::getSortMode returns the current sort mode value. A non-zero
value indicates sorting mode. A zero value indicates non-sorting, or
normal mode.
pfQueue::getElementSize 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 *).
pfQueue::setInputRange 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.
pfQueue::getInputRange returns currently set water mark values. Values
read by this function may not have taken effect yet.
pfQueue::setOutputRange 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.
pfQueue::getOutputRange returns currently set water mark values. Values
read by this function may not have taken effect yet.
pfQueue::setSortFunc 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
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
Page 5
pfQueue(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfQueue(3pf)
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.
pfQueue::getSortFunc returns a pointer to the current sorting function.
This may not be the sort function currently in use.
pfQueue::getSortProcPID 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.
pfQueue::notifySortProc 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.
pfQueue::signalAllServiceProcs 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 pfQueue::signalAllServiceProcs 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
