SFXHeap

Class that represents heap.

#include <SFXHeap.h.hpp>

class SFXHeap;

SFMTYPEDEFCLASS(SFXHeap)

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.

Example 473. How to Use the Attach Function

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

Example 474. How to Use the Detach Function

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

Constructor/Destructor
SFXHeap( `Void` ) Constructor of SFXHeap class.

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

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

SFXHeap::SFXHeap

Constructor of SFXHeap class.

[ public, explicit ]
SFXHeap(Void);

SFXHeap::Attach

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

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

Return value

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

Example

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(heap)

･･･

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

Reference

SFXHeap::Detach

SFXHeap::Contains

Check whether the attached SFXHeap 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

SFXHeap<SInt16> heap1;
heap1.Resize(sizeof(SInt16) * 128);  // set the size of heap1 to 256 bytes
SFXHeap<SInt16> 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
  ...
}

SFXHeap::Detach

Delegate the control privilege of SFXHeap 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 SFXHeap object has.

Description

The heap that the SFXHeap object has is never copied.

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

Example

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

SFXHeap::Attach

SFXHeap::EmptyInstance

Get an empty heap.

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

Description

Get an instance that represents an empty heap.

SFXHeap::Free

Release the heap that the SFXHeap object manages.

[ public ]
Void Free(Void);

Example

SFXHeap<SInt16> heap;

...

heap.Free();   // release heap explicitly

SFXHeap::GetHeap

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

[ public ]
VoidPtr GetHeap(Void);

[ public, const ]
VoidConstPtr GetHeap(Void);

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
}

SFXHeap::GetSize

Get the heap size.

[ public, const ]
UInt32 GetSize(Void);

Return value

Return the heap size.

Example

SFXHeap<SInt16> heap;

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

Reference

SFXHeap::Resize

SFXHeap::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 SFXHeap 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 SFXHeap::Protect function, use the SFXHeap::Unprotect function.

Example

SFXHeap<SInt16> heap1;
SFXHeap<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 SFXHeap::Protect function
    heap1.Unprotect(protect, sa);
}

Reference

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

SFXHeap::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

Example

SFXHeap<SInt16> heap;

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

SFXHeap::Unprotect

Release the heap allocated by the SFXHeap::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 SFXHeap::Protect function.

Example

SFXHeap<SInt16> heap1;
SFXHeap<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 SFXHeap::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

SFXHeap::Protect

SFXHeap::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==(
    SFXHeap< T > const & left    // SFXHeap object to compare with
    SFXHeap< M > const & right   // SFXHeap object to compare with
);

[ public, friend ]
Bool operator==(
    SFXHeap< T > const & left   // SFXHeap 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
    SFXHeap< T > const & right   // SFXHeap 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>=(
    SFXHeap< T > const & left    // SFXHeap object to compare with
    SFXHeap< M > const & right   // SFXHeap object to compare with
);

[ public, friend ]
Bool operator>=(
    SFXHeap< T > const & left   // SFXHeap 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
    SFXHeap< T > const & right   // SFXHeap 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>(
    SFXHeap< T > const & left    // SFXHeap object to compare with
    SFXHeap< M > const & right   // SFXHeap object to compare with
);

[ public, friend ]
Bool operator>(
    SFXHeap< T > const & left   // SFXHeap 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
    SFXHeap< T > const & right   // SFXHeap 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<=(
    SFXHeap< T > const & left    // SFXHeap object to compare with
    SFXHeap< M > const & right   // SFXHeap object to compare with
);

[ public, friend ]
Bool operator<=(
    SFXHeap< T > const & left   // SFXHeap 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
    SFXHeap< T > const & right   // SFXHeap object 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<(
    SFXHeap< T > const & left    // SFXHeap object to compare with
    SFXHeap< M > const & right   // SFXHeap object to compare with
);

[ public, friend ]
Bool operator<(
    SFXHeap< T > const & left   // SFXHeap 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
    SFXHeap< T > const & right   // SFXHeap 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!=(
    SFXHeap< T > const & left    // SFXHeap object to compare with
    SFXHeap< M > const & right   // SFXHeap object to compare with
);

[ public, friend ]
Bool operator!=(
    SFXHeap< T > const & left   // SFXHeap 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
    SFXHeap< T > const & right   // SFXHeap 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.