Warning: That file was not part of the compilation database. It may have many parsing errors.
1 | /* This file is part of the KDE libraries |
---|---|
2 | Copyright (c) 2002-2003 KDE Team |
3 | |
4 | This library is free software; you can redistribute it and/or |
5 | modify it under the terms of the GNU Library General Public |
6 | License as published by the Free Software Foundation; either |
7 | version 2 of the License, or (at your option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, |
10 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
11 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
12 | Library General Public License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to |
16 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
17 | Boston, MA 02110-1301, USA. |
18 | */ |
19 | |
20 | /** |
21 | * @file kdemacros.h |
22 | * |
23 | * This header defines several compiler-independent macros which are used |
24 | * throughout KDE. Most of these macros make use of GCC extensions; on other |
25 | * compilers, they don't have any effect. |
26 | */ |
27 | |
28 | #ifndef _KDE_MACROS_H_ |
29 | #define _KDE_MACROS_H_ |
30 | |
31 | #define __KDE_HAVE_GCC_VISIBILITY |
32 | |
33 | /** |
34 | * @def KDE_NO_EXPORT |
35 | * @ingroup KDEMacros |
36 | * |
37 | * The KDE_NO_EXPORT macro marks the symbol of the given variable |
38 | * to be hidden. A hidden symbol is stripped during the linking step, |
39 | * so it can't be used from outside the resulting library, which is similar |
40 | * to static. However, static limits the visibility to the current |
41 | * compilation unit. Hidden symbols can still be used in multiple compilation |
42 | * units. |
43 | * |
44 | * \code |
45 | * int KDE_NO_EXPORT foo; |
46 | * int KDE_EXPORT bar; |
47 | * \endcode |
48 | * |
49 | * @sa KDE_EXPORT |
50 | */ |
51 | |
52 | /** |
53 | * @def KDE_EXPORT |
54 | * @ingroup KDEMacros |
55 | * |
56 | * The KDE_EXPORT macro marks the symbol of the given variable |
57 | * to be visible, so it can be used from outside the resulting library. |
58 | * |
59 | * \code |
60 | * int KDE_NO_EXPORT foo; |
61 | * int KDE_EXPORT bar; |
62 | * \endcode |
63 | * |
64 | * @sa KDE_NO_EXPORT |
65 | */ |
66 | |
67 | /** |
68 | * @def KDE_IMPORT |
69 | * @ingroup KDEMacros |
70 | */ |
71 | |
72 | #ifdef __KDE_HAVE_GCC_VISIBILITY |
73 | #define KDE_NO_EXPORT __attribute__ ((visibility("hidden"))) |
74 | #define KDE_EXPORT __attribute__ ((visibility("default"))) |
75 | #define KDE_IMPORT __attribute__ ((visibility("default"))) |
76 | #elif defined(_WIN32) || defined(_WIN64) |
77 | #define KDE_NO_EXPORT |
78 | #define KDE_EXPORT __declspec(dllexport) |
79 | #define KDE_IMPORT __declspec(dllimport) |
80 | #else |
81 | #define KDE_NO_EXPORT |
82 | #define KDE_EXPORT |
83 | #define KDE_IMPORT |
84 | #endif |
85 | |
86 | /** |
87 | * @def KDE_PACKED |
88 | * @ingroup KDEMacros |
89 | * |
90 | * The KDE_PACKED macro can be used to hint the compiler that a particular |
91 | * structure or class should not contain unnecessary paddings. |
92 | */ |
93 | |
94 | #ifdef __GNUC__ |
95 | #define KDE_PACKED __attribute__((__packed__)) |
96 | #else |
97 | #define KDE_PACKED |
98 | #endif |
99 | |
100 | /** |
101 | * @def KDE_DEPRECATED |
102 | * @ingroup KDEMacros |
103 | * |
104 | * The KDE_DEPRECATED macro can be used to trigger compile-time warnings |
105 | * with newer compilers when deprecated functions are used. |
106 | * |
107 | * For non-inline functions, the macro gets inserted at front of the |
108 | * function declaration, right before the return type: |
109 | * |
110 | * \code |
111 | * KDE_DEPRECATED void deprecatedFunctionA(); |
112 | * KDE_DEPRECATED int deprecatedFunctionB() const; |
113 | * \endcode |
114 | * |
115 | * For functions which are implemented inline, |
116 | * the KDE_DEPRECATED macro is inserted at the front, right before the return |
117 | * type, but after "static", "inline" or "virtual": |
118 | * |
119 | * \code |
120 | * KDE_DEPRECATED void deprecatedInlineFunctionA() { .. } |
121 | * virtual KDE_DEPRECATED int deprecatedInlineFunctionB() { .. } |
122 | * static KDE_DEPRECATED bool deprecatedInlineFunctionC() { .. } |
123 | * inline KDE_DEPRECATED bool deprecatedInlineFunctionD() { .. } |
124 | * \endcode |
125 | * |
126 | * You can also mark whole structs or classes as deprecated, by inserting the |
127 | * KDE_DEPRECATED macro after the struct/class keyword, but before the |
128 | * name of the struct/class: |
129 | * |
130 | * \code |
131 | * class KDE_DEPRECATED DeprecatedClass { }; |
132 | * struct KDE_DEPRECATED DeprecatedStruct { }; |
133 | * \endcode |
134 | * |
135 | * \note |
136 | * It does not make much sense to use the KDE_DEPRECATED keyword for a Qt signal; |
137 | * this is because usually get called by the class which they belong to, |
138 | * and one would assume that a class author does not use deprecated methods of |
139 | * his own class. The only exception to this are signals which are connected to |
140 | * other signals; they get invoked from moc-generated code. In any case, |
141 | * printing a warning message in either case is not useful. |
142 | * For slots, it can make sense (since slots can be invoked directly) but be |
143 | * aware that if the slots get triggered by a signal, the will get called from |
144 | * moc code as well and thus the warnings are useless. |
145 | * |
146 | * \par |
147 | * Also note that it is not possible to use KDE_DEPRECATED for classes which |
148 | * use the k_dcop keyword (to indicate a DCOP interface declaration); this is |
149 | * because the dcopidl program would choke on the unexpected declaration |
150 | * syntax. |
151 | * |
152 | * \note |
153 | * KDE_DEPRECATED cannot be used at the end of the declaration anymore, |
154 | * unlike what is done for KDE3. |
155 | * |
156 | * \note |
157 | * KDE_DEPRECATED cannot be used for constructors, |
158 | * use KDE_CONSTRUCTOR_DEPRECATED instead. |
159 | */ |
160 | |
161 | #ifdef __cplusplus |
162 | # include <QtCore/qglobal.h> |
163 | # ifndef KDE_DEPRECATED |
164 | # ifdef KDE_DEPRECATED_WARNINGS |
165 | # define KDE_DEPRECATED Q_DECL_DEPRECATED |
166 | # else |
167 | # define KDE_DEPRECATED |
168 | # endif |
169 | # endif |
170 | #endif |
171 | |
172 | /** |
173 | * @def KDE_CONSTRUCTOR_DEPRECATED |
174 | * @ingroup KDEMacros |
175 | * |
176 | * The KDE_CONSTRUCTOR_DEPRECATED macro can be used to trigger compile-time |
177 | * warnings with newer compilers when deprecated constructors are used. |
178 | * |
179 | * For non-inline constructors, the macro gets inserted at front of the |
180 | * constructor declaration, right before the return type: |
181 | * |
182 | * \code |
183 | * KDE_CONSTRUCTOR_DEPRECATED classA(); |
184 | * \endcode |
185 | * |
186 | * For constructors which are implemented inline, |
187 | * the KDE_CONSTRUCTOR_DEPRECATED macro is inserted at the front, |
188 | * but after the "inline" keyword: |
189 | * |
190 | * \code |
191 | * KDE_CONSTRUCTOR_DEPRECATED classA() { .. } |
192 | * \endcode |
193 | * |
194 | * \note Do not forget that inlined constructors are not allowed in public |
195 | * headers for KDE. |
196 | */ |
197 | |
198 | #ifndef KDE_CONSTRUCTOR_DEPRECATED |
199 | # ifdef __GNUC__ |
200 | # if __GNUC__ == 3 && __GNUC_MINOR__ <= 3 |
201 | /* GCC 3.3.x cannot handle Qt 4.1.2's definition of Q_DECL_CONSTRUCTOR_DEPRECATED */ |
202 | # define KDE_CONSTRUCTOR_DEPRECATED |
203 | # else |
204 | # define KDE_CONSTRUCTOR_DEPRECATED Q_DECL_CONSTRUCTOR_DEPRECATED |
205 | # endif |
206 | # else |
207 | # define KDE_CONSTRUCTOR_DEPRECATED Q_DECL_CONSTRUCTOR_DEPRECATED |
208 | # endif |
209 | #endif |
210 | |
211 | /** |
212 | * @def KDE_NO_DEPRECATED |
213 | * @ingroup KDEMacros |
214 | * |
215 | * The KDE_NO_DEPRECATED indicates if the deprecated symbols of the platform |
216 | * have been compiled out. |
217 | */ |
218 | /* #undef KDE_NO_DEPRECATED */ |
219 | |
220 | /** |
221 | * @def KDE_ISLIKELY |
222 | * @ingroup KDEMacros |
223 | * |
224 | * The KDE_ISLIKELY macro tags a boolean expression as likely to evaluate to |
225 | * @c true. When used in an <tt>if ( )</tt> statement, it gives a hint to the compiler |
226 | * that the following codeblock is likely to get executed. Providing this |
227 | * information helps the compiler to optimize the code for better performance. |
228 | * Using the macro has an insignificant code size or runtime memory footprint impact. |
229 | * The code semantics is not affected. |
230 | * |
231 | * Example: |
232 | * |
233 | * \code |
234 | * if ( KDE_ISLIKELY( testsomething() ) ) |
235 | * abort(); // assume its likely that the application aborts |
236 | * \endcode |
237 | * |
238 | * \note |
239 | * Providing wrong information ( like marking a condition that almost never |
240 | * passes as 'likely' ) will cause a significant runtime slowdown. Therefore only |
241 | * use it for cases where you can be sure about the odds of the expression to pass |
242 | * in all cases ( independent from e.g. user configuration ). |
243 | * |
244 | * \note |
245 | * Do NOT use ( !KDE_ISLIKELY(foo) ) as an replacement for KDE_ISUNLIKELY() ! |
246 | * |
247 | * @sa KDE_ISUNLIKELY |
248 | */ |
249 | |
250 | /** |
251 | * @def KDE_ISUNLIKELY |
252 | * @ingroup KDEMacros |
253 | * |
254 | * The KDE_ISUNLIKELY macro tags a boolean expression as likely to evaluate to |
255 | * @c false. When used in an <tt>if ( )</tt> statement, it gives a hint to the compiler |
256 | * that the following codeblock is unlikely to get executed. Providing this |
257 | * information helps the compiler to optimize the code for better performance. |
258 | * Using the macro has an insignificant code size or runtime memory footprint impact. |
259 | * The code semantics is not affected. |
260 | * |
261 | * Example: |
262 | * |
263 | * \code |
264 | * if ( KDE_ISUNLIKELY( testsomething() ) ) |
265 | * abort(); // assume its unlikely that the application aborts |
266 | * \endcode |
267 | * |
268 | * \note |
269 | * Providing wrong information ( like marking a condition that almost never |
270 | * passes as 'unlikely' ) will cause a significant runtime slowdown. Therefore only |
271 | * use it for cases where you can be sure about the odds of the expression to pass |
272 | * in all cases ( independent from e.g. user configuration ). |
273 | * |
274 | * \note |
275 | * Do NOT use ( !KDE_ISUNLIKELY(foo) ) as an replacement for KDE_ISLIKELY() ! |
276 | * |
277 | * @sa KDE_ISLIKELY |
278 | */ |
279 | |
280 | #if defined(__GNUC__) && __GNUC__ - 0 >= 3 |
281 | # define KDE_ISLIKELY( x ) __builtin_expect(!!(x),1) |
282 | # define KDE_ISUNLIKELY( x ) __builtin_expect(!!(x),0) |
283 | #else |
284 | # define KDE_ISLIKELY( x ) ( x ) |
285 | # define KDE_ISUNLIKELY( x ) ( x ) |
286 | #endif |
287 | |
288 | |
289 | /** |
290 | * @ingroup KDEMacros |
291 | * This macro, and it's friends going up to 10 reserve a fixed number of virtual |
292 | * functions in a class. Because adding virtual functions to a class changes the |
293 | * size of the vtable, adding virtual functions to a class breaks binary |
294 | * compatibility. However, by using this macro, and decrementing it as new |
295 | * virtual methods are added, binary compatibility can still be preserved. |
296 | * |
297 | * \note The added functions must be added to the header at the same location |
298 | * as the macro; changing the order of virtual functions in a header is also |
299 | * binary incompatible as it breaks the layout of the vtable. |
300 | */ |
301 | #define RESERVE_VIRTUAL_1 \ |
302 | virtual void reservedVirtual1() {} |
303 | /** |
304 | * @ingroup KDEMacros |
305 | */ |
306 | #define RESERVE_VIRTUAL_2 \ |
307 | virtual void reservedVirtual2() {} \ |
308 | RESERVE_VIRTUAL_1 |
309 | /** |
310 | * @ingroup KDEMacros |
311 | */ |
312 | #define RESERVE_VIRTUAL_3 \ |
313 | virtual void reservedVirtual3() {} \ |
314 | RESERVE_VIRTUAL_2 |
315 | /** |
316 | * @ingroup KDEMacros |
317 | */ |
318 | #define RESERVE_VIRTUAL_4 \ |
319 | virtual void reservedVirtual4() {} \ |
320 | RESERVE_VIRTUAL_3 |
321 | /** |
322 | * @ingroup KDEMacros |
323 | */ |
324 | #define RESERVE_VIRTUAL_5 \ |
325 | virtual void reservedVirtual5() {} \ |
326 | RESERVE_VIRTUAL_4 |
327 | /** |
328 | * @ingroup KDEMacros |
329 | */ |
330 | #define RESERVE_VIRTUAL_6 \ |
331 | virtual void reservedVirtual6() {} \ |
332 | RESERVE_VIRTUAL_5 |
333 | /** |
334 | * @ingroup KDEMacros |
335 | */ |
336 | #define RESERVE_VIRTUAL_7 \ |
337 | virtual void reservedVirtual7() {} \ |
338 | RESERVE_VIRTUAL_6 |
339 | /** |
340 | * @ingroup KDEMacros |
341 | */ |
342 | #define RESERVE_VIRTUAL_8 \ |
343 | virtual void reservedVirtual8() {} \ |
344 | RESERVE_VIRTUAL_7 |
345 | /** |
346 | * @ingroup KDEMacros |
347 | */ |
348 | #define RESERVE_VIRTUAL_9 \ |
349 | virtual void reservedVirtual9() {} \ |
350 | RESERVE_VIRTUAL_8 |
351 | #define RESERVE_VIRTUAL_10 \ |
352 | virtual void reservedVirtual10() {} \ |
353 | RESERVE_VIRTUAL_9 |
354 | |
355 | /** |
356 | * @def KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION |
357 | * @ingroup KDEMacros |
358 | * |
359 | * From Qt's global.h: |
360 | * Compilers which follow outdated template instantiation rules |
361 | * require a class to have a comparison operator to exist when |
362 | * a QList of this type is instantiated. It's not actually |
363 | * used in the list, though. Hence the dummy implementation. |
364 | * Just in case other code relies on it we better trigger a warning |
365 | * mandating a real implementation. |
366 | * |
367 | * In KDE we need this for classes which are exported in a shared |
368 | * lib because some compilers need a full instantiated class then. |
369 | * |
370 | * @sa KDE_DUMMY_COMPARISON_OPERATOR |
371 | * @sa KDE_DUMMY_QHASH_FUNCTION |
372 | */ |
373 | |
374 | /** |
375 | * @def KDE_DUMMY_COMPARISON_OPERATOR |
376 | * @ingroup KDEMacros |
377 | * |
378 | * The KDE_DUMMY_COMPARISON_OPERATOR defines a simple |
379 | * compare operator for classes. |
380 | * |
381 | * @sa KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION |
382 | * @sa KDE_DUMMY_QHASH_FUNCTION |
383 | */ |
384 | |
385 | /** |
386 | * @def KDE_DUMMY_QHASH_FUNCTION |
387 | * @ingroup KDEMacros |
388 | * |
389 | * The KDE_DUMMY_QHASH_FUNCTION defines a simple |
390 | * hash-function for classes. |
391 | * |
392 | * @sa KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION |
393 | * @sa KDE_DUMMY_COMPARISON_OPERATOR |
394 | */ |
395 | |
396 | #ifdef KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION |
397 | # define KDE_DUMMY_COMPARISON_OPERATOR(C) \ |
398 | bool operator==(const C&) const { \ |
399 | qWarning(#C"::operator==(const "#C"&) was called"); \ |
400 | return false; \ |
401 | } |
402 | # define KDE_DUMMY_QHASH_FUNCTION(C) \ |
403 | inline uint qHash(const C) { \ |
404 | qWarning("inline uint qHash(const "#C") was called"); \ |
405 | return 0; \ |
406 | } |
407 | #else |
408 | # define KDE_DUMMY_COMPARISON_OPERATOR(C) |
409 | # define KDE_DUMMY_QHASH_FUNCTION(C) |
410 | #endif |
411 | |
412 | /** |
413 | * @def KDE_BF_ENUM |
414 | * @ingroup KDEMacros |
415 | * |
416 | * The KDE_BF_ENUM is used when storing an enum |
417 | * in a bitfield, to ensure correct conversion |
418 | * by all compilers. |
419 | * |
420 | * @sa KDE_CAST_BF_ENUM |
421 | */ |
422 | |
423 | /** |
424 | * @def KDE_CAST_BF_ENUM |
425 | * @ingroup KDEMacros |
426 | * |
427 | * The KDE_CAST_BF_ENUM is used when retrieving an |
428 | * enum from a bitfield, to ensure correct conversion |
429 | * by all compilers. |
430 | * |
431 | * @sa KDE_BF_ENUM |
432 | */ |
433 | |
434 | #ifdef Q_CC_MSVC |
435 | # define KDE_BF_ENUM(a) unsigned int |
436 | # define KDE_CAST_BF_ENUM(a,b) static_cast<a>(b) |
437 | #else |
438 | # define KDE_BF_ENUM(a) a |
439 | # define KDE_CAST_BF_ENUM(a,b) b |
440 | #endif |
441 | |
442 | /** |
443 | * @def KDE_WEAK_SYMBOL |
444 | * @ingroup KDEMacros |
445 | * |
446 | * The KDE_WEAK_SYMBOL macro can be used to tell the compiler that |
447 | * a particular function should be a weak symbol (that e.g. may be overridden |
448 | * in another library, -Bdirect will not bind this symbol directly) |
449 | */ |
450 | |
451 | #ifdef __GNUC__ |
452 | #define KDE_WEAK_SYMBOL __attribute__((__weak__)) |
453 | #else |
454 | #define KDE_WEAK_SYMBOL |
455 | #endif |
456 | |
457 | |
458 | /** |
459 | * @def KDE_MUST_USE_RESULT |
460 | * @ingroup KDEMacros |
461 | * |
462 | * The KDE_MUST_USE_RESULT macro can be used to tell the compiler that |
463 | * a particular functions return value must be checked. |
464 | */ |
465 | |
466 | #ifdef __GNUC__ |
467 | #define KDE_MUST_USE_RESULT __attribute__((__warn_unused_result__)) |
468 | #else |
469 | #define KDE_MUST_USE_RESULT |
470 | #endif |
471 | |
472 | |
473 | |
474 | #endif /* _KDE_MACROS_H_ */ |
475 |
Warning: That file was not part of the compilation database. It may have many parsing errors.