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 SFXHeap class provides the block allocation mechanism, but the SFXClusterHeap class does not.

If the heap size is updated a little bit at a time frequently, using the SFXClusterHeap class is recommended from the perspective of memory efficiency.

Attach Function and Detach Function

The SFXClusterHeap::Attach function delegates the control privilege of specified Void data to the SFXClusterHeap object. The SFXClusterHeap::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.

SFXClusterHeap<SInt16> heap;
VoidPtr swap;

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

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

...

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

SFXClusterHeap heap;
VoidPtr swap;
UInt32 length;

...

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

...

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

Reference

SFXHeap | Heap Class

Member

Description

As for arguments, the minimum size to allocate the heap memory is specified in bytes as the threshold argument, and the cluster size to increase or decrease the heap memory is specified in bytes as the cluster argument.

If no argument is specified, "threshold = 0" and "cluster = 1" are set by default.

	Caution
	In the constructor, heap is not allocated. Before using heap, never forget to call the Attach function or the Resize function.

Example

This is an example of constructor with arguments.

SFXClusterHeap myheap(100, 10);

In this example, the minimum heap size is set to 100 bytes. When bigger than 100 bytes, it will be 110 bytes, 120 bytes, 130 bytes, and so on.

Reference

SFXClusterHeap::SetThreshold | SFXClusterHeap::SetCluster | SFXClusterHeap::Attach | SFXClusterHeap::Resize

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 SFXClusterHeap object.

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

Example

SFXClusterHeap<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

SFXClusterHeap::Detach | SFXClusterHeap::Contains

Return value

Description

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

Example

SFXClusterHeap<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

SFXClusterHeap<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

SFXClusterHeap::Attach

Description

This function gets the empty heap object.

Description

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

Example

SFXClusterHeap<Byte> heap;

...

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

Reference

SFXClusterHeap::Resize

Return value

Return the cluster size in bytes to increase or decrease the heap.

Example

SFXClusterHeap<SInt16> heap;

// set the cluster size when allocating the heap to 10 bytes
heap.SetCluster(10);

TRACE("cluster size = %d", heap.GetCluster());  // cluster size = 10

Reference

SFXClusterHeap::SetCluster | SFXClusterHeap::Resize

Return value

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

Example

SFXClusterHeap<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

SFXClusterHeap<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

SFXClusterHeap::Resize | SFXClusterHeap::Attach

Return value

Return the minimum heap size(in bytes).

Example

SFXClusterHeap<SInt16> heap;

// set the minimum heap size to 100 bytes
heap.SetThreshold(100);

TRACE("minimum heap size = %d", heap.GetThreshold());  // minimum heap size = 100

Reference

SFXClusterHeap::SetThreshold | SFXClusterHeap::Resize

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 SFXClusterHeap::Protect function, you have to call the SFXClusterHeap::Unprotect function.

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

Example

SFXClusterHeap<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

SFXClusterHeap::Unprotect | SFXClusterHeap::Attach | SFXClusterHeap::Contains

Return value

Description

The heap size is determined by the value of the minimun heap size and the cluster size. The minimun heap size is set with the threshold argument of the SFXClusterHeap::SFXClusterHeap constructor or the SFXClusterHeap::SetThreshold function. And the cluster size is specified with the threshold argument of the SFXClusterHeap::SFXClusterHeap constructor or the SFXClusterHeap::SetCluster function.

If the value of size is smaller than or equals that of the minimun heap size, the allocated heap size equals the value of the minimun heap size in effect.

Otherwise, the heap bigger than the minimun heap size is allocated by the cluster size.

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

Example

SFXClusterHeap<Byte> heap;

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

Reference

SFXClusterHeap::SFXClusterHeap | SFXClusterHeap::SetCluster | SFXClusterHeap::SetThreshold | SFXClusterHeap::Attach | SFXClusterHeap::GetHeap | SFXClusterHeap::GetSize

Description

This function sets the cluster size to increase or decrease the heap.

Default: Value specified in the cluster argument of the SFXClusterHeap::SFXClusterHeap constructor[Unit: byte]. 1 byte if not specified.

Example

SFXClusterHeap<SInt16> heap;

// set the cluster size when allocating the heap to 10 bytes
heap.SetCluster(10);

TRACE("cluster = %d", heap.GetCluster());  // cluster = 10

Reference

SFXClusterHeap::GetCluster | SFXClusterHeap::SFXClusterHeap | SFXClusterHeap::Resize

Description

This function sets the minimum heap size.

Default: Value specified in the threshold argument of the SFXClusterHeap::SFXClusterHeap constructor[Unit: byte]. 0 byte if not specified.

Example

SFXClusterHeap<SInt16> heap;

// set the minimum heap size to 100 bytes
heap.SetThreshold(100);

TRACE("minimum heap size = %d", heap.GetThreshold());  // minimum heap size = 100

Reference

SFXClusterHeap::GetThreshold | SFXClusterHeap::SFXClusterHeap | SFXClusterHeap::Resize

Description

This function unprotects the area protected by the SFXClusterHeap::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 SFXClusterHeap::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

SFXClusterHeap::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.