Cleanup +requirements

diff -r 43e37759235e -r 51a74ef9ed63 Symbian3/SDK/Source/GUID-E93E577A-0BDF-5472-B79F-DA60841C30CC.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-E93E577A-0BDF-5472-B79F-DA60841C30CC.dita Wed Mar 31 11:11:55 2010 +0100 @@ -0,0 +1,71 @@ + + + + + +Cleanup +requirementsThis document describes the requirements for cleanup after a function +leaves. +

When a function leaves, it transfers control directly to the statement +following the TRAP (or TRAPD) macro under +which it was invoked. This is carried out by setting the stack pointer to +the context of the original TRAP macro, and jumping to the +desired program location. Therefore,

any objects created +as automatic variables, passed by value as arguments, or created as member +variables of other objects so created, will be orphaned: +their destructor will not be called, and any resources they claim except for +storage space on the stack, cannot be recovered.

This key aspect of Symbian platform exceptions has far-reaching implications:

There should be a clear +distinction between objects which can be safely orphaned, and those which +cannot.

This is embodied in the naming convention for types. All types +beginning with T can be safely orphaned, including, for instance, TInt, TPoint, TPtr and many others. Such objects can be freely allocated on the stack.

The +basic requirement for T objects is that all their data is +contained internally. Pointers, handles and references to data owned by the T object +are not allowed (although such references to data owned by other objects is +allowed).

C objects must never be orphaned: they should +never be allocated on the stack.

R objects may contain +handles to external resources, but are generally designed so that the R object +can be copied without copying its resources. Copied R objects +may therefore be allocated on the stack: the stack-allocated copies may safely +be orphaned, provided the resources are safely accessible by some other means.

Objects which cannot +be safely orphaned must, if allocated inside the trap harness, be accessible +somehow so they can be cleaned up.

The cleanup stack is the Symbian platform mechanism for handling +this last problem.

Example

The problem for heap-allocated resources +is shown below. If the call to DoSomethingL() leaves, the CExample object +would be orphaned on the heap: the memory used for it could +not have been recovered until the program terminates.

void doExampleL() + { + // An T-type object: can be declared on the stack + TBuf<10> buf; + + // A C-type object: must be allocated on the heap + // Allocate and leave if can not + CExample* myExample = new (ELeave) CExample; + + // do something that cannot leave: no protection needed + myExample->iInt = 5; + + // PROBLEM: do something that can leave + myExample->DoSomethingL(); + + // delete + delete myExample; + }

+ \ No newline at end of file