This document describes the need for two-phase construction and how to use second phase constructors.
When the construction of an object cannot leave (except for out-of-memory for the allocation of the object itself), then it is appropriate to use the conventional C++ constructor, which is automatically invoked by new.
When the construction of an object may leave, then the object must be pushed to the clean-up stack, or a pointer to the object must be stored in an object that would be cleaned up if a leave occurred, before any part of the construction function is invoked that may leave. To allow this to happen, construction steps that can leave, are performed not in the C++ constructor, but in another initialization functions, referred to as a second phase constructor.
Thus, the general sequence for two-phase construction is:
allocate memory for the object (and leave if out of memory) using new
optionally define a C++ constructor to perform any construction that cannot leave
push a pointer to the object, or store a pointer to it in a class with cleanup support
use the second phase constructor to perform any part of the construction that might leave
Note that:
The whole sequence is usually encapsulated in static member functions called NewL(), and NewLC() (which additionally leaves the created object on the clean-up stack).
Abstract classes are not intended to be instantiated, and so have no NewLC() or NewL(), only a second phase constructor.
Step 2 is optional, because all such construction can be performed by the second phase constructor. The C++ constructor is only necessary when the class is immediately derived from a base class whose default C++ constructor cannot be used. In this case, the derived class must call the base class’s constructor with appropriate parameters.
It is conventional for the second phase constructor to be called ConstructL().