Inheritance diagram

Collaboration diagram

Description

SFXHeap Class and SFXClusterHeap Class

Both the SFXHeap class and the SFXClusterHeap class provide the dynamic heap management function.

The SFXClusterHeap class provides the block allocation mechanism, but the SFXHeap class does not.

If the heap size is not updated frequently, using the SFXHeap class is recommended from the perspective of memory efficiency.

Attach Function and Detach Function

The SFXHeap::Attach function delegates the control privilege of Void data to the SFXHeap object. The SFXHeap::Detach function has the reverse functionality.

What is delegation?: In object oriented programming, delegation means that an object have another deputy object behave like itself.

SFXHeap<SInt16> heap;
VoidPtr swap;

// allocate memory
swap = MemoryAllocate(10240); 
...

// delegate the control privilege of Void data(swap) to the SFXHeap object(heap)
heap.Attach(swap, 10240);
// hereafter, the Void data(swap) will be handled as the SFXHeap object

･･･

// after used, the allocated memory will be released automatically

SFXHeap heap;
VoidPtr swap;
UInt32 length;

...

// delegate the control privilege of SFXHeap object(heap) to the Void data(swap)
swap = heap.Detach(&length);
// hereafter, the SFXHeap object(heap) will be handled as the Void data(swap)

...

// after used, the Void data(swap) must be released explicitly
MemoryFree(swap);

Reference

SFXClusterHeap | Heap Class

Member

Return value

Description

This function attaches the specified area to this heap object. After this function is executed, the specified area can be handled as the SFXHeap object.

	Note
	When this heap object is released, the specified area will be released automatically together with this heap object.

Example

SFXHeap<Byte> heap;
VoidPtr swap;

// allocate the memory of 10240 bytes to swap
swap = MemoryAllocate(10240); 
...

// attach the swap area to the heap object
heap.Attach(swap, 10240);
// hereafter, the swap area can be handled as the heap object

･･･

// after used, the swap area will be released automatically together with the heap object

Reference

SFXHeap::Detach | SFXHeap::Contains

Return value

Description

This function checks whether or not this heap object contains some of the specified area.

Example

SFXHeap<Byte> heap(100, 10);

heap.Resize(100);  // set the size of the heap object to 100 bytes

// area1 is contained by the heap object
VoidConstPtr area1 = static_cast<BytePtr>(heap.GetHeap()) + 10;  

// area2 is not contained by the heap object
VoidConstPtr area2 = static_cast<BytePtr>(heap.GetHeap()) + 100;  

if (heap.Contains(area1, 200)) {

    // since the heap object contains the area1 area, the statement below will be executed
    TRACE("The heap object contains area1.");
}

if (!heap.Contains(area2, 200)) {

    // since the heap object does not contain the area2 area, the statement below will be executed
    TRACE("The heap object does not contain area2.");
}

Return value

Pointer to the detached heap area

Description

This function detaches and returns the pointer to the heap area which this heap object has controled.

The size of the heap area will be returned into the size argument after this function is called.

	Caution
	The detached heap area will not be copied.

Example

SFXHeap<Byte> heap;
VoidPtr swap;
UInt32 length;

...

// detach the heap area from the heap object and set the swap variable to this pointer
// the size of the detached heap area will be stored into the length variable
swap = heap.Detach(&length);

// hereafter, the heap area of the heap object will be handled via the swap variable

...

// after used, the detached heap area must be released explicitly
MemoryFree(swap);

Reference

SFXHeap::Attach

Description

This function gets the empty heap object.

Description

This function releases the heap area which this heap object manages.

Example

SFXHeap<Byte> heap;

...

heap.Free();   // release the heap area which the heap object manages

Reference

SFXHeap::Resize

Return value

Return the pointer to the heap that the SFXHeap object manages.

Example

SFXHeap<SInt16> heap;

// set heap size
if (heap.Resize(sizeof(SInt16) * 128) == SFERR_NO_ERROR) {
    TRACE("addr = 0x%08X", heap.GetHeap());  // addr = 0x0686FF80
}

Return value

Heap size of this heap object.

Description

This function gets the size of the heap area which this heap object manages.

Example

