Symbian OS Explained Effective C++ Programming for Smartphones phần 9 pot

292 COMPATIBILITY do not have constructors and never have destructors. Once a T class is publicly defined, it is often difficult to make client-compatible changes to it. 18.8 Summary A change is acceptable if every line of code affected by it can be altered, where necessary, and the code rebuilt against the changes. In effect, this often means that a change must be restricted to the internals of a component rather than its public API. For this reason, you should endeavor to keep private definitions and header files (and anything else which is likely to be subject to change) out of the public domain. A change is also acceptable if it can be verified as compatible, accord- ing to the guidelines I’ve discussed here. In general, the key compatibility issue for shared library DLLs is backward binary compatibility, with source compatibility an additional aim. These guidelines derive from those used within Symbian, in accor- dance with the C++ standard. I am very grateful to David Batchelor, John Forrest and Andrew Thoelke of Symbian who have previously written guides to compatibility best practice on Symbian OS, which I used as the basis of this chapter. Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 19 Thin Templates Now, now, my good man, this is no time to be making enemies Voltaire on his deathbed, in response to a priest who asked him to renounce Satan C++ templates are useful for code that can be reused with different types, for example to implement container classes such as dynamic arrays. Templates allow the code to be generic, accepting any type, without forcing the programmer to overload a function. template<class T> class CDynamicArray : public CBase { public: // Functions omitted for clarity void Add(const T& aEntry); T& operator[](TInt aIndex); }; Prior to the introduction of templates to the C++ standard, generic code tended to be written using void* arguments, to allow the caller to specify any pointer type as an argument. However, the major benefit of using C++ templates for genericity, instead of void*, is that templated code can be checked for type safety at compile time. However, the problem with template code is that it can lead to a major increase in code size, because for each type used in the template, separate code is generated for each templated function. For example, if your code used the CDynamicArray class above for both an array of HBufC* andanarrayofTUid values, the object code generated when your code was compiled would contain two copies of the Add() function and two copies of operator[], one for an array of HBufC* and one for an array of TUid. What’s more, the template code is generated, at best, once for each DLL or EXE that uses it and, at worst, for every compilation unit. Compiling a templated class into a binary can thus have a significant impact on its size. Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 294 THIN TEMPLATES The advantage of automatically generated template code is thus a disadvantage when code size matters. Because Symbian OS code is deployed on mobile phones with limited ROM and RAM sizes, it is important to avoid code bloat. Using templated classes, such as CDynamicArray above, expands the code size too significantly. To avoid this, but still reap the benefits of C++ templates, Symbian OS makes use of the thin template pattern. This chapter describes the pattern in more detail, so you have a good idea of how the system code works. If you intend to use C++ templates 1 in your code on Symbian OS, you should endeavor to use this pattern to minimize code size. Let’s consider the theory first, and then look at a couple of examples of the use of thin templates in Symbian OS code. The thin template idiom works by implementing the necessary code logic in a generic base class that uses type-unsafe TAny* pointers rather than a templated type. This code is liable to misuse because of the lack of type-checking, so typically these methods will be made protected in the base class to prevent them being called naively. A templated class will then be defined which uses private inheritance 2 from this class to take advantage of the generic implementation. The derived class declares the interface to be used by its clients and implements it inline in terms of the base class. I’ll show an example of this from Symbian OS code shortly. Since the derived class uses templates, it can be used with any type required. It is type-safe because it is templated and thus picks up the use of an incorrect type at compile time. There are no additional runtime costs because the interfaces are defined inline, so it will be as if the caller had used the base class directly. And importantly, since the base class is not templated, only a single copy of the code is generated, regardless of the number of types that are used. For illustration purposes, here is just a small part of the RArrayBase class and its subclass RArray (from e32std.h and e32std.inl). The type-unsafe base class (RArrayBase) implements the code logic for the array but cannot be used directly because all its methods are protected. You’ll find a detailed discussion of the RArray class, and other Symbian OS container classes, in Chapter 7. 1 You will typically want to use templates when writing a class that manipulates several different types using the same generic code. The code should be agnostic about the type passed into the template parameter, that is, the underlying logic is independent of type. Typical examples of (thin) template classes in Symbian OS are the array classes (I’ll discuss RArray shortly), the singly- and doubly-linked list classes (based on TSglQueBase and TDblQueBase) and the circular buffers (based on CCirBufBase). 2 Private inheritance means that the derived class is implemented in terms of the base class. Private inheritance is used when the deriving class uses some of the implemented methods of the base class, but has no direct conceptual relationship with the base class. Using private inheritance allows implementation to be inherited but all the methods of the base class become private members of the deriving class. In effect, the deriving class does not inherit the interface of the base class . Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com THIN TEMPLATES 295 class RArrayBase { protected: IMPORT_C RArrayBase(TInt anEntrySize); IMPORT_C RArrayBase(TInt aEntrySize,TAny* aEntries, TInt aCount); IMPORT_C TAny* At(TInt anIndex) const; IMPORT_C TInt Append(const TAny* anEntry); IMPORT_C TInt Insert(const TAny* anEntry, TInt aPos); }; The templated RArray class privately inherits the implementation and defines a clear, usable API for clients. The API is defined inline and uses the base class implementation. Elements of the array are instances of the template class. template <class T> class RArray : private RArrayBase { public: inline RArray(); inline const T& operator[](TInt anIndex) const; inline T& operator[](TInt anIndex); inline TInt Append(const T& anEntry); inline TInt Insert(const T& anEntry, TInt aPos); }; template <class T> inline RArray<T>::RArray() : RArrayBase(sizeof(T)) {} template <class T> inline const T& RArray<T>::operator[](TInt anIndex) const {return *(const T*)At(anIndex); } template <class T> inline T& RArray<T>::operator[](TInt anIndex) {return *(T*)At(anIndex); } template <class T> inline TInt RArray<T>::Append(const T& anEntry) {return RArrayBase::Append(&anEntry);} template <class T> inline TInt RArray<T>::Insert(const T& anEntry, TInt aPos) {return RArrayBase::Insert(&anEntry,aPos);} Use of the class is then straightforward: void TestRArray() { const TInt arraySize = 3; RArray<TInt> myArray(arraySize); for (TInt index = 0; index<arraySize; index++) { Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 296 THIN TEMPLATES myArray.Append(index); } TInt count = myArray.Count(); ASSERT(arraySize==count); for (index = 0; index<arraySize; index++) { ASSERT(myArray[index]==index); } } For another example of the thin template pattern in Symbian OS, consider the TBufC and TBuf descriptor classes discussed in Chapter 5. These classes are templated on an integer, the value of which is used as the variable which determines the maximum statically-allocated length of the buffer. In this case, the inheritance model is public and the derived class publicly inherits the base class implementation (whereas the previous example used private inheritance to gain access to the implementation without inheriting the behavior). The constructors of the derived TBufC16 class, and other functions that use the template parameter, are declared inline. I’ve shown the constructors for the base and derived classes below (from e32des16.h and e32std.inl): class TBufCBase16 : public TDesC16 { protected: IMPORT_C TBufCBase16(); inline TBufCBase16(TInt aLength); IMPORT_C TBufCBase16(const TUint16 *aString,TInt aMaxLength); IMPORT_C TBufCBase16(const TDesC16 &aDes,TInt aMaxLength); }; template <TInt S> class TBufC16 : public TBufCBase16 { public: inline TBufC16(); inline TBufC16(const TUint16 *aString); inline TBufC16(const TDesC16 &aDes); }; template <TInt S> inline TBufC16<S>::TBufC16() : TBufCBase16() {} template <TInt S> inline TBufC16<S>::TBufC16(const TUint16 *aString) : TBufCBase16(aString,S) {} template <TInt S> inline TBufC16<S>::TBufC16(const TDesC16 &aDes) Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com SUMMARY 297 : TBufCBase16(aDes,S) {} To get the benefits of C++ templates without the disadvantages of code bloat, you should prefer the thin-template idiom which is used throughout Symbian OS code. 19.1 Summary This chapter explained why C++ templates are ideal for reusable type- safe but type-agnostic code, but have the disadvantage that they can increase their clients’ code size quite considerably. For each templated class, every time a different type is used, separate code is generated for every templated function. Furthermore, this code duplication occurs in each client DLL or compilation unit using the templated class. This can cause significant code bloat unless the number of different types that are used with the templated class is limited, the code generated is small, and it is guaranteed that only a few clients will use the templated class. Many Symbian OS container classes use the thin template pattern to gain the advantages of C++ templates without the disadvantages of increased code size (which is unacceptable on the ”small footprint” devices on which Symbian OS is deployed). This chapter described the characteristics of the thin template pattern, which typically defines a base class (containing a generic implementation, usually specified as protected to prevent it being called directly) and a derived class (which uses private inheritance to inherit the implementation of the base class). The derived class exposes a templated interface, implemented inline in terms of the base class and thus benefits from compile-time type-checking by using C++ templates. The derived class does not have the associated size overhead because, regardless of the number of types used, the code is inline and uses a single copy of the generic base class implementation. In this chapter the RArray, TBuf and TBufC classes illustrated the thin template idiom as it is employed on Symbian OS, and how these classes should be used. The RArray class is discussed in detail in Chapter 7, while TBuf and TBufC are examined in Chapter 5. Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 20 Expose a Comprehensive and Comprehensible API Have no fear of perfection – you’ll never reach it Salvador Dali So, you’re ready to design a class. You’ve read Chapter 1, and have thought about the characteristics of your class, maybe by asking the following questions: ”How will objects of my class be instantiated?”; ”Will they be stack- or heap-based?”; ”Will the class have any data or simply provide an interface?”; ”Will it need a destructor?” The answers to these questions will help you decide what kind of Symbian OS class it is and give you the first letter of its name, the rest of which is down to you. When choosing a class name it is frequently difficult to be descriptive yet brief. Unless your class consists solely of static functions, it will be instantiated and used as an object. The class name should be a noun to reflect that. I’ll discuss the best strategy for naming classes and their member data, methods and parameters, later in this chapter. The type of class you choose affects, to some extent, the definition of the class. For example, if you decide to implement it as a T class, it won’t have a destructor nor own any data which needs one. On the other hand, if you’re writing a C class, you’ll most likely need to use two-phase construction. To do this, you will make constructors protected or private and provide a public static function, usually called NewL(), which calls a non-public second-phase construction method to perform any initialization that may leave. You’ll find more information about two-phase construction in Chapter 4. This chapter aims to highlight the factors you need to consider when designing a class, in particular the application programming interface (API) it will expose to its clients. The chapter isn’t a comprehensive treatise in class design – that would need a whole book – but it does point out some of the more important points for good C++ class design on Symbian OS. Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 300 EXPOSE A COMPREHENSIVE AND COMPREHENSIBLE API The quality of your API is important if your clients are to find it easy to understand and use. It should provide all the methods they need to perform the tasks for which the class is designed, but no more. You should design your interface to be as simple as possible, each member function having a distinct purpose and no two functions overlapping in what they perform. Try and limit the number of methods, too – if your class provides too many it can be confusing and difficult to work with. A powerful class definition has a set of functions where each has a clear purpose, making it straightforward, intuitive and attractive to reuse. The alternative might make a client think twice about using the class – if the functions are poorly declared, why trust the implementation? Besides the benefit of avoiding duplicating the implementation effort, with limited memory space on a typical Symbian OS phone, it’s in everyone’s interests to reuse code where possible. Even if your own code is the intended client, no matter! Should you decide later to reuse the class, the time you spend making it convenient to use will pay off. By making the class simple to understand and use, and cutting out duplicated functionality, you’ll cut down your test and maintenance time too. Furthermore, a well-defined class makes documentation easier and that’s got to be a good thing. 20.1 Class Layout Before looking at details of good API design, let’s consider the aesthetics of your class definition. When defining a class, make it easy for your clients to find the information they need. The convention is to lay out Symbian OS classes with public methods at the top, then protected and private methods, following this with public data if there is any (and later in this chapter I’ll describe why there usually shouldn’t be), protected and private data. I tend to use the public, protected and private access specifiers more than once to split the class into logically related methods or data. It doesn’t have any effect on the compiled C++, and it makes the class definition simpler to navigate. For example: class CMyExample : public CSomeBase { public: // Object instantiation and destruction static CMyExample* NewL(); static CMyExample* NewLC(); ∼CMyExample(); public: void PublicFunc1(); // Public functions, non virtual public: inline TBool Inline1(); // Inline (defined elsewhere) public: Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com IMPORT − C AND EXPORT − C 301 virtual void VirtualFunc1(); // Public virtual protected: // Implementation of pure virtual base class functions void DoProcessL(); // etc for other protected and private functions private: // Construction methods, private for 2-phase construct void ConstructL(); CMyExample(); private: // Data can also be grouped, e.g. into that owned CPointer* iData1; // by the class (which must be freed in the // destructor) & that which does not need cleanup }; 20.2 IMPORT − C and EXPORT − C Having declared your class, you should consider how your clients get access to it. If it will be used by code running in a separate executable (that is, DLL or EXE code compiled into a separate binary component) from the one in which you will deliver the class, you need to export functions from it. This makes the API ”public” to other modules by creating a .lib file, which contains the export table to be linked against by client code. There’s more about statically linked DLLs in Chapter 13. Every function you wish to export should be marked in the class definition in the header file with IMPORT_C. Admittedly, this is slightly confusing, until you consider that the client will be including the header file, so they are effectively ”importing” your function definition into their code module. You should mark the corresponding function definition in the .cpp file with EXPORT_C. The number of functions marked IMPORT_C in the header files must match the number marked EXPORT_C in the source. Here’s an example of the use of the macros, which will doubtless look familiar from class definitions in the header files supplied by whichever Symbian OS SDK you use. class CMyExample : public CSomeBase { public: IMPORT_C static CMyExample* NewL(); public: IMPORT_C void Foo(); }; EXPORT_C CMyExample* CMyExample::NewL() { } Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com [...]... good programming style and there isn’t enough space in this book to go into too much detail Instead, I’ve tried to focus on a few aspects that can improve your C++ code on Symbian OS The chapter covers some of the main features of the Symbian OS coding standards and distils advice that developers working on Symbian OS have found to be most useful While it concentrates on issues specific to Symbian OS, ... concentrates on issues specific to Symbian OS, it also has some tips for general good programming style I used some excellent books on C++ for background information when researching this chapter; those I recommend in particular are listed in the Bibliography 21.1 Reduce the Size of Program Code Space is at a premium on Symbian OS Where possible, you should attempt to minimize the size of your program... memory for the allocation Leaves are the preferred method of coping with exceptional conditions such as low memory on Symbian OS When a memory failure occurs and causes your code to leave, you should have a higher level TRAP to ”catch” the failure and handle it gracefully (for example, by freeing some memory, closing the application, notifying the user, or whatever seems most appropriate) Symbian OS runs... memory efficiency The Symbian OS classes have been written and maintained by those with expertise in dealing with restricted memory resources, and the classes have been extensively tried and tested as the OS has evolved While the experience of writing your own utility classes and functions is irreplaceable, you get guaranteed efficiency and memory safety from using those provided by Symbian OS When allocating... assignment operator on Symbian OS very often As I’ve explained, C class objects are not suitable for copy or assignment, while T class objects are ideal candidates for allowing the compiler to generate its own implicit versions An R class object is unlikely to be copied and is safe for bitwise copy anyway You would usually not expect to define an explicit copy constructor or assignment operator for an R class... omitted for clarity }; Without looking at the declaration of MakeHospitalAppointment(), it’s not immediately clear how to call the method, for example to make an urgent hospital appointment for a new patient who already has some test data available Unless you name your parameters carefully, your client may well have to consult your documentation too, to find out the appropriate boolean value for each... from forgoing the function call.) On Symbian OS, limited memory resources typically mean that the overhead of a function call is preferable to the potential code bloat from a large section of inlined code Furthermore, inlined code is impossible to upgrade without breaking binary compatibility If a client uses your function, it is compiled into their code, and any change you make to it later will force... as part of the regular testing cycle, in order to catch regressions close to the time at which they are introduced 21.3 Use Stack Memory Carefully For a target mobile phone running Symbian OS, the program stack size defaults to 8 KB,4 and it doesn’t grow when that size is exceeded Actually that’s not quite true, because the Symbian OS emulator running on Windows will extend the program stack if the size... expose member data • the use of enumerations to clarify the role of a function parameter and allow it to be extended in future 316 EXPOSE A COMPREHENSIVE AND COMPREHENSIBLE API Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com • the functions a compiler will generate for a class if they are not declared This chapter also discussed the use of IMPORT_C and EXPORT_C on Symbian OS. .. object’s lifetime, the password could change, for better security I’ll leave that implementation as an exercise for the reader Where possible, use const on parameters, return values, ”query” methods, and other methods that do not modify the internals of a class It indicates invariance to other programmers and ensures that the compiler enforces it 20.5 Choosing Class, Method and Parameter Names The title . 297 : TBufCBase16(aDes,S) {} To get the benefits of C++ templates without the disadvantages of code bloat, you should prefer the thin-template idiom which is used throughout Symbian OS code. 19. 1. chapter explained why C++ templates are ideal for reusable type- safe but type-agnostic code, but have the disadvantage that they can increase their clients’ code size quite considerably. For each. out some of the more important points for good C++ class design on Symbian OS. Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 300 EXPOSE A COMPREHENSIVE AND COMPREHENSIBLE