RWTValVirtualArray(3C++) RWTValVirtualArray(3C++)
Name
RWTValVirtualArray<T> - Rogue Wave library class
Synopsis
#include <rw/tvrtarry.h>
RWVirtualPageHeap* heap;
RWTValVirtualArray<T> array(1000L, heap);
Description
This class represents a virtual array of elements of type T of almost any
length. Individual elements are brought into physical memory as needed
basis. If an element is updated it is automatically marked as "dirty"
and will be rewritten to the swapping medium. The swap space is provided
by an abstract page heap which is specified by the constructor. Any
number of virtual arrays can use the same abstract page heap. You must
take care that the destructor of the abstract page heap is not called
before all virtual arrays built from it have been destroyed. The class
supports reference counting using a copy-on-write technique, so (for
example) returning a virtual array by value from a function is as
efficient as it can be. Be aware, however, that if the copy-on-write
machinery finds that a copy must ultimately be made, then for large
arrays this could take quite a bit of time. For efficiency, more than
one element can (and should) be put on a page. The actual number of
elements is equal to the page size divided by the element size, rounded
downwards. Example: for a page size of 512 bytes, and an element size of
8, then 64 elements would be put on a page. The indexing operator
(operator[](long)) actually returns an object of type
RWTVirtualElement<T>. Consider this example:
double d = vec[j];
vec[i] = 22.0;
Assume that vec is of type RWTValVirtualArray<double>. The expression
vec[j] will return an object of type RWTVirtualElement<double>, which
will contain a reference to the element being addressed. In the first
line, this expression is being used to initialize a double. The class
RWTVirtualElement<T> contains a type conversion operator to convert
itself to a T, in this case a double. The compiler uses this to
initialize d in the first line. In the second line, the expression
vec[i] is being used as an lvalue. In this case, the compiler uses the
assignment operator for RWTVirtualElement<T>. This assignment operator
recognizes that the expression is being used as an lvalue and
Page 1
RWTValVirtualArray(3C++) RWTValVirtualArray(3C++)
automatically marks the appropriate page as "dirty," thus guaranteeing
that it will be written back out to the swapping medium. Slices, as well
as individual elements, can also be addressed. These should be used
wherever possible as they are much more efficient because they allow a
page to be locked and used multiple times before unlocking. The class T
must have:
well-defined copy semantics (T::T(const T&) or equiv.);
well-defined assignment semantics (T::operator=(const T&) or
equiv.).
Persistence
In addition, you must never take the address of an element. None
Example
In this example, a virtual vector of objects of type ErsatzInt is
exercised. A disk-based page heap is used for swapping space.
#include <rw/tvrtarry.h>
#include <rw/rstream.h>
#include <rw/diskpage.h>
#include <stdlib.h>
#include <stdio.h>
struct ErsatzInt {
char buf[8];
ErsatzInt(int i) { sprintf(buf, "%d", i); }
friend ostream& operator<<(ostream& str, ErsatzInt& i)
{ str << atoi(i.buf); return str; }
};
main() {
RWDiskPageHeap heap;
RWTValVirtualArray<ErsatzInt> vec1(10000L, &heap);
for (long i=0; i<10000L; i++)
vec1[i] = i; // Some compilers may need a cast here
cout << vec1[100] << endl; // Prints "100"
cout << vec1[300] << endl; // Prints "300"
RWTValVirtualArray<ErsatzInt> vec2 = vec1.slice(5000L, 500L);
cout << vec2.length() << endl; // Prints "500"
cout << vec2[0] << endl; // Prints "5000";
return 0;
}
Program output:
100
300
500
Page 2
RWTValVirtualArray(3C++) RWTValVirtualArray(3C++)
Public Constructors
5000
RWTValVirtualArray<T>(long size, RWVirtualPageHeap* heap);
Construct a vector of length size. The pages for the vector will be
allocated from the page heap given by heap which can be of any type.
RWTValVirtualArray<T>(const RWTValVirtualArray<T>& v);
Constructs a vector as a copy of v. The resultant vector will use the
same heap and have the same length as v. The actual copy will not be
made until a write, minimizing the amount of heap allocations and copying
that must be done.
RWTValVirtualArray<T>(const RWTVirtualSlice<T>& sl);
Constructs a vector from a slice of another vector. The resultant vector
will use the same heap as the vector whose slice is being taken. Its
length will be given by the length of the slice. The copy will be made
immediately.
Public Destructor
~RWTValVirtualArray<T>();
Releases all pages allocated by the vector.
Public Operators
RWTValVirtualArray&
operator=(const RWTValVirtualArray<T>& v);
Sets self to a copy of v. The resultant vector will use the same heap
and have the same length as v. The actual copy will not be made until a
write, minimizing the amount of heap allocations and copying that must be
done.
void
operator=(const RWTVirtualSlice<T>& sl);
Sets self equal to a slice of another vector. The resultant vector will
Page 3
RWTValVirtualArray(3C++) RWTValVirtualArray(3C++)
use the same heap as the vector whose slice is being taken. Its length
will be given by the length of the slice. The copy will be made
immediately.
T
operator=(const T& val);
Sets all elements in self equal to val. This operator is actually quite
efficient because it can work with many elements on a single page at
once. A copy of val is returned.
T
operator[](long i) const;
Returns a copy of the value at index i. The index i must be between zero
and the length of the vector less one or an exception of type
TOOL_LONGINDEX will occur.
RWTVirtualElement<T>
operator[](long);
Returns a reference to the value at index i. The results can be used as
an lvalue. The index i must be between zero and the length of the vector
less one or an exception of type TOOL_LONGINDEX will occur.
Public Member Functions
long
length() const;
Returns the length of the vector.
T
val(long i) const;
Returns a copy of the value at index i. The index i must be between zero
and the length of the vector less one or an exception of type
TOOL_LONGINDEX will occur.
void
set(long i, const T& v);
Sets the value at the index i to v. The index i must be between zero and
the length of the vector less one or an exception of type TOOL_LONGINDEX
will occur.
Page 4
RWTValVirtualArray(3C++) RWTValVirtualArray(3C++)
RWTVirtualSlice<T>
slice(long start, long length);
Returns a reference to a slice of self. The value start is the starting
index of the slice, the value length its extent. The results can be used
as an lvalue.
void
reshape(long newLength);
Change the length of the vector to newLength. If this results in the
vector being lengthened then the value of the new elements is undefined.
RWVirtualPageHeap*
heap() const;
Returns a pointer to the heap from which the vector is getting its pages.
Page 5
