Standard C++ Support on the Symbian Platform

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.