SFXHeap<Byte> heap;

// set the heap size
if (heap.Resize(0x200) == SFERR_NO_ERROR) {

    // get the heap size
    TRACE("size = 0x%x", heap.GetSize());  // size = 0x200
}

Reference

SFXHeap::Resize | SFXHeap::Attach

Return value

Pointer to the protected area.

Description

If this heap contains some of the specified area, this function will allocate another area outside of this heap area, where the contents of the specified area will be copied. Otherwise, this function will only return the pointer to the specified area.

After you perform some processings regarding to the area protected by the SFXHeap::Protect function, you have to call the SFXHeap::Unprotect function.

	Note
	The SFXHeap::Unprotect function will release the area which is allocated by the SFXHeap::Protect function. If the SFXHeap::Protect function has allocated no area, nothing will happen.

Example

SFXHeap<Byte> heap;
VoidConstPtr protect;

heap.Resize(0x200);  // set the heap size to 0x200 bytes

// _area1 = _heap + 0x100 
// _area2 = _heap + 0x200 
VoidConstPtr _heap(heap.GetHeap());
VoidConstPtr _area1(static_cast<BytePtr>(heap.GetHeap()) + 0x100);
VoidConstPtr _area2(static_cast<BytePtr>(heap.GetHeap()) + 0x200);

TRACE("addr of _heap  = 0x%08X", _heap);   // addr of _heap  = 0x0585BD50
TRACE("addr of _area1 = 0x%08X", _area1);  // addr of _area1 = 0x0585BE50
TRACE("addr of _area2 = 0x%08X", _area2);  // addr of _area2 = 0x0585BF50

// HEAP:   [ _heap, _heap + 0x200 )
// AREA_1: [ _area1, _area1 + 0x100 )
// AREA_2: [ _area2, _area2 + 0x100 )

// HEAP ∩ AREA_1 ≠ Φ
// protect AREA_1
if ((protect = heap.Protect(_area1, 0x100)) != null) {
 
    // the [ protect, protect + 0x100 ) area will be allocated outside of HEAP
    TRACE("addr of protect = 0x%08X", protect); // addr of protect = 0x0585BF80
 
    // unprotect: release the [ protect, protect + 0x100 ) area which Protect() has allocated
    heap.Unprotect(protect, _area1);
}

// HEAP ∩ AREA_2 ＝ Φ
// protect AREA_2
if ((protect = heap.Protect(_area2, 0x100)) != null) {
 
    // since AREA_2 and HEAP have no common area, the value of protect will equal that of _area2
    TRACE("addr of protect = 0x%08X", protect); // addr of protect = 0x0585BF50
 
    // unprotect: since Protect() has allocated no area, nothing will happen
    heap.Unprotect(protect, _area2);
}

Reference

SFXHeap::Unprotect | SFXHeap::Attach | SFXHeap::Contains

Return value

Description

This function resizes this heap. The specified memory will be allocated to this heap.

	Caution
	If this heap is resized, the pointer to the heap which the SFXHeap::GetHeap function returns will be changed too.

Example

SFXHeap<Byte> heap;

heap.Resize(0x200);  // set the heap size to 0x200 bytes

Reference

SFXHeap::Attach | SFXHeap::GetHeap | SFXHeap::GetSize

Description

This function unprotects the area protected by the SFXHeap::Protect function.

If this heap contains some of the area to protect, this function will release the area outside of this heap area which has been allocated by the SFXHeap::Protect function. Otherwise, this function will do nothing.

	Note
	If this heap contains some of the area to protect, the value of the protect argument will be different from that of the heap argument. Otherwise, both values of these two arguments are the same.

Reference

SFXHeap::Protect

Return value

If heap is allocated, return a pointer to the heap. Otherwise return a null pointer.

Return value

Description

Both head address of left heap and that of right heap are compared with.

Return value

Description

Both head address of left heap and that of right heap are compared with.

Return value

Description

Both head address of left heap and that of right heap are compared with.

Return value

Description

Both head address of left heap and that of right heap are compared with.

Return value

Description

Both head address of left heap and that of right heap are compared with.

Return value

Description

Both head address of left heap and that of right heap are compared with.