SFDWatcher

Class to operate memory for debugging.

#include <SFDWatcher.h.hpp>

class SFDWatcher;

SFMTYPEDEFCLASS(SFDWatcher)

Description

SFDWatcher class records all the memory operation.

This class does nothing on the mobile phone device.

Member

Public Functions
static `Void`	dumpleak( `Void` ) Dump information on un-released heap.
static `Void`	dumpuse( `Void` ) Dump the current size of total heap and the maximum size of total heap.
static `Void`	free( `VoidPtr` address ) Free the heap.
static `VoidPtr`	malloc( `UInt32` size , `ACharConstPtr` file , `SInt32` line ) Allocate memory from heap.
static `VoidPtr`	realloc( `VoidPtr` address , `UInt32` size , `ACharConstPtr` file , `SInt32` line ) Re-allocate memory from heap
static `Void`	resetlimit( `Void` ) Reset the upper limit of total heap size.
static `Void`	resetmaximum( `Void` ) Set the maximum size of total heap to the current size of total heap.
static `Void`	setlimit( `UInt32` size ) Set the upper limit of total heap size that can be allocated.
static `Void`	setrandomize( `Bool` active ) Enable or disable to write random data to the allocated memory.
static `Void`	setwarning( `Bool` active ) Enable or disable to warn about an invalid argument.

SFDWatcher::dumpleak

Dump information on un-released heap.

[ public, static ]
Void dumpleak(Void);

Information

The SFDWatcher::dumpleak function is used to display information on un-released heap in the output window of BREW simulator.

Reference

SFDWatcher::malloc | SFDWatcher::realloc | SFDWatcher::free

SFDWatcher::dumpuse

Dump the current size of total heap and the maximum size of total heap.

[ public, static ]
Void dumpuse(Void);

Description

The SFDWatcher::dumpuse function is used to display the current size of total heap and the maximum size of total heap in the output window of BREW simulator.

Reference

SFDWatcher::malloc | SFDWatcher::realloc | SFDWatcher::free | SFDWatcher::resetmaximum

SFDWatcher::free

Free the heap.

[ public, static ]
Void free(
    VoidPtr address   // pointer to the heap to be freed
);

Description

The SFDWatcher::free function is used to free the heap specified with the "address" argument.

When the "address" argument is set to "null" and warning option about invalid arguments is set effective by the SFDWatcher::setwarning funtion, "null" is displayed as the value of "address" argument in the output window of BREW simulator.

Reference

SFDWatcher::setwarning | Section 27.2.3, “MemoryFree Macro” | Section 27.2.4, “The new/delete Operators”

SFDWatcher::malloc

Allocate memory from heap.

[ public, static ]
VoidPtr malloc(
    UInt32 size          // heap size to be allocated ( bytes )
    ACharConstPtr file   // source code name of caller
    SInt32 line          // line number of caller
);

Return value

Return a pointer to the allocated heap.

Description

After confirmation whether heap has enough free memory space or not, memory is allocated by the SFXHelper::malloc function and the file name and line number of caller are recorded.

The file argument ( source file name of caller ) and line argument ( line number of caller ) are specified optionally when debugging. The file argument can be set to the "null" pointer.

If heap allocation is failed, the "null" pointer is returned. When heap does not have enough free memory space, the "null" pointer will be displayed in the output window of BREW simulator.

When the size argument is set to 0 and warning option about invalid arguments is set effective by the SFDWatcher::setwarning function, 0 ( value of size ) is displayed in the output window of BREW simulator.

Example

This is an example that "the 100th line of Test.cpp resource file" is recorded and heap is allocated.

// resource file name is HogeHoge.cpp
...
// in fact this is the 4096th line
UInt32Ptr buf = reinterpret_cast<UInt32Ptr>(SFDWatcher::malloc(sizeof(UInt32) * 1000, "Test.cpp", 100));
...

When recording the source file name and line number and allocating heap, the MemoryAllocate macro or new operator is more useful.

Reference

SFDWatcher::setwarning | SFXHelper::malloc | MemoryAllocate | new

