diff -r 48780e181b38 -r 578be2adaf3e Symbian3/PDK/Source/GUID-E93E577A-0BDF-5472-B79F-DA60841C30CC.dita --- a/Symbian3/PDK/Source/GUID-E93E577A-0BDF-5472-B79F-DA60841C30CC.dita Tue Jul 20 12:00:49 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-E93E577A-0BDF-5472-B79F-DA60841C30CC.dita Fri Aug 13 16:47:46 2010 +0100 @@ -1,71 +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,

- -

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

- - -

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; - }
+ + + + + +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