Standard -C++ Support on the Symbian Platform

Standard -C++ Support on the Symbian Platform -

This topic describes the Standard C++ runtime features supported on Symbian^3.

Global operator new
new_handler
Global object destruction
STL

Global operator -new

In Standard C++, when dynamic memory allocation (using operator - new) fails and if a handler is not set to handle it, the -code throws an exception (std::bad_alloc). But in Symbian -C++, when dynamic memory allocation fails, the code returns NULL.

When -you write Standard C++ code on Symbian C++ ensure that you either use Symbian -C++ semantics of operator new or Standard C++ semantics of operator new in -your code. You can use the global operator new as per the -Standard C++ specification on the Symbian platform by either:

Building your application -or library using the STD target type.
Using the MMP keyword, STDCPP.

Note: For detailed information about problems that can occur -while using the global operator new, see Use of operator new.

Warning: The Symbian build system -does not permit you to mix the Standard C++ operator new and -the Symbian C++ operator new.

Example

The -following example code illustrates how to use the global operator -new when you write Standard C++ code on the Symbian platform and -your target type is a non-STD target type, for example, exe.

You -must add the MMP keyword, STDCPP in the .mmp file -as shown in the following code:

//operator_new_example.mmp -Target operator_new_example.exe -Targettype exe -//The STDCPP keyword specifies Standard C++ -STDCPP -Source operator_new.cpp -Systeminclude /epoc32/include/stdapis/stlportv5 -Systeminclude /epoc32/include/stdapis -Library libstdcppv5.lib libc.lib -Capability all -tcb //operator_new.cpp -#include <new> -int main() - { - try - { - int *ptr = new int(0); - //do something - } - catch(std::bad_alloc) - { - return 1; - } - delete ptr; - return 0; - }

new_handler

The new_handler() function -of Standard C++ is fully supported on the Symbian platform (the global operator -new restrictions are applicable). You can use the new_handler function -to handle an out of memory scenario caused by the global operator -new when dynamic memory allocation fails.

The following code -illustrates how to set and invoke a new_handler:

#include <new> -int one_huge_chunk = 0xa000; -int *last_huge_chunk=NULL; -void foo() - { - /* - * This is the new_handler and it frees the last successful allocation so - * that the subsequent call to operator new has some free memory. - */ - delete [] last_huge_chunk; - } -void bar() - { - last_huge_chunk = new int[one_huge_chunk]; - } -int main() - { - std::new_handler h_new; - try - { - while(1) - { - // Keep allocating until we reach OOM (out of memory) condition. At OOM - // the default new handler throws std::bad_alloc - bar(); - } - } - catch(std::bad_alloc ba) - { - /* - * Once the handler is set, failure of 'new' will call the handler to - * get some free memory... - */ - h_new = (std::new_handler)&foo; - try - { - /* - * Try once more to see if our handler actually freed up some memory - */ - bar(); - } - catch(...) - { - } - return 0; - } - /*Failed to throw std::bad_alloc*/ - return 1; - }

Important Note: The targettype of -this executable must either be STDEXE /STDDLL or -its .mmp file must use the STDCPP keyword.

Global object -destructors

Global objects are supported both in a statically or -dynamically loaded Standard C++ DLL. Their constructors are invoked when the -DLL is loaded and their destructors are invoked when the reference count of -the DLL falls to zero.

Example

The following example -illustrates the construction and destruction of a global object:

// glob_data.cpp -#include <iostream> -// class definition -class AClass - { - AClass() - { - std::cout << “ctor()” << std::endl; // inline constructor - } - ~AClass() - { - std::cout << “dtor()” <<std::endl; // inline destructor - } - }; -AClass GlobData; // global instance of AClass -int main() - { - std::cout << “main()” << std::endl; - }

The output of this example must be:

ctor -main -dtor

STL

Here -are some key facts about STL support on the Symbian platform:

The Standard C++ implementation -on the Symbian platform is based on STLPort version 5.1.4.
The Standard C++ header -files are available in the ${EPOCROOT}/epoc32/include/stdapis/stlportv5 directory.
The Standard C++ library -name that you must use is libstdcppv5.lib. The value -5 (in the library name) being based on the STL Port version number, which -is 5.

-Copyright -Acknowledgments for Standard C++ (STLport) -Standard -C++ Library Overview - Developing -Applications or Libraries Using Standard C++ -Building -a Standard C++ Application or Library -Possible -Problems -Troubleshooting - -Known Issues - + + + + + +Standard +C++ Support on the Symbian Platform +

