• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdelibs-4.14.38 API Reference
  • KDE Home
  • Contact Us
 

KDECore

kdemacros.h.cmake
Go to the documentation of this file.
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 #cmakedefine __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 #cmakedefine 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_ */
This file is part of the KDE documentation.
Documentation copyright © 1996-2018 The KDE developers.
Generated on Tue Aug 21 2018 18:45:07 by doxygen 1.8.14 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KDECore

Skip menu "KDECore"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • File Members
  • Modules
  • Related Pages

kdelibs-4.14.38 API Reference

Skip menu "kdelibs-4.14.38 API Reference"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDEWebKit
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUnitConversion
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal