Two-phase Construction

1.    Brief description

In Symbian C++ programming, theTwo-phase construction idiom ensures that the objects being constructed andinitialised do not leave before they are stored in thecleanup stack.

2.   Contextand Problem

In programming for Symbian with C++,the pointers to heap-based objects are stored in thecleanup stack. This allows automatic cleaning of the object in case of aleave situation. A newl created object is pushed into thecleanup stack immediately after it is constructedand initialised by a C++ constructor. However, according to the C++conventions, during the time after memory is allocated for the object andbefore the object’s C++ constructor completes, the object cannot be stored inthecleanup stack yet, and therefore, leaving during that time should not beallowed.

3.    Solution, its Consequences andLiabilities

In order to avoid a leavingsituation until an object is pushed into the cleanup stack, leaving of this object’s C++ constructor should beprohibited. This is achieved by implementing a two-phase constructor.

According to the two-phaseconstructor idiom, all initialisation code that might leave, as well as anycalls to the functions that might leave, is located in a separate functionConstructL(), referred to as a second-phase constructor. (For example, if baseclasses as well have ConstructL() methods, they should be called (explicitly)in the second-phase constructor.) This second-phase constructor is called onlyafter the object being initialised is pushed into thecleanup stack.

For frequently used classes, bothcalls to the C++ constructor and to the second-phase constructor are usuallyencapsulated in a static special-purpose NewL() function. When the object is tobe created, the NewL() function is supposed to be called instead of the C++constructor and ConstructorL(). This factory function allocates memory for theobject, pushes it into thecleanup stack, calls the second-phase constructor, and finally pops theobject out of the stack. If it is envisioned that the newly created object willbe used as an automatic variable (i.e. it should be kept in thecleanup stack throughout its lifetime),additional NewLC() function is provided, which is the same as the NewL() withthe exception that it does not pop the object out of the stack. An example of theConstructL(), NewL(), and NewLC() functions is provided in the listing below.

NewL() and NewLC() are the staticmethod and can be called by the class with out creating an object. NewL() andNewLC() are kept into the public access specifier of the class. so that we cancall them directly. While the default constructor (in which the initialisationcode is non-leaving) and the ConstructL() method(in which the initializationcode may leave) are put into the private area of the class and only the methodsin public area (generally NewL() and NewLC()) can make a call to them andaccess them.

 

 

       // Phase #1

        CMyClass::CMyClass()

               {

               }

 

        // Phase #2

        voidCMyClass::ConstructL()

               {

               //Member data initialization.

               }

 

        // Put bothphases together in one function...

        CMyClass *CMyClass::NewL()

               {

               CMyClass* self = new (ELeave) CMyClass();

               CleanupStack::PushL(self);

               self->ConstructL();

               CleanupStack::Pop(self);

               returnself;

               }

 

        CMyClass *CMyClass::NewLC()

               {

               CMyClass* self = new (ELeave) CMyClass();

               CleanupStack::PushL(self);

               self->ConstructL();

               returnself;

               }