kdemacros.h.cmake

   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_ISLIKELY
 213  * @ingroup KDEMacros
 214  *
 215  * The KDE_ISLIKELY macro tags a boolean expression as likely to evaluate to
 216  * @c true. When used in an <tt>if ( )</tt> statement, it gives a hint to the compiler
 217  * that the following codeblock is likely to get executed. Providing this
 218  * information helps the compiler to optimize the code for better performance.
 219  * Using the macro has an insignificant code size or runtime memory footprint impact.
 220  * The code semantics is not affected.
 221  *
 222  * Example:
 223  *
 224  * \code
 225  * if ( KDE_ISLIKELY( testsomething() ) )
 226  *     abort();     // assume its likely that the application aborts
 227  * \endcode
 228  *
 229  * \note
 230  * Providing wrong information ( like marking a condition that almost never
 231  * passes as 'likely' ) will cause a significant runtime slowdown. Therefore only
 232  * use it for cases where you can be sure about the odds of the expression to pass
 233  * in all cases ( independent from e.g. user configuration ).
 234  *
 235  * \note
 236  * Do NOT use ( !KDE_ISLIKELY(foo) ) as an replacement for KDE_ISUNLIKELY() !
 237  *
 238  * @sa KDE_ISUNLIKELY
 239  */
 240
 241 /**
 242  * @def KDE_ISUNLIKELY
 243  * @ingroup KDEMacros
 244  *
 245  * The KDE_ISUNLIKELY macro tags a boolean expression as likely to evaluate to
 246  * @c false. When used in an <tt>if ( )</tt> statement, it gives a hint to the compiler
 247  * that the following codeblock is unlikely to get executed. Providing this
 248  * information helps the compiler to optimize the code for better performance.
 249  * Using the macro has an insignificant code size or runtime memory footprint impact.
 250  * The code semantics is not affected.
 251  *
 252  * Example:
 253  *
 254  * \code
 255  * if ( KDE_ISUNLIKELY( testsomething() ) )
 256  *     abort();     // assume its unlikely that the application aborts
 257  * \endcode
 258  *
 259  * \note
 260  * Providing wrong information ( like marking a condition that almost never
 261  * passes as 'unlikely' ) will cause a significant runtime slowdown. Therefore only
 262  * use it for cases where you can be sure about the odds of the expression to pass
 263  * in all cases ( independent from e.g. user configuration ).
 264  *
 265  * \note
 266  * Do NOT use ( !KDE_ISUNLIKELY(foo) ) as an replacement for KDE_ISLIKELY() !
 267  *
 268  * @sa KDE_ISLIKELY
 269  */
 270
 271 #if defined(__GNUC__) && __GNUC__ - 0 >= 3
 272 # define KDE_ISLIKELY( x )    __builtin_expect(!!(x),1)
 273 # define KDE_ISUNLIKELY( x )  __builtin_expect(!!(x),0)
 274 #else
 275 # define KDE_ISLIKELY( x )   ( x )
 276 # define KDE_ISUNLIKELY( x )  ( x )
 277 #endif
 278
 279
 280 /**
 281  * @ingroup KDEMacros
 282  * This macro, and it's friends going up to 10 reserve a fixed number of virtual
 283  * functions in a class.  Because adding virtual functions to a class changes the
 284  * size of the vtable, adding virtual functions to a class breaks binary
 285  * compatibility.  However, by using this macro, and decrementing it as new
 286  * virtual methods are added, binary compatibility can still be preserved.
 287  *
 288  * \note The added functions must be added to the header at the same location
 289  * as the macro; changing the order of virtual functions in a header is also
 290  * binary incompatible as it breaks the layout of the vtable.
 291  */
 292 #define RESERVE_VIRTUAL_1 \
 293     virtual void reservedVirtual1() {}
 294 /**
 295  * @ingroup KDEMacros
 296  */
 297 #define RESERVE_VIRTUAL_2 \
 298     virtual void reservedVirtual2() {} \
 299     RESERVE_VIRTUAL_1
 300 /**
 301  * @ingroup KDEMacros
 302  */
 303 #define RESERVE_VIRTUAL_3 \
 304     virtual void reservedVirtual3() {} \
 305     RESERVE_VIRTUAL_2
 306 /**
 307  * @ingroup KDEMacros
 308  */
 309 #define RESERVE_VIRTUAL_4 \
 310     virtual void reservedVirtual4() {} \
 311     RESERVE_VIRTUAL_3
 312 /**
 313  * @ingroup KDEMacros
 314  */
 315 #define RESERVE_VIRTUAL_5 \
 316     virtual void reservedVirtual5() {} \
 317     RESERVE_VIRTUAL_4
 318 /**
 319  * @ingroup KDEMacros
 320  */
 321 #define RESERVE_VIRTUAL_6 \
 322     virtual void reservedVirtual6() {} \
 323     RESERVE_VIRTUAL_5
 324 /**
 325  * @ingroup KDEMacros
 326  */
 327 #define RESERVE_VIRTUAL_7 \
 328     virtual void reservedVirtual7() {} \
 329     RESERVE_VIRTUAL_6
 330 /**
 331  * @ingroup KDEMacros
 332  */
 333 #define RESERVE_VIRTUAL_8 \
 334     virtual void reservedVirtual8() {} \
 335     RESERVE_VIRTUAL_7
 336 /**
 337  * @ingroup KDEMacros
 338  */
 339 #define RESERVE_VIRTUAL_9 \
 340     virtual void reservedVirtual9() {} \
 341     RESERVE_VIRTUAL_8
 342 #define RESERVE_VIRTUAL_10 \
 343     virtual void reservedVirtual10() {} \
 344     RESERVE_VIRTUAL_9
 345
 346 /**
 347  * @def KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION
 348  * @ingroup KDEMacros
 349  *
 350  * From Qt's global.h:
 351  * Compilers which follow outdated template instantiation rules
 352  * require a class to have a comparison operator to exist when
 353  * a QList of this type is instantiated. It's not actually
 354  * used in the list, though. Hence the dummy implementation.
 355  * Just in case other code relies on it we better trigger a warning
 356  * mandating a real implementation.
 357  *
 358  * In KDE we need this for classes which are exported in a shared
 359  * lib because some compilers need a full instantiated class then.
 360  *
 361  * @sa KDE_DUMMY_COMPARISON_OPERATOR
 362  * @sa KDE_DUMMY_QHASH_FUNCTION
 363  */
 364
 365 /**
 366  * @def KDE_DUMMY_COMPARISON_OPERATOR
 367  * @ingroup KDEMacros
 368  *
 369  * The KDE_DUMMY_COMPARISON_OPERATOR defines a simple
 370  * compare operator for classes.
 371  *
 372  * @sa KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION
 373  * @sa KDE_DUMMY_QHASH_FUNCTION
 374  */
 375
 376 /**
 377  * @def KDE_DUMMY_QHASH_FUNCTION
 378  * @ingroup KDEMacros
 379  *
 380  * The KDE_DUMMY_QHASH_FUNCTION defines a simple
 381  * hash-function for classes.
 382  *
 383  * @sa KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION
 384  * @sa KDE_DUMMY_COMPARISON_OPERATOR
 385  */
 386
 387 #ifdef KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION
 388 # define KDE_DUMMY_COMPARISON_OPERATOR(C) \
 389     bool operator==(const C&) const { \
 390         qWarning(#C"::operator==(const "#C"&) was called"); \
 391         return false; \
 392     }
 393 # define KDE_DUMMY_QHASH_FUNCTION(C) \
 394     inline uint qHash(const C) { \
 395         qWarning("inline uint qHash(const "#C") was called"); \
 396         return 0; \
 397     }
 398 #else
 399 # define KDE_DUMMY_COMPARISON_OPERATOR(C)
 400 # define KDE_DUMMY_QHASH_FUNCTION(C)
 401 #endif
 402
 403 /**
 404  * @def KDE_BF_ENUM
 405  * @ingroup KDEMacros
 406  *
 407  * The KDE_BF_ENUM is used when storing an enum
 408  * in a bitfield, to ensure correct conversion
 409  * by all compilers.
 410  *
 411  * @sa KDE_CAST_BF_ENUM
 412  */
 413
 414 /**
 415  * @def KDE_CAST_BF_ENUM
 416  * @ingroup KDEMacros
 417  *
 418  * The KDE_CAST_BF_ENUM is used when retrieving an
 419  * enumfrom  a bitfield, to ensure correct conversion
 420  * by all compilers.
 421  *
 422  * @sa KDE_BF_ENUM
 423  */
 424
 425 #ifdef Q_CC_MSVC
 426 # define KDE_BF_ENUM(a) unsigned int
 427 # define KDE_CAST_BF_ENUM(a,b) static_cast<a>(b)
 428 #else
 429 # define KDE_BF_ENUM(a) a
 430 # define KDE_CAST_BF_ENUM(a,b) b
 431 #endif
 432
 433 /**
 434  * @def KDE_WEAK_SYMBOL
 435  * @ingroup KDEMacros
 436  *
 437  * The KDE_WEAK_SYMBOL macro can be used to tell the compiler that
 438  * a particular function should be a weak symbol (that e.g. may be overriden
 439  * in another library, -Bdirect will not bind this symbol directly)
 440  */
 441
 442 #ifdef __GNUC__
 443 #define KDE_WEAK_SYMBOL __attribute__((__weak__))
 444 #else
 445 #define KDE_WEAK_SYMBOL
 446 #endif
 447
 448
 449 /**
 450  * @def KDE_MUST_USE_RESULT
 451  * @ingroup KDEMacros
 452  *
 453  * The KDE_MUST_USE_RESULT macro can be used to tell the compiler that
 454  * a particular functions return value must be checked.
 455  */
 456
 457 #ifdef __GNUC__
 458 #define KDE_MUST_USE_RESULT __attribute__((__warn_unused_result__))
 459 #else
 460 #define KDE_MUST_USE_RESULT
 461 #endif
 462
 463
 464
 465 #endif /* _KDE_MACROS_H_ */