SFDWatcher::realloc

Re-allocate memory from heap

[ public, static ]
VoidPtr realloc(
    VoidPtr address      // pointer to the space allocated before or an empty pointer
    UInt32 size          // the new size of heap to be allocated in byte
    ACharConstPtr file   // the source code name of the caller
    SInt32 line          // the line number of the caller
);

Return values

The SFDWatcher::realloc function returns the pointer to re-allocated heap.

Description

After confirmation whether heap has enough free memory space or not, memory is re-allocated by the SFXHelper::realloc function and the file name and line number of caller are recorded.

When re-allocating heap, the previous content is retained if memory size to be newly re-allocated is bigger than before.

While memory size is smaller than before, only the previous content of newly re-allocated heap is retained.

When the address argument is set to the null pointer, heap is newly allocated. This is the same as the SFDWatcher::malloc function.

The file argument ( source file name of caller ) and line argument ( line number of caller ) are specified optionally when debugging. The file argument can be set to the "null" pointer.

If heap allocation is failed, the "null" pointer is returned. When heap does not have enough free memory space, the "null" pointer will be displayed in the output window of BREW simulator.

When the address argument is set to other than the null pointer and the size argument is set to 0, its heap is released. The result is the same as the SFDWatcher::free function.

Reference

SFDWatcher::free | SFXHelper::realloc | SFDWatcher::malloc

SFDWatcher::resetlimit

Reset the upper limit of total heap size.

[ public, static ]
Void resetlimit(Void);

Description

The SFDWatcher::resetlimit function resets the upper limit of total heap size set by the SFDWatcher::setlimit function.

Reference

SFDWatcher::setlimit | SFDWatcher::malloc | SFDWatcher::realloc

SFDWatcher::resetmaximum

Set the maximum size of total heap to the current size of total heap.

[ public, static ]
Void resetmaximum(Void);

Description

Though the size of total heap changes by using the SFDWatcher::malloc, SFDWatcher::realloc, or SFDWatcher::free function, SophiaFramework has its maximum size internally.

The SFDWatcher::resetmaximum function resets the former maximum size of total heap, and sets the current size of total heap to the maximum size of total heap.

Reference

SFDWatcher::malloc | SFDWatcher::realloc | SFDWatcher::free

SFDWatcher::setlimit

Set the upper limit of total heap size that can be allocated.

[ public, static ]
Void setlimit(
    UInt32 size   // limit of total heap size in byte
);

Description

The SFDWatcher::setlimit function sets the upper limit of total heap size that can be allocated.

The free heap size that can be confirmed inside the SFDWatcher::malloc function or SFDWatcher::realloc function is the value gotten by subtracting the total allocated heap size from this upper limit.

There is no upper limit for total heap size until the SFDWatcher::setlimit function is called. (Actually, the maximum heap size of BREW simulator is the upper limit.)

Reference

SFDWatcher::resetlimit | SFDWatcher::malloc | SFDWatcher::realloc

SFDWatcher::setrandomize

Enable or disable to write random data to the allocated memory.

[ public, static ]
Void setrandomize(
    Bool active   // true = enabled, false = disabled
);

Description

The SFDWatcher::setrandomize function is used to enable or disable to write random data to the allocated memory.

By using this function, it is easier to detect the bugs caused by forgetting memory initialization when debugging with the BREW simulator.

In case this function is set to "off", allocated memory is padded with "null". By default this function is set to "on".

Reference

SFDWatcher::malloc | SFDWatcher::realloc | SFDWatcher::free

SFDWatcher::setwarning

Enable or disable to warn about an invalid argument.

[ public, static ]
Void setwarning(
    Bool active   // true = enabled, false = disabled
);

Description

The SFDWatcher::setwarning function is used to enable or disable to display the warning message in the output window of BREW simulator when an invalid argument is specified with the SFDWatcher::malloc, SFDWatcher::realloc, or SFDWatcher::free function.

Reference

SFDWatcher::malloc | SFDWatcher::realloc | SFDWatcher::free