This topic describes the Standard C++ runtime features supported on Symbian^3.

Global operator new
new_handler
Global object destruction
STL

Global operator +new

In Standard C++, when dynamic memory allocation (using operator + new) fails and if a handler is not set to handle it, the +code throws an exception (std::bad_alloc). But in Symbian +C++, when dynamic memory allocation fails, the code returns NULL.

When +you write Standard C++ code on Symbian C++ ensure that you either use Symbian +C++ semantics of operator new or Standard C++ semantics of operator new in +your code. You can use the global operator new as per the +Standard C++ specification on the Symbian platform by either:

Building your application +or library using the STD target type.
Using the MMP keyword, STDCPP.

Note: For detailed information about problems that can occur +while using the global operator new, see Use of operator new.

Warning: The Symbian build system +does not permit you to mix the Standard C++ operator new and +the Symbian C++ operator new.

Example

The +following example code illustrates how to use the global operator +new when you write Standard C++ code on the Symbian platform and +your target type is a non-STD target type, for example, exe.

You +must add the MMP keyword, STDCPP in the .mmp file +as shown in the following code:

//operator_new_example.mmp +Target operator_new_example.exe +Targettype exe +//The STDCPP keyword specifies Standard C++ +STDCPP +Source operator_new.cpp +Systeminclude /epoc32/include/stdapis/stlportv5 +Systeminclude /epoc32/include/stdapis +Library libstdcppv5.lib libc.lib +Capability all -tcb //operator_new.cpp +#include <new> +int main() + { + try + { + int *ptr = new int(0); + //do something + } + catch(std::bad_alloc) + { + return 1; + } + delete ptr; + return 0; + }

new_handler

The new_handler() function +of Standard C++ is fully supported on the Symbian platform (the global operator +new restrictions are applicable). You can use the new_handler function +to handle an out of memory scenario caused by the global operator +new when dynamic memory allocation fails.

The following code +illustrates how to set and invoke a new_handler:

#include <new> +int one_huge_chunk = 0xa000; +int *last_huge_chunk=NULL; +void foo() + { + /* + * This is the new_handler and it frees the last successful allocation so + * that the subsequent call to operator new has some free memory. + */ + delete [] last_huge_chunk; + } +void bar() + { + last_huge_chunk = new int[one_huge_chunk]; + } +int main() + { + std::new_handler h_new; + try + { + while(1) + { + // Keep allocating until we reach OOM (out of memory) condition. At OOM + // the default new handler throws std::bad_alloc + bar(); + } + } + catch(std::bad_alloc ba) + { + /* + * Once the handler is set, failure of 'new' will call the handler to + * get some free memory... + */ + h_new = (std::new_handler)&foo; + try + { + /* + * Try once more to see if our handler actually freed up some memory + */ + bar(); + } + catch(...) + { + } + return 0; + } + /*Failed to throw std::bad_alloc*/ + return 1; + }

Important Note: The targettype of +this executable must either be STDEXE /STDDLL or +its .mmp file must use the STDCPP keyword.

Global object +destructors

Global objects are supported both in a statically or +dynamically loaded Standard C++ DLL. Their constructors are invoked when the +DLL is loaded and their destructors are invoked when the reference count of +the DLL falls to zero.

Example

The following example +illustrates the construction and destruction of a global object:

// glob_data.cpp +#include <iostream> +// class definition +class AClass + { + AClass() + { + std::cout << “ctor()” << std::endl; // inline constructor + } + ~AClass() + { + std::cout << “dtor()” <<std::endl; // inline destructor + } + }; +AClass GlobData; // global instance of AClass +int main() + { + std::cout << “main()” << std::endl; + }

The output of this example must be:

ctor +main +dtor

STL

Here +are some key facts about STL support on the Symbian platform:

The Standard C++ implementation +on the Symbian platform is based on STLPort version 5.1.4.
The Standard C++ header +files are available in the ${EPOCROOT}/epoc32/include/stdapis/stlportv5 directory.
The Standard C++ library +name that you must use is libstdcppv5.lib. The value +5 (in the library name) being based on the STL Port version number, which +is 5.

+Copyright +Acknowledgments for Standard C++ (STLport) +Standard +C++ Library Overview + Developing +Applications or Libraries Using Standard C++ +Building +a Standard C++ Application or Library +Possible +Problems +Troubleshooting + +Known Issues +

\ No newline at end of file