pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
NAME
pfCreateDPool, pfGetDPoolSize, pfGetDPoolName, pfReleaseDPool,
pfAttachDPool, pfDPoolAlloc, pfDPoolFree, pfDPoolFind, pfDPoolLock,
pfDPoolSpinLock, pfDPoolUnlock, pfDPoolTest, pfDPoolAttachAddr,
pfGetDPoolAttachAddr, pfGetDPoolClassType - Create, control and allocate
from locked memory pools.
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfDataPool* pfCreateDPool(uint size, char *name);
int pfGetDPoolSize(pfDataPool *dpool);
const char* pfGetDPoolName(pfDataPool* dpool);
int pfReleaseDPool(pfDataPool *dpool);
pfDataPool* pfAttachDPool(char *name);
volatile void* pfDPoolAlloc(pfDataPool *dpool, uint size, int id);
int pfDPoolFree(pfDataPool *dpool, void *dpmem);
volatile void* pfDPoolFind(pfDataPool *dpool, int id);
int pfDPoolLock(void *dpmem);
int pfDPoolSpinLock(void* dpmem, int spins, int block);
void pfDPoolUnlock(void *dpmem);
int pfDPoolTest(void *dpmem);
void pfDPoolAttachAddr(void *addr);
void* pfGetDPoolAttachAddr(void);
pfType * pfGetDPoolClassType(void);
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfDataPool is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfDataPool. Casting an object of
class pfDataPool 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);
Page 1
pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
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 pfDataPool can also be used with these
functions designed for objects of class pfMemory.
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);
PARAMETERS
dpool identifies a pfDataPool.
DESCRIPTION
A pfDataPool is similar to a shared memory malloc arena but adds the
ability to lock/unlock pfDataPool memory for multiprocessing
applications. The datapool functions allow related or unrelated
processes to share data and provide a means for locking data blocks to
eliminate data collision. These functions use the shared arena functions
(see usinit).
pfCreateDPool creates and returns a handle to a pfDataPool. size is the
size in bytes of the pfDataPool. name is the name of the pfDataPool and
is also the name of the memory-mapped file used by the pfDataPool. This
file is created in the directory "/usr/tmp" unless the environment
variable PFTMPDIR is defined, in which case the file is created in the
directory named in the PFTMPDIR environment variable. name should be
unique among all pfDataPool names and only a single process should create
a given pfDataPool with name name.
pfGetDPoolClassType return the pfType* for the class pfDataPool. The
Page 2
pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
pfType* returned is the same as the pfType* returned by invoking
pfGetType on any instance of class pfDataPool. 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.
pfGetDPoolSize and pfGetDPoolName return the size in bytes and the string
name of dpool respectively.
pfAttachDPool allows the calling process to attach to a pfDataPool with
name name that may have been created by another process. A handle to the
found pfDataPool is returned or NULL if it was not found or could not be
accessed.
pfReleaseDPool hides dpool so that no other processes may attach to it
although all previously attached processes may still access it.
Additionally, a released pfDataPool will be removed from the file system
(deleted) once all attached processes exit. pfReleaseDPool returns TRUE
if successful and FALSE otherwise.
pfDPoolAlloc returns a pointer to a block of memory of size bytes that
was allocated out of dpool or NULL if there is not enough available
memory in dpool. size is in bytes and can range from 1 to the size of
the pfDataPool. The actual size allocated is always rounded up to the
next 16 byte boundary. id is an integer id assigned to the block of
memory that is used to reference it by pfDPoolFind. Block id's should be
unique or the results are undefined.
pfDPoolFind returns a pointer to a block of pfDataPool memory which is
identified by id or NULL if id was not found. The calling process must
be attached to the datapool memory.
pfDPoolFree frees the memory block previously allocated by pfDPoolAlloc
and makes it available to be reallocated.
pfDPoolLock, pfDPoolSpinLock and pfDPoolUnlock lock and unlock access to
a block of pfDataPool memory that was allocated by pfDPoolAlloc. When
the lock cannot be acquired, pfDPoolLock yields the processor causing the
current thread to block until the lock is available. pfDPoolSpinLock
provides more control by accepting arguments to control the spinning and
blocking. When block is FALSE, pfDPoolSpinLock returns rather than
yielding the processor if the lock cannot be acquired. spins specifies
the number of times to spin before yielding or returning. A spins value
of -1 invokes the default, currently 600. pfDPoolLock and
pfDPoolSpinLock return 1 upon acquisition of the lock, 0 upon failure to
acquire the lock and -1 upon error. pfDPoolUnlock relinquishes the lock
on the block of memory.
There are a fixed number of locks (currently 4096) allocated for each
pfDataPool and a new lock is consumed when an allocation in that
pfDataPool is first locked. Subsequent releases and locks do not require
Page 3
pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
further lock allocations.
Example:
typedef struct SharedData
{
float a, b, c;
} SharedData;
pfDataPool *pool;
SharedData *data;
:
/* create a DataPool with room for 4 SharedData structures */
pool = pfCreateDPool(4*sizeof(SharedData), "dpoolForSharedData");
/* allocate SharedData structure in the data pool with ID=153 */
data = (SharedData*)pfDPoolAlloc(pool, sizeof(SharedData), 153);
:
/* write to the DataPool with cooperative mutual exclusion */
pfDPoolLock((void*)data);
data->a = 370.0;
data->b = 371.0;
data->c = 407.0;
pfDPoolUnlock((void*)data);
pfDPoolLock attempts to acquire a hardware lock associated with dpmem.
If another process has already acquired the lock, the calling process
will not return until the lock is acquired. Whether the process blocks
or spins is a function of the machine configuration. (see usconfig).
pfDPoolUnlock unlocks dpmem. A process which double-trips a lock by
calling pfDPoolLock twice in succession will block until the lock is
unset by another process. A process may unlock a lock that was locked by
a different process. pfDPoolTest returns 0 if dpmem is unlocked and 1 if
it is locked.
pfDataPool memory may be accessed without using the lock and unlock
feature; however this defeats the mutual exclusion feature provided by
pfDataPool functions.
A data pool must occupy the same range of virtual memory addresses in all
processes that attach to it. pfAttachDPool will fail if something else
has already been mapped into the required address space, e.g. as a result
of mmap or sbrk. To minimize this risk, pfCreateDPool tries to place new
datapools above the main shared memory arena created by pfInitArenas.
The address at which the next datapool will be created can be overridden
by calling pfDPoolAttachAddr with the addr argument specifying the
desired address. An addr of NULL tells Performer to return to its normal
placement efforts. The next attachment address is returned by
pfGetDPoolAttachAddr.
Page 4
pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages
In the absence of a shared memory arena created by pfInitArenas,
pfCreateDPool lets the kernel choose the data pool placement.
Deleting a data pool with pfDelete or unmaps the data pool from virtual
memory as well as deleting the pfDataPool data structure.
NOTES
pfDataPool functionality is not currently supported under the single
processor version of Performer on Linux.
When a datapool is created, a file is created in "/usr/tmp" or PFTMPDIR.
The file name will end with the string ".pfdpool". If pfReleaseDPool is
not called to unlink the datapool, this file will remain in the file
system after the program exits, taking up disk space.
When using pfDataPools between unrelated processes, you can reduce memory
conflicts by having the application that uses more virtual memory create
the datapool and having the smaller application attach to the datapool
before allocating memory that might cause conflicts. Alternately, if an
address is known to be safe for both applications, it can be specified
using pfDPoolAttachAddr.
SEE ALSO
amalloc, pfInitArenas, usconfig, usinit, ussetlock, ustestlock,
usunsetlock
Page 5
