Chapter 1

If you're writing a function, and that function calls another one that might leave, then you
should put an L in its name. This will remind you, your colleagues, or anyone else looking at
your code, that this function might leave. Here are a few cases to think about:
� If you're writing a function that calls another, and the other is an L function, then your
function must be an L function too (unless you trap the leave).
� If your function calls new(ELeave), your function must also be an L function.
� If you're implementing a function provided by a framework, then it's important to know
whether that framework function is an L function. If it is, you can allocate resources that
can potentially leave. If not, your code must not leave – or, if it does, you must handle it
privately. For example, CEikAppUi::HandleCommandL() allows you to leave, so
user command handlers can allocate resources and potentially leave.
CCoeControl::Draw() doesn't allow you to leave, so any drawing code you write
must work with preallocated resources and not leave or, if for its own reasons it can't
preallocate resources, it must trap potential leaves and handle them privately.
� If you're specifying a framework function for others to implement, think very carefully
about whether you will allow an implementer to leave. This is an essential aspect of
your function. Don't just code it as an L function to allow the implementer to do what
they want; code L if it's needed, and don't code it if it's not.
The L naming convention gives the same kind of message to the programmer as the
throws clause in Java or standard C++. However, L is not checked by the compiler, so if
you forget to include it in the name, the compiler will not complain. However, if someone else
then uses your function and doesn't realize that it might leave – they may not take
appropriate precautions.
Note
In the C++ Knowledge Base on Symbian's website, you'll find an Lcorrectness
checking script that can be quite useful.
You don't often need to code your own traps, partly because the Symbian OS framework
provides one for you, and partly because (as we'll see shortly) routine cleanup is handled by
other means.
Sometimes, though, you'll need to perform a recovery action, in addition to some nonroutine
cleanup. Or you'll need to code a nonleaving function, such as Draw() that allocates
resources and draws successfully if possible, but otherwise traps any leaves and handles
them internally. In these cases, you must code your own trap.
In a word processor, for example, processing a key press causes many things to happen –
to name but two, there's the allocation of undo buffers, and the expansion of the document
to take a new character. If anything like that goes wrong, you need to undo the operation
completely. You could use code such as
TRAPD(error, HandleKeyL());
if(error)
{
RevertUndoBuffer();
// Any other special cleanup
User::Leave(error);
}
Nested traps