pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
NAMEpfDataPool - Create, control and allocate from locked memory pools.
FUNCTION SPECIFICATION
#include <Performer/pr/pfDataPool.h>
static pfDataPool* pfDataPool::create(uint size, char *name);
static pfDataPool* pfDataPool::attach(char *name);
int pfDataPool::getDPoolSize(void);
const char* pfDataPool::getName(void);
int pfDataPool::release(void);
volatile void* pfDataPool::alloc(uint size, int id);
int pfDataPool::free(void *dpmem);
volatile void* pfDataPool::find(int id);
static int pfDataPool::lock(void *dpmem);
static int pfDataPool::lock(void *dpmem, int spins, int block);
static void pfDataPool::unlock(void *dpmem);
static int pfDataPool::test(void *dpmem);
void pfDataPool::setAttachAddr(void *addr);
void* pfDataPool::getAttachAddr(void);
static pfType * pfDataPool::getClassType(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. 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();
Page 1
pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
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.
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();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
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).
pfDataPool::create 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.
pfDataPool::getClassType return the pfType* for the class pfDataPool.
The pfType* returned is the same as the pfType* returned by invoking
getType 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 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.
Page 2
pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
The member functions pfDataPool::getDPoolSize and pfDataPool::getName
respectively return the size in bytes and the string name of a
pfDataPool.
pfDataPool::attach 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.
pfDataPool::release 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. The member function release
returns TRUE if successful and FALSE otherwise.
pfDataPool::alloc returns a pointer to a block of memory of size bytes
that was allocated out of the pfDataPool or NULL if there is not enough
available memory. 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 the member function find. Block
id's should be unique or the results are undefined.
pfDataPool::find 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.
The member function free frees the memory block previously allocated by
alloc and makes it available to be reallocated.
pfDataPool::lock and pfDataPool::unlock lock and unlock access to a block
of pfDataPool memory that was allocated by pfDataPool::alloc. When the
lock cannot be acquired, pfDataPool::lock yields the processor causing
the current thread to block until the lock is available. Extra arguments
to pfDataPool::lock provides more control by accepting arguments to
control the spinning and blocking. When block is FALSE, pfDataPool::lock
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.
pfDataPool::lock returns 1 upon acquisition of the lock, 0 upon failure
to acquire the lock and -1 upon error. pfDataPool::unlock 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
further lock allocations.
Example:
Page 3
pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
typedef struct SharedData
{
float a, b, c;
} SharedData;
pfDataPool *pool;
SharedData *data;
:
/* create a DataPool with room for 4 SharedData structures */
pool = pfDataPool::create(4*sizeof(SharedData), "dpoolForSharedData");
/* allocate SharedData structure in the data pool with ID=153 */
data = (SharedData*)pool->alloc(sizeof(SharedData), 153);
:
/* write to the DataPool with cooperative mutual exclusion */
pfDataPool::lock((void*)data);
data->a = 370.0;
data->b = 371.0;
data->c = 407.0;
pfDataPool::unlock((void*)data);
pfDataPool::lock 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). pfDataPool::unlock unlocks dpmem. A process which double-
trips a lock by calling the member function lock 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. pfDataPool::test 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. pfDataPool::attach 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, the member function
create 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 pfDataPool::setAttachAddr 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 pfDataPool::getAttachAddr.
In the absence of a shared memory arena created by pfInitArenas, create
lets the kernel choose the data pool placement.
Deleting a data pool with pfDelete or delete unmaps the data pool from
Page 4
pfDataPool(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages
virtual memory as well as deleting the pfDataPool data structure.
NOTESpfDataPool 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
pfDataPool::release 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 pfDataPool::setAttachAddr.
SEE ALSO
amalloc, pfInitArenas, usconfig, usinit, ussetlock, ustestlock,
usunsetlock
Page 5
