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().