Symbian OS Class Conventions
By convention, there are several class types on Symbian OS, each of which has different characteristics, such as where objects may be created (on the heap, on the stack, or on either) and how those objects should later be cleaned up. The classes are named with a prefix according to type, and this convention makes the creation, use and destruction of objects more straightforward. When writing code, the required behavior of a class should be matched to the Symbian OS class characteristics. Later, a user of an unfamiliar class can be confident in how to instantiate an object, use it and then destroy it without leaking memory.
3.2.1 T Classes
Class names prefixed with T are used for classes that behave like the fundamental built-in data types (it is for this reason that they are prefixed with the same letter as the typedefs described above-the 'T' is for 'Type').
Just like the built-in types, T classes do not have an explicit destructor. In consequence, T classes must not contain any member data which itself has a destructor. T classes contain all their data internally and have no pointers, references or handles to data, unless that data is owned by another object responsible for its cleanup.
T-class objects are usually stack-based but they can also be created on the heap - indeed, some T classes should only ever be heap-based because the resulting object would otherwise occupy too much stack space. A good rule of thumb is that any object larger than 512 bytes should always be heap-based rather than created on the stack, since stack space is limited for applications running on Symbian OS. One way to prevent the object from being instantiated on the stack is to rename the class, and make it a C class, since C-class objects are always created on the heap, as the next subsection describes.
Tip: T classes can be created on the heap as well as on the stack.
3.2.2 C Classes
C-class objects must always be created on the heap. Unlike T classes, C classes may contain and own pointers.
For Symbian OS memory management to work correctly, every C class must ultimately derive from class CBase (defined in the Symbian OS header file e32base.h). This class has three characteristics, which are inherited by every C class:
• Safe destruction. CBase has a virtual destructor, so a CBase-derived object is destroyed properly by deletion through a base-class pointer.
• Zero initialization. CBase overloads operator new to zero-initialize an object when it is first allocated on the heap. This means that all member data in a CBase-derived object will be zero-filled when it is first created, so this does not need to be done explicitly in the constructor.
• CBase also declares a private copy constructor and assignment operator. Their declaration prevents calling code from accidentally performing invalid copy operations on C classes.
On instantiation, the member data contained within a C class typically needs to perform operations that may fail. A good example is instantiation of an object that performs a memory allocation, which fails if there is insufficient memory available. This kind of failure is called a leave on Symbian OS, and is discussed in more detail shortly. A constructor should never be able to leave, because this can cause memory leaks, as we will discuss in Section 3.6 on two-phase construction. To avoid the potential for memory leaks upon construction, C classes are characterized by an idiom called two-phase construction, which also prevents accidental creation of objects of a C class on the stack.
C classes will be discussed more when we deal with two-phase construction and the cleanup stack.
3.2.3 R Classes
R classes own an external resource handle, for example a handle to a server session. R classes are diverse, and vary from holding a file server session handle (e.g., class RFs) to memory allocated on the heap (e.g., class RBuf). R classes are often small, and usually contain no other member data besides the resource handle. R-class objects may exist as class members, as local stack-based variables or, occasionally, on the heap.
Initializing R classes usually requires calling a special method, such as Open(), Create() or Connect(). Similarly, destroying R classes usually involves calling a special cleanup method, which is usually named Close() although it may sometimes be named something else, such as Reset(). It is rare for an R class to have a destructor too - it generally does not need one because cleanup is performed in the cleanup method.
Although you will probably use a number of Symbian R classes, there are only a few cases where you may need to write your own R class, for example when you are creating a client-server application.
3.2.4 M Classes
On Symbian OS, M classes are often used in callback or observer classes. An M class is an abstract interface class which declares pure virtual functions and has no member data. A concrete class deriving from such a class typically inherits from CBase (or a CBase-derived class) as its first base class and from one or more M-class 'mixin' interfaces, and implements the interface functions.
An M class should usually have only pure virtual functions, but may occasionally have non-pure virtual functions.
Tip: The only form of multiple inheritance encouraged on Symbian C++ is that which uses one CBase-derived class and mixes in one or more M classes. The correct class-derivation order is always to put the CBase-derived class first, to emphasize the primary inheritance tree and ensure proper cleanup through the cleanup stack.
Post a comment