SFXClusterHeap

Class that represents a heap that supports block allocation.

#include <SFXClusterHeap.h.hpp>

class SFXClusterHeap;

SFMTYPEDEFCLASS(SFXClusterHeap)

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.

Example 460. How to Use the Attach Function

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

Example 461. How to Use the Detach Function

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

Constructor/Destructor
SFXClusterHeap( `Void` ) Constructor of SFXClusterHeap class.
SFXClusterHeap( `UInt16` threshold , `UInt16` cluster ) Constructor of SFXClusterHeap class.

Public Functions
`SFCError`	Attach( `VoidPtr` heap , `UInt32` size ) Delegate the control privilege of specified Void data to the SFXClusterHeap object.
`Bool`	Contains( `VoidConstPtr` heap , `UInt32` size ) Check whether the attached SFXClusterHeap object contains some of the specified data of Void type or not.
`VoidPtr`	Detach( `UInt32Ptr` size = null ) Delegate the control privilege of SFXClusterHeap object to the specified Void data.
static `SFXClusterHeap< T > const &`	EmptyInstance( `Void` ) Get an empty heap.
`Void`	Free( `Void` ) Release the heap that the SFXClusterHeap object manages.
`UInt16`	GetCluster( `Void` ) Get the cluster size to increase or decrease the heap.
`VoidPtr`	GetHeap( `Void` ) Get the pointer to the heap that the SFXClusterHeap object manages.
`VoidConstPtr`	GetHeap( `Void` ) Get the pointer to the heap that the SFXClusterHeap object manages.
`UInt32`	GetSize( `Void` ) Get the heap size.
`UInt16`	GetThreshold( `Void` ) Get the minimum heap size.
`VoidConstPtr`	Protect( `VoidConstPtr` heap , `UInt32` size ) Allocate the specified heap safely.
`SFCError`	Resize( `UInt32` size ) Set the heap size.
`Void`	SetCluster( `UInt16` cluster ) Set the cluster size to increase or decrease the heap.
`Void`	SetThreshold( `UInt16` threshold ) Set the minimum heap size.
`Void`	Unprotect( `VoidConstPtr` protect , `VoidConstPtr` heap ) Release the heap allocated by the SFXClusterHeap::Protect function.
`Bool`	operator==( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator==( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator==( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of "==".
`Bool`	operator>=( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator>=( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator>=( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of ">=".
`Bool`	operator>( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator>( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator>( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of ">".
`Bool`	operator<=( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator<=( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator<=( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of "<=".
`Bool`	operator<( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator<( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator<( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of "<".
`Bool`	operator!=( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator!=( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator!=( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of "!=".
`Bool`	operator==( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator==( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator==( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of "==".

Global Functions
`Bool`	operator>=( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator>=( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator>=( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of ">=".
`Bool`	operator>( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator>( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator>( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of ">".
`Bool`	operator<=( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator<=( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator<=( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of "<=".
`Bool`	operator<( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator<( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator<( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of "<".
`Bool`	operator!=( `SFXClusterHeap< T > const &` left , `SFXClusterHeap< M > const &` right ) operator!=( `VoidConstPtr` left , `SFXClusterHeap< T > const &` right ) operator!=( `SFXClusterHeap< T > const &` left , `VoidConstPtr` right ) Check the relation of "!=".

SFXClusterHeap::SFXClusterHeap

Constructor of SFXClusterHeap class.

[ public, explicit ]
SFXClusterHeap(Void);

[ public, explicit ]
SFXClusterHeap(
    UInt16 threshold   // minimum heap size (in bytes)
    UInt16 cluster     // cluster size to increase or decrease heap (in bytes)
);

Description

As for arguments, the minimum size to allocate a heap is specified in bytes as the threshold argument.

When updating the heap size more than specified in the threshold argument, the cluster size to update heap is specified in bytes as the cluster argument.

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

In 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::Attach | SFXClusterHeap::Resize

SFXClusterHeap::Attach

Delegate the control privilege of specified Void data to the SFXClusterHeap object.

[ public ]
SFCError Attach(
    VoidPtr heap   // pointer to the heap
    UInt32 size    // heap size
);

Return value

Success : SFERR_NO_ERROR
If the attached SFXClusterHeap object contains some of the specified data : SFERR_INVALID_PARAM

Example

SFXClusterHeap<SInt16> heap;
VoidPtr swap;

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

// delegate the control privilege of swap of Void type 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

Reference

SFXClusterHeap::Detach

SFXClusterHeap::Contains

Check whether the attached SFXClusterHeap object contains some of the specified data of Void type or not.

[ public, const ]
Bool Contains(
    VoidConstPtr heap   // pointer to the heap to compare with
    UInt32 size         // size of heap to compare with (in bytes)
);

Return value

If contain : true
If not contain : false

Example

SFXClusterHeap heap1(100, 10);
heap1.Resize(100);  // set the size of heap1 to 100 bytes
SFXClusterHeap heap2;

// heap2 is that the both ends of heap1 are cut by 10 bytes respectively
heap2.Attach(static_cast<BytePtr>(heap1.GetHeap()) + 10, heap1.GetSize() - 20);  

if (heap2.Contains(heap1.GetHeap(), heap1.GetSize())) {
  // since heap2 contains heap1, this segment is executed
  ...
} else {
  // this segment is not executed
  ...
}

SFXClusterHeap::Detach

Delegate the control privilege of SFXClusterHeap object to the specified Void data.

[ public ]
VoidPtr Detach(
    UInt32Ptr size = null   // pointer to the variable where heap size is stored
);

Return value

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

Description

The heap that the SFXClusterHeap object has is never copied.

The size of heap that the SFXClusterHeap object has is returned to the size argument.

Example

SFXClusterHeap heap;
VoidPtr swap;
UInt32 length;

...

// delegate the control privilege of SFXClusterHeap object(heap) class 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

SFXClusterHeap::Attach

SFXClusterHeap::EmptyInstance

Get an empty heap.

[ public, static ]
SFXClusterHeap< T > const & EmptyInstance(Void);

Description

Get an instance that represents an empty heap.

SFXClusterHeap::Free

Release the heap that the SFXClusterHeap object manages.

[ public ]
Void Free(Void);

Example

SFXClusterHeap<SInt16> heap;

...

heap.Free();   // release heap explicitly

SFXClusterHeap::GetCluster

Get the cluster size to increase or decrease the heap.

[ public, const ]
UInt16 GetCluster(Void);

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 = %d", heap.GetCluster());  // cluster = 10

Reference

SFXClusterHeap::Resize SFXClusterHeap::SetCluster |

SFXClusterHeap::GetHeap

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

[ public ]
VoidPtr GetHeap(Void);

[ public, const ]
VoidConstPtr GetHeap(Void);

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
}

SFXClusterHeap::GetSize

Get the heap size.

[ public, const ]
UInt32 GetSize(Void);

Return value

Return the heap size.

Example

SFXClusterHeap<SInt16> heap;

// set heap size
if (heap.Resize(sizeof(SInt16) * 128) == SFERR_NO_ERROR) {
        TRACE("size = %d", heap.GetSize());  // size = 256
}

Reference

SFXClusterHeap::Resize

SFXClusterHeap::GetThreshold

Get the minimum heap size.

[ public, const ]
UInt16 GetThreshold(Void);

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("threshold = %d", heap.GetThreshold());  // threshold = 100

Reference

SFXClusterHeap::Resize

SFXClusterHeap::Protect

Allocate the specified heap safely.

[ public, const ]
VoidConstPtr Protect(
    VoidConstPtr heap   // pointer to the heap to allocate safely
    UInt32 size         // heap size to allocate safely
);

Return value

Return a pointer to the allocated heap.

Description

If the SFXClusterHeap object contains some of the specified heap, allocate another heap where the specified heap is moved. Otherwise, allocate the specified heap that will not be moved. And return a pointer to the allocated heap.

To release the heap allocated by the SFXClusterHeap::Protect function, use the SFXClusterHeap::Unprotect function.

Example

SFXClusterHeap<SInt16> heap1;
SFXClusterHeap<SInt16> heap2;
VoidConstPtr protect;

heap1.Resize(sizeof(UInt32) * 128);  // set the heap size to 512 bytes
heap2.Resize(sizeof(UInt32) * 128);  // set the heap size to 512 bytes

// save values not to conflict when processing themselves
VoidConstPtr sa(heap2.GetHeap());
UInt32 ss(heap2.GetSize());
UInt32 ds(heap1.GetSize());

TRACE("addr = 0x%08X", heap1.GetHeap());      // addr = 0x06871C84 

// allocate another heap safely
if ((protect = heap1.Protect(sa, ss)) != null) {
    TRACE("addr = 0x%08X", protect);          // addr = 0x06871EB8
    // release the heap allocated by the SFXClusterHeap::Protect function
    heap1.Unprotect(protect, sa);
}

Reference

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

SFXClusterHeap::Resize

Set the heap size.

[ public ]
SFCError Resize(
    UInt32 size   // heap size (in bytes)
);

Return value

Success : SFERR_NO_ERROR
If insufficient memory : SFERR_NO_MEMORY

Description

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

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

Otherwise, heap to exceed the threshold is allocated by the cluster size.

Example

SFXClusterHeap<SInt16> heap;

heap.Resize(sizeof(UInt32) * 128);  // set the heap size to 512 bytes

Reference

SFXClusterHeap::SFXClusterHeap | SFXClusterHeap::SetCluster | SFXClusterHeap::SetThreshold

SFXClusterHeap::SetCluster

Set the cluster size to increase or decrease the heap.

[ public ]
Void SetCluster(
    UInt16 cluster   // 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 = %d", heap.GetCluster());  // cluster = 10

Reference

SFXClusterHeap::GetCluster | SFXClusterHeap::Resize

SFXClusterHeap::SetThreshold

Set the minimum heap size.

[ public ]
Void SetThreshold(
    UInt16 threshold   // minimum heap size (in bytes)
);

Example

SFXClusterHeap<SInt16> heap;

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

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

Reference

SFXClusterHeap::GetThreshold | SFXClusterHeap::Resize

SFXClusterHeap::Unprotect

Release the heap allocated by the SFXClusterHeap::Protect function.

[ public, const ]
Void Unprotect(
    VoidConstPtr protect   // pointer the  function returns
    VoidConstPtr heap      // pointer to the heap that the  function allocates
);

Description

Release the heap allocated by the SFXClusterHeap::Protect function.

Example

SFXClusterHeap<SInt16> heap1;
SFXClusterHeap<SInt16> heap2;
VoidConstPtr protect;

heap1.Resize(sizeof(UInt32) * 128);  // set the heap size to 512 bytes
heap2.Resize(sizeof(UInt32) * 128);  // set the heap size to 512 bytes

// save values not to conflict when processing themselves
VoidConstPtr sa(heap2.GetHeap());
UInt32 ss(heap2.GetSize());
UInt32 ds(heap1.GetSize());

TRACE("addr = 0x%08X", heap1.GetHeap());      // addr = 0x06871C84 

// allocate another heap safely
if ((protect = heap1.Protect(sa, ss)) != null) {
    TRACE("addr = 0x%08X", protect);          // addr = 0x06871EB8
    // release the heap allocated by the SFXClusterHeap::Protect function
    // The value of 2nd argument of Unprotect function must be the same with that of 1st argument of Protect function
    heap1.Unprotect(protect, sa);
}

Reference

SFXClusterHeap::Protect

SFXClusterHeap::operator T *

Convert into the typr of "T *".

[ public, const ]
operator T *(Void);

Return value

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

operator==

Check the relation of "==".

[ public, friend ]
Bool operator==(
    SFXClusterHeap< T > const & left    // SFXClusterHeap object to compare with
    SFXClusterHeap< M > const & right   // SFXClusterHeap object to compare with
);

[ public, friend ]
Bool operator==(
    SFXClusterHeap< T > const & left   // SFXClusterHeap object to compare with
    VoidConstPtr right                 // pointer to the heap to compare with
);

[ public, friend ]
Bool operator==(
    VoidConstPtr left                   // pointer to the heap to compare with
    SFXClusterHeap< T > const & right   // SFXClusterHeap object to compare with
);

Return value

If address of left equals that of right : true
Otherwise : false

Description

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

operator>=

Check the relation of ">=".

[ public, friend ]
Bool operator>=(
    SFXClusterHeap< T > const & left    // SFXClusterHeap object to compare with
    SFXClusterHeap< M > const & right   // SFXClusterHeap object to compare with
);

[ public, friend ]
Bool operator>=(
    SFXClusterHeap< T > const & left   // SFXClusterHeap object to compare with
    VoidConstPtr right                 // pointer to the heap to compare with
);

[ public, friend ]
Bool operator>=(
    VoidConstPtr left                   // pointer to the heap to compare with
    SFXClusterHeap< T > const & right   // SFXClusterHeap object to compare with
);

Return value

If address of left is bigger than or equals that of right : true
Otherwise : false

Description

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

operator>

Check the relation of ">".

[ public, friend ]
Bool operator>(
    SFXClusterHeap< T > const & left    // SFXClusterHeap object to compare with
    SFXClusterHeap< M > const & right   // SFXClusterHeap object to compare with
);

[ public, friend ]
Bool operator>(
    SFXClusterHeap< T > const & left   // SFXClusterHeap object to compare with
    VoidConstPtr right                 // pointer to the heap to compare with
);

[ public, friend ]
Bool operator>(
    VoidConstPtr left                   // pointer to the heap to compare with
    SFXClusterHeap< T > const & right   // SFXClusterHeap object to compare with
);

Return value

If address of left is bigger than that of right : true
Otherwise : false

Description

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

operator<=

Check the relation of "<=".

[ public, friend ]
Bool operator<=(
    SFXClusterHeap< T > const & left    // SFXClusterHeap object to compare with
    SFXClusterHeap< M > const & right   // SFXClusterHeap object to compare with
);

[ public, friend ]
Bool operator<=(
    SFXClusterHeap< T > const & left   // SFXClusterHeap object to compare with
    VoidConstPtr right                 // pointer to the heap to compare with
);

[ public, friend ]
Bool operator<=(
    VoidConstPtr left                   // SFXClusterHeap object to compare with
    SFXClusterHeap< T > const & right   // pointer to the heap to compare with
);

Return value

If address of left is less than or equals that of right : true
Otherwise : false

Description

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

operator<

Check the relation of "<".

[ public, friend ]
Bool operator<(
    SFXClusterHeap< T > const & left    // SFXClusterHeap object to compare with
    SFXClusterHeap< M > const & right   // SFXClusterHeap object to compare with
);

[ public, friend ]
Bool operator<(
    SFXClusterHeap< T > const & left   // SFXClusterHeap object to compare with
    VoidConstPtr right                 // pointer to the heap to compare with
);

[ public, friend ]
Bool operator<(
    VoidConstPtr left                   // pointer to the heap to compare with
    SFXClusterHeap< T > const & right   // SFXClusterHeap object to compare with
);

Return value

If address of left is less than that of right : true
Otherwise : false

Description

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

operator!=

Check the relation of "!=".

[ public, friend ]
Bool operator!=(
    SFXClusterHeap< T > const & left    // SFXClusterHeap object to compare with
    SFXClusterHeap< M > const & right   // SFXClusterHeap object to compare with
);

[ public, friend ]
Bool operator!=(
    SFXClusterHeap< T > const & left   // SFXClusterHeap object to compare with
    VoidConstPtr right                 // pointer to the heap to compare with
);

[ public, friend ]
Bool operator!=(
    VoidConstPtr left                   // pointer to the heap to compare with
    SFXClusterHeap< T > const & right   // SFXClusterHeap object to compare with
);

Return value

If address of left does not equal that of right : true
Otherwise : false

Description

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