/**

@mainpage 

@par Overview 

@par

This document describes new core APIs for semi-automatic resource

management designed to begin to increase the baseline usability of

Symbian OS for developers. We would welcome feedback, improvement

suggestions, and defect reports. Note that there is a Q&A section at

the bottom of this page that explains some of the background rationale

behind the design choices we have made to get to this point.

Please send any questions or review feedback you have to: core.idioms@symbian.com

The new APIs include the following:

- A new type category: the L-class

  - Allows leaving constructors and can rely on automatic destructor execution for

    cleanup (explained in more detail below)

- New general purpose, self-managing string classes that can be used much 

  like T-classes 

  - LString16 

    - For manipulating strings of 16 bit characters

    - Usually used via the ::LString typedef

  - LString8 

    - For manipulating strings of 8 bit characters

  - ::LData

    - Type alias for LString8 allowing the intent to use it as a raw (non-character) data buffer to be expressed

  - The LString classes are based on the descriptor APIs and are fully interoperable with descriptors

  - The LString classes can grow on demand and do not always need to be

    initialized with a fixed reserve maximum length

- New "smart pointer" style utility classes for managing resources referenced from local variables, 

  which may be used instead of the existing cleanup stack API

  - LCleanedupPtr

    - Alternative to PushL(CBase*)/Pop()/PopAndDestroy() code sequences

  - LCleanedupHandle

    - Alternative to CleanupClosePushL()/Pop()/PopAndDestroy() code sequences

  - See also the more rarely used LCleanedupRef, LCleanedupArray, and LCleanedupGuard

- New "smart pointer" style utility classes for managing resources referenced from data members, 

  which reduce the need for manually-written destructors 

  - LManagedPtr

    - Alternative to calling delete manually in a destructor for the managed data member

  - LManagedHandle

    - Alternative to calling Close() manually in a destructor for the managed data member

  - See also the more rarely used LManagedRef, LManagedArray, and LManagedGuard

- Enablers for the (optional, typically private) use of single-phase construction

  - #CONSTRUCTORS_MAY_LEAVE 

    - A class declaration flagging that the class's constructors may leave

  - Normally used in combination with the LManagedXxx classes to ensure reliable cleanup in case of a constructor leaving

  - Normally hidden behind a conventional Symbian NewL() abstraction

- New utilities for making correct, error checking code easier to read

  - New #OR_LEAVE postfix macro

    - Alternative to wrapping User::LeaveIfError() around an expression

The motivation for the new APIs is to make it easier to write correct,

less brittle code in the first instance, but perhaps more so to make

the resulting code easier to read and easier to modify safely later.

Some guiding principles:

- Resource management should be handled either fully automatically or declaratively 

  at point of definition as far as possible

  - Helps to eliminate mismatches between code that pushes and code that pops

  - Helps to eliminate mismatches between code that constructs and code that destructs

  - Removes the need to duplicate cleanup code (or modify your code's structure) to correctly handle functions with multiple return points 

  - Makes changing code safer and easier by reducing dependencies between different areas of the code

- It should be easier and lighter weight to write and maintain leave-safe code

  - So that more people are prepared to make the investment to do it right

- The primary function of code should not be swamped by auxiliary error checking and resource management 

  - The key logic should be front and centre, and read as straightforwardly as possible

- It should be easier to write fully general code

  - Unsafe and/or overly conservative maximum size limitations should not be 

    encouraged by making that style of code easier to write

- Terminology should be as conventional as possible

  - We call a string a string

To help illustrate the new APIs, here is a sampling of idiomatic code

implemented first in terms of the current Symbian APIs, and alongside

in terms of the new APIs.

<table width="100%">

<tr valign="top">

<td>Current APIs</td><td>New APIs</td>

</tr>

<tr valign="top">

<td>

@code

{

TBuf<KMaxQuery> query; // fixed worst-case max

query.Format(KQueryFormat, param);

ExecuteQueryL(query);

}

@endcode

</td>

<td>

@code

{

LString query; // can grow its heap buffer on demand

query.FormatL(KQueryFormat, param);

ExecuteQueryL(query);

} // query buffer released on normal scope exit or leave

@endcode

</td>

</tr>

<tr valign="top">

<td>

@code

{

HBufC* queryc = HBufC::NewLC(KTooBigForStackMaxQuery);

TPtr query(queryc->Des());

BuildQueryL(query);

ExecuteQueryL(query);

CleanupStack::PopAndDestroy();

}

@endcode

</td>

<td>

@code

{

LString query;

BuildQueryL(query);

ExecuteQueryL(query);

}

@endcode

</td>

</tr>

<tr valign="top">

<td>

@code

{

RBuf query;

query.CleanupClosePushL();

query.CreateL(TooBigForStackMaxQuery);

BuildQueryL(query);

ExecuteQueryL(query);

CleanupStack::PopAndDestroy();

}

@endcode

</td>

<td>

@code

{

LString query;

BuildQueryL(query);

ExecuteQueryL(query);

}

@endcode

</td>

</tr>

<tr valign="top">

<td>

@code

{

CQuery* query = CQuery::NewL();

CleanupStack::PushL(query);

query->BuildQueryL();

query->ExecuteQueryL();

CleanupStack::PopAndDestroy();

}

@endcode

</td>

<td>

@code

{

LCleanedupPtr<CQuery> query(CQuery::NewL()); 

query->BuildQueryL();

query->ExecuteQueryL();

} // query deleted on normal scope exit or leave

@endcode

</td>

</tr>

<tr valign="top">

<td>

@code

{

CQuery* query = CQuery::NewL();

CleanupStack::PushL(query);

query->BuildQueryL();

CleanupStack::Pop();

return query;

}

@endcode

</td>

<td>

@code

{

LCleanedupPtr<CQuery> query(CQuery::NewL()); 

query->BuildQueryL();

return query.Unmanage(); 

// query was protected until Unmanage() was called

}

@endcode

</td>

</tr>

<tr valign="top">

<td>

@code

{

RQuery query;

CleanupClosePushL(query);

query.BuildQueryL();

query.ExecuteQueryL();

CleanupStack::PopAndDestroy();

}

@endcode

</td>

<td>

@code

{

LCleanedupHandle<RQuery> query;

query->BuildQueryL();

query->ExecuteQueryL();

} // query is closed on normal scope exit or leave

@endcode

</td>

</tr>

</table>

@par Concepts

These APIs introduce a new category of Symbian type: the

L-class. L-classes have characteristics close to standard C++ value

and handle classes, including the following:

- Constructors, operators, and implicit operations may leave

- They are self-managing and do not require auxiliary memory management logic

L-classes may be used like T-classes except that they can own

resources, they typically rely on guaranteed execution of their

destructors, and they cannot necessarily be naively bitwise

copied. Any code that manipulates L-class instances must be

leave-safe. The only exception to this rule is if the particular

operations being used are explicitly documented not to leave (e.g. the

default LString constructor and all the LManagedXXX constructors).

The L prefix denotes that these classes may be Liberal when it comes

to Leaving, while being Leave-safe themselves. 

The implementation of many L classes relies on the leave=throw mapping

current in Symbian OS since v9.1 because this guarantees destructor

execution for objects allocated on the stack.

@par Notes on Usage

For ease of experimentation during review, all the new APIs are

packaged for use as a statically-linked bundle:

- #include <euserhl.h> in your code

- STATICLIBRARY euserhl.lib in your mmp

Some important dos and don'ts (most of which leavescan will reliably flag):

- The LCleanedupXXX classes are for managing locals only, and may not be used to manage data members. This is because the LCleanedupXXX classes are implemented in terms of the legacy cleanup stack.

- The LCleanedupXXX classes must not be used in the same function as the legacy cleanup stack APIs. They can interact unintuitively and this is best avoided. It is all or nothing at function granularity.

- Use L-suffix method variants with LCleanedupXXX, never LC-suffix variants that manipulate the cleanup stack. This is for the same reason as the previous point. 

- The LManagedXXX classes should only be used for data members. If they are used for locals, they can interact unintuitively with cleanup stack based cleanup (from other functions on the call stack) with respect to cleanup ordering.

- Whenever you write code that manipulates LString or other L-prefix classes, always conservatively leave-safe your code. This is now easier with the LCleanedupXXX utilities.

On the resource management utility classes:

- A managed object's member functions may be called directly on the managing container, but -> notation must be used to access them

- Implicit coercions from managing containers to managed types are not defined; instead the dereference operator * must be used e.g. to obtain a reference suitable for passing as a parameter to another function 

- Pop()-like semantics (as opposed to PopAndDestroy()) is achieved by calling Unmanage() on the managing container before it goes out of scope; Unmanage() returns the managed object which can then be returned from your function, or passed to a different function which takes over ownership. Unlike Pop(), however, Unmanage() simply sets a flag to disable cleanup and may be called at any time without worrying about stack discipline

- It is still typically necessary to declare, define, and export a destructor, even if its implementation (currently) contains no hand-written code

  - The destructor must be available wherever delete may be called on an instance of the class

  - The compiler will automatically generate destruction logic behind the scenes for LString and LManagedXxx data members, even if you don't write any code yourself

  - The destructor may of course change over time anyway

On the LString classes:

- Existing library functions that accept a modifiable TDes cannot take advantage of LString's on-demand growth behaviour; the necessary capacity must first be explicitly reserved in the LString before calling such functions (this can be done either with a constructor parameter or by calling SetMaxLengthL())

- Any descriptor method that could panic due to lack of capacity is replaced with a leaving variant that grows the heap e.g. instead of Append(), LString defines AppendL(). The non-leaving TDes versions are hidden to avoid accidental use, although they can still be accessed via a TDes typed (as opposed to LString typed) ref or pointer

- Programmers new to Symbian OS could first be introduced to descriptors and string handling via just const TDesC& (for input parameter contracts), TDes (for output parameter contracts), and LString for implementation. LStrings can be initialized by value from any descriptor return type, and by automatically taking ownership in the HBufC* return case.

On single-phase construction:

- This option is enabled by LString and the LManagedXxx classes

  - However you implement construction behind the scenes, NewL is an important abstraction

  - Think hard before using single-phase construction in a framework class designed for derivation in client code

- LString and the LManagedXxx classes may be used safely in conventional Symbian two-phase construction as well as standard C++ style single-phase construction

  - LManagedXxx construction never leaves, and is safe to perform at any stage

  - Default construction of an empty LString never leaves, but other initializations must be deferred to ConstructL

- An understanding of standard C++ construction semantics is required before attempting to use single-phase construction

  - If a constructor throws mid-way through, its matching destructor is not invoked to clean up

  - Instead all data members fully-constructed to the point of the leave are automatically destructed

  - Therefore, in effect, all class cleanup must typically be achieved via data member destruction

  - The presence of a non-empty destructor is a warning sign if you are using single-phase construction

An annotated example using the new APIs follows (the

euserhl_walkthrough example goes into much more detail than we do

here).

@code

#include <e32std.h>

#include <f32file.h>

#include <euserhl.h> // Includes all the new APIs

class CFinder : public CBase

	{

public:

	// We have opted to use single-phase construction here, and some of 

	// our constructor's initialization actions may leave. In order to 

	// guarantee full cleanup in all cases, we have to declare this fact.

	CONSTRUCTORS_MAY_LEAVE

	static CFinder* NewL(const TDesC& aPattern);

	~CFinder();

	void GetNextMatchL(TDes& aMatch);

protected:

	CFinder(const TDesC& aPattern);

protected:

	LString iPattern;

	LManagedHandle<RFs> iFs; // We always use LManagedXxx for data members

	// ...

	};

CFinder* CFinder::NewL(const TDesC& aPattern)

	{

	return new(ELeave) CFinder(aPattern);

	}

CFinder::CFinder(const TDesC& aPattern) 

	// This initializer may leave, since the LString will allocate a

	// heap buffer large enough to contain a copy of aPattern's data

	: iPattern(aPattern) 

	{

	// If connection fails and we leave here, iPattern's destructor

	// will be called automatically, and the string's resources will

	// be released

	iFs->Connect() OR_LEAVE;

	}

CFinder::~CFinder()

	{

	// Automatic destruction of each of the data members does all of the

	// work for us: iPattern's heap buffer if freed, while Close() is

	// called on the managed RFs in iFs.

	// Even though this destructor is textually empty, it should

	// still be exported; the compiler is generating destruction logic

	// for us in this case

	}

void CFinder::GetNextMatchL(TDes& aMatch)

	{

	// ...

	LString possible;

	// ...

	LCleanedupHandle<RFile> file; // We always use CleanedupXXX for locals

	TInt status = file->Open(*iFs, possible, EFileRead); // Note use of -> and * here

	// ...

	aMatch = possible;

	// ...

	}

@endcode

For comparison, the original code in terms of existing APIs:

@code

#include <e32std.h>

#include <f32file.h>

class CFinder : public CBase

	{

public:

	static CFinder* NewL(const TDesC& aPattern);

	~CFinder();

	void GetNextMatchL(TDes& aMatch);

protected:

	CFinder();

	void ConstructL(const TDesC& aPattern);

protected:

	HBufC* iPattern;

	RFs iFs;

	// ...

	};

CFinder* CFinder::NewL(const TDesC& aPattern)

	{

	CFinder* self = new(ELeave) CFinder;

	CleanupStack::PushL(self);

	self->ConstructL(aPattern);

	CleanupStack::Pop();

	return self;

	}

CFinder::CFinder() 

	{

	}

void CFinder::ConstructL(const TDesC& aPattern)

	{

	iPattern = aPattern.AllocL();

	User::LeaveIfError(iFs.Connect());

	}

CFinder::~CFinder()

	{

	iFs.Close();

	delete iPattern;

	}

void CFinder::GetNextMatchL(TDes& aMatch)

	{

	// ...

	RFile file;

	CleanupClosePushL(file);

	TInt status = file.Open(iFs, possible, EFileRead);

	// ...

	aMatch = possible;

	// ...

	CleanupStack::PopAndDestroy();

	}

@endcode

@par Q&A

\b General.1 <em>Why start at the bottom? Shouldn't improving the usability of Symbian

OS and its APIs be a top-down initiative?</em>

There is a product-wide usability initiative within Symbian which aims

to address all of APIs, documentation, and tools. On the API side,

there are tracks that try to improve the design process for good API

usability going forward, and tracks like this one that try to improve

the usability of existing functionality. This is just the first

deliverable of the latter effort, but other work is ongoing.

\b General.2 <em>Will Core Idioms changes like these be backed up by tools support?</em>

Yes, support for tools like Leavescan and Coverity, as well as more

basic debugger presentation support for the new descriptor types and

resource management classes, is being planned into the roll-out

project.

\b General.3 <em>Will Core Idioms changes like these be backed up by matching

documentation, examples, and coding standards updates?</em>

Yes, we understand this to be essential and this is our goal.

\b General.4 <em>Symbian will support STL as part of Open Environment, and

Symbian's STL implementation includes std::string and

std::auto_ptr. Why not just use them?</em>

We investigated this option to the point of creating a native Symbian

C++ interoperable STL subset for experimentation. This was ultimately

rejected for the following reasons:

- Hybrid-style code (with mixed Symbian-style and standard-style naming) is

  harder to read and to work with than code in a single consistent style

- Beyond basic naming conventions, supporting two very different APIs 

  for manipulating strings (the descriptor methods alongside the 

  std::string methods) similarly does not help usability

- Interoperability between std::string and TDesC/TDes accepting APIs 

  implemented via implicit coercion is more limited than the direct placement

  of new string classes within the existing descriptor hierarchy can

  achieve

- Because we need a number of Symbian-specific resource management 

  utilities (cleanup-stack aware, R-class aware, and so on), auto_ptr

  on its own does not provide much leverage

- It would require maintaining two subtly variant STL builds: the Open

  Environment version with standard C++ new and exception 

  behaviour, and a Symbian C++ version with new(ELeave) and leaving

  behaviour

Instead we opted to give Symbian C++ a "programming philosophy

upgrade"; more aligned with standard C++ but still in the style of

Symbian C++ and its existing APIs. The result is something that can be

more easily and more incrementally adopted by existing Symbian C++

projects and teams. Note that this decision to focus first on building

out the usability of native Symbian C++ does not preclude the

possibility of an official hybridized Symbian embedding of STL being

developed at a later date

Finally, we could have used Symbian-ized names like XAutoPtrYyy as the

basis for the resource management utility classes. However, this was

deliberately avoided because the semantics of our classes are

different from auto_ptr e.g. they can't support copy construction or

transfer of ownership through parameter passing and return, and

different variants are required for use with locals than with data

members. We did not want to give the Symbian classes names that could

result in developers making natural but incorrect assumptions about

their behaviour based experience with similarly-named classes

elsewhere.

\b General.5 <em>These new template classes seem more conceptually

complex than what they're replacing. How can this improve

usability?</em>

Template classes can be complex to implement, but they're not

particularly difficult to understand or use in the way they're

employed here. Symbian programmers are already familiar with the

basics from RArray<T> and RPointerArray<T>. And to anyone coming from

standard C++ and STL it's second nature, as in fact is this general

style of parameterised declaration to desktop Java and C# programmers

used to generics.

In the end, it's just a concise, declarative annotation that takes

leaky code and helps turn it into robust code.

Leaky:

@code

{

CFoo* foo = CFoo::NewL();