source: trunk/doc/src/platforms/symbian-exceptionsafety.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
  • Property svn:eol-style set to native
File size: 10.0 KB
RevLine 
[556]1/****************************************************************************
2**
[846]3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
[556]4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
[846]9** $QT_BEGIN_LICENSE:FDL$
[556]10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
[846]13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
[556]15**
[846]16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
[556]21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \page symbianexceptionsafety.html
30 \title Exception Safety with Symbian
31 \ingroup qtsymbian
32 \brief A guide to integrating exception safety in Qt with Symbian.
33
34 The following sections describe how Qt code can interoperate with Symbian's
35 exception safety system.
36
37 \tableofcontents
38
39 \section1 What the problem is
40
41 Qt and Symbian have different exception systems. Qt works with standard C++
42 exceptions, whereas Symbian has its TRAP/Leave/CleanupStack system. So, what would
43 happen if you mix the two systems? It could go wrong in a number of ways.
44
45 Clean-up ordering would be different between the two. When Symbian code
46 leaves, the clean-up stack is cleaned up before anything else happens. After
47 that, the objects on the call stack would be cleaned up as with a normal
48 exception. So if there are any dependencies between stack-based and
49 objects owned by the clean-up stack, there could be problems due to this
50 ordering.
51
52 Symbian's \c XLeaveException, which is used when Symbian implements leaves as
53 exceptions, is not derived from \c std::exception, so would not be caught in
54 Qt catch statements designed to catch \c std::exception.
55
56 Qt's and standard C++'s \c std::exception derived exceptions result in program
57 termination if they fall back to a Symbian TRAP.
58
59 These problems can be solved with barrier macros and helper functions that
60 will translate between the two exception systems. Use them, in Qt code,
61 whenever calling into or being called from Symbian code.
62
63 \section1 Qt calls to Symbian
64
65 When calling Symbian leaving functions from Qt code, we want to translate
66 Symbian leaves to standard C++ exceptions. The following help is provided:
67
68 \list
69 \o \l qt_symbian_throwIfError() takes a Symbian
70 error code and throws an appropriate exception to represent it.
71 This will do nothing if the error code is not in fact an error. The
72 function is equivalent to Symbian's \c User::LeaveIfError.
73 \o \l q_check_ptr() takes a pointer and throws a std::bad_alloc
74 exception if it is 0, otherwise the pointer is returned. This can be
75 used to check the success of a non-throwing allocation, eg from
76 \c malloc(). The function is equivalent to Symbian's \c
77 User::LeaveIfNull.
78 \o \l QT_TRAP_THROWING() takes a Symbian leaving
79 code fragment f and runs it under a trap harness converting any resulting
80 error into an exception.
81 \o \c TRAP and \c TRAPD from the Symbian libraries can be used to convert
82 leaves to error codes.
83 \endlist
84
85 \code
86 HBufC* buf=0;
87 // this will throw a std::bad_alloc because we've asked for too much memory
88 QT_TRAP_THROWING(buf = HBufC::NewL(100000000));
89
90 _LIT(KStr,"abc");
91 TInt pos = KStr().Locate('c');
92 // pos is a good value, >= 0, so no exception is thrown
93 qt_symbian_throwIfError(pos);
94
95 pos = KStr().Locate('d');
96 // pos == KErrNotFound, so this throws an exception
97 qt_symbian_throwIfError(pos);
98
99 // we are asking for a lot of memory, HBufC::New may return NULL, so check it
100 HBufC *buffer = q_check_ptr(HBufC::New(1000000));
101 \endcode
102
103 \section2 Be careful with new and CBase
104
105 When writing Qt code, \c new will normally throw a \c std::bad_alloc if the
106 allocation fails. However this may not happen if the object being created
107 has its own \c {operator new}. For example, CBase and derived classes have
108 their own \c {operator new} which returns 0 and the \c {new(ELeave)}
109 overload for a leaving \c {operator new}, neither of which does what we want.
110 When using 2-phase construction of CBase derived objects, use \c new and