Class: TMemorySurrogate

Declaration: Memory.h

Taxonomy Categories:

Member Functions:

TMemorySurrogate
~TMemorySurrogate
operator=
operator<<=
operator>>=
GetLength
SetLength
GetStartAddress
SetStartAddress
FillWith
FillWithZeros
CopyFrom
Hash

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TMemoryRange

Purpose:

TMemorySurrogate is a concrete class that is used to describe a range of memory.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This class cannot be derived.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements. Note: This class does not allocate memory. It is used to describe extant memory ranges.

Member Function: TMemorySurrogate::TMemorySurrogate

TMemorySurrogate ()
TMemorySurrogate (void * start)
TMemorySurrogate (void * start, size_t length)
TMemorySurrogate (const TMemorySurrogate & aRange)

Interface Category:

API.

Purpose:

Default constructor. Creates a memory surrogate that describes a zero-length range of memory starting at address zero.
Creates a memory surrogate that describes a zero-length range of memory starting at the address passed as an argument to the constructor (start).
Creates a memory surrogate that describes a range of memory of length length starting at the address start.
Copy constructor.

Calling Context:

Called to create an object whose internal state will be set by some other member function, such as a stream-in operator.
Called to construct a memory surrogate that denotes a specific memory address.
Called to construct a memory surrogate that denotes a specific memory range.
Called to copy an object.

Parameters:

Takes no parameters.
void * start -Specifies the starting address of the memory range.
void * start -Specifies the starting address of the memory range.
size_t length -Specifies the length of the memory range.
const TMemorySurrogate & aRange -Specifies the object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMemorySurrogate::~TMemorySurrogate

~ TMemorySurrogate ()

Interface Category:

API.

Purpose:

Destructor. Destroys an object, but does not release the memory range described by the object.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMemorySurrogate::operator=

TMemorySurrogate & operator =(const TMemorySurrogate & theMemory)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TMemorySurrogate & theMemory -The object that supplies the value for the right-hand side of the assignment statement.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMemorySurrogate::operator<<=

TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if the object read in from the stream has an invalid version number.

Concurrency:

Not multithread safe.

Other Considerations:

None

Member Function: TMemorySurrogate::operator>>=

TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMemorySurrogate::GetLength

inline size_t GetLength () const

Interface Category:

API.

Purpose:

Returns the length of the memory range described by the object.

Calling Context:

Called to determine the amount of memory described by the object.

Parameters:

Takes no parameters.

Return Value:

The length of the memory range described by the object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMemorySurrogate::SetLength

inline void SetLength (size_t length)

Interface Category:

API.

Purpose:

Sets the length of the memory range described by the object.

Calling Context:

Called to change the memory range described by the object.

Parameters:

size_t length -The new length value to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMemorySurrogate::GetStartAddress

inline void * GetStartAddress () const

Interface Category:

API.

Purpose:

Returns the starting address of the memory range described by the object.

Calling Context:

Called to determine the memory range described by the object.

Parameters:

Takes no parameters.

Return Value:

The starting address of the memory range described by the object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMemorySurrogate::SetStartAddress

inline void SetStartAddress (void * newStart)

Interface Category:

API.

Purpose:

Sets the starting address of the memory range described by the object.

Calling Context:

Called to change the memory range described by the object.

Parameters:

void * newStart -The new starting address to set.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TMemorySurrogate::FillWith

void FillWith (unsigned long thePattern)
void FillWith (unsigned short thePattern)
void FillWith (unsigned char thePattern)
void FillWith (const TMemorySurrogate & thePattern)

Interface Category:

API.

Purpose:

Fills the memory range described by the object by repeatedly copying the parameter value.
Fills the memory range described by the object by repeatedly copying the parameter value.
Fills the memory range described by the object by repeatedly copying the parameter value.
Fills the memory range described by the object by repeatedly copying the contents of the memory described by the memory surrogate passed into the member function. This member function copies overlapping ranges correctly.

Calling Context:

Called to fill a range of memory with a repeating byte pattern.
Called to fill a range of memory with a repeating byte pattern.
Called to fill a range of memory with a repeating byte pattern.
Called to fill a range of memory with a repeating byte pattern.

Parameters:

unsigned long thePattern -A 4-byte pattern packed into an unsigned long.
unsigned short thePattern -A 2-byte pattern packed into an short.
unsigned char thePattern -A byte used to fill memory.
const TMemorySurrogate & thePattern -Describes a memory range that contains the byte pattern to be used to fill memory.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The FillWith routine is optimized for each platform; it is implemented to work as efficiently as possible on each platform.

Member Function: TMemorySurrogate::FillWithZeros

void FillWithZeros ()

Interface Category:

API.

Purpose:

Fills the memory region described by the TMemorySurrogate object with zeros.

Calling Context:

Called to initialize or erase the contents of a memory region.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The FillWithZeros routine is optimized for each platform; it is implemented to work as efficiently as possible on each platform.

Member Function: TMemorySurrogate::CopyFrom

void CopyFrom (const TMemorySurrogate & theSource)

Interface Category:

API.

Purpose:

Copies the contents of theSource memory to the memory region described by *this. The amount of memory copied is the minimum of the sizes of the two memory ranges. The routine copies overlapping ranges correctly.

Calling Context:

Called to copy the contents of one memory range to another.

Parameters:

const TMemorySurrogate & theSource -Describes the memory range from which data is copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The CopyFrom routine is optimized for each platform; it is implemented to work as efficiently as possible on each platform.

Member Function: TMemorySurrogate::Hash

long Hash () const

Interface Category:

API.

Purpose:

Returns a hash value.

Calling Context:

Called whenever a hash value is required for the object.

Parameters:

Takes no parameters.

Return Value:

Returns a HashResult.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.