RWVirtualPageHeap(3C++) RWVirtualPageHeap(3C++)
NameRWVirtualPageHeap - Rogue Wave library class
Synopsis
#include <rw/vpage.h>
(Abstract base class)
Description
This is an abstract base class representing an abstract page heap of
fixed sized pages. The following describes the model by which
specializing classes of this class are expected to work. You allocate a
page off the abstract heap by calling member function allocate() which
will return a memory "handle," an object of type RWHandle. This handle
logically represents the page. In order to use the page it must first be
"locked" by calling member function lock() with the handle as an
argument. It is the job of the specializing class of RWVirtualPageHeap
to make whatever arrangements are necessary to swap in the page
associated with the handle and bring it into physical memory. The actual
swapping medium could be disk, expanded or extended memory, or a machine
someplace on a network. Upon return, lock() returns a pointer to the
page, now residing in memory. Once a page is in memory, you are free to
do anything you want with it although if you change the contents, you
must call member function dirty() before unlocking the page. Locked
pages use up memory. In fact, some specializing classes may have only a
fixed number of buffers in which to do their swapping. If you are not
using the page, you should call unlock(). After calling unlock() the
original address returned by lock() is no longer valid -- to use the page
again, it must be locked again with lock(). When you are completely done
with the page then call deallocate() to return it to the abstract heap.
In practice, managing this locking and unlocking and the inevitable type
casts can be difficult. It is usually easier to design a class that can
work with an abstract heap to bring things in and out of memory
automatically. Indeed, this is what has been done with class
RWTValVirtualArray<T>, which represents a virtual array of elements of
type T. Elements are automatically swapped in as necessary as they are
addressed.
Persistence
None
Example
This example illustrates adding N nodes to a linked list. In this linked
list, a "pointer" to the next node is actually a handle.
Page 1
RWVirtualPageHeap(3C++) RWVirtualPageHeap(3C++)
#include <rw/vpage.h>
struct Node {
int key;
RWHandle next;
};
RWHandle head = 0;
void addNodes(RWVirtualPageHeap& heap, unsigned N) {
for (unsigned i=0; i<N; i++){
RWHandle h = heap.allocate();
Node* newNode = (Node*)heap.lock(h);
newNode->key = i;
newNode->next = head;
head = h;
heap.dirty(h);
heap.unlock(h);
}
}
Public Constructor
RWVirtualPageHeap(unsigned pgsize);
Sets the size of a page.
Public Destructor
virtual ~RWVirtualPageHeap();
The destructor has been made virtual to give specializing classes a
chance to deallocate any resources that they may have allocated.
Public Member Functions
unsigned
pageSize() const;
Returns the page size for this abstract page heap.
Page 2
RWVirtualPageHeap(3C++) RWVirtualPageHeap(3C++)
Public Pure Virtual Functions
virtual RWHandle
allocate() = 0
Allocates a page off the abstract heap and returns a handle for it. If
the specializing class is unable to honor the request, then it should
return a zero handle.
virtual void
deallocate(RWHandle h) = 0;
Deallocate the page associated with handle h. It is not an error to
deallocate a zero handle.
virtual void
dirty(RWHandle h) = 0;
Declare the page associated with handle h to be "dirty." That is, it has
changed since it was last locked. The page must be locked before calling
this function.
virtual void*
lock(RWHandle h) = 0;
Lock the page, swapping it into physical memory, and return an address
for it. A nil pointer will be returned if the specializing class is
unable to honor the lock. The returned pointer should be regarded as
pointing to a buffer of the page size.
virtual void
unlock(RWHandle h) = 0;
Unlock a page. A page must be locked before calling this function.
After calling this function the address returned by lock() is no longer
valid.
Page 3
