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.