KDECore
KDE Macros
Defines | |
#define | K_GLOBAL_STATIC(TYPE, NAME) K_GLOBAL_STATIC_WITH_ARGS(TYPE, NAME, ()) |
#define | K_GLOBAL_STATIC_WITH_ARGS(TYPE, NAME, ARGS) |
#define | KDE_BF_ENUM(a) a |
#define | KDE_CAST_BF_ENUM(a, b) b |
#define | KDE_CONSTRUCTOR_DEPRECATED Q_DECL_CONSTRUCTOR_DEPRECATED |
#define | KDE_DUMMY_COMPARISON_OPERATOR(C) |
#define | KDE_DUMMY_QHASH_FUNCTION(C) |
#define | KDE_EXPORT |
#define | KDE_IMPORT |
#define | KDE_ISLIKELY(x) ( x ) |
#define | KDE_ISUNLIKELY(x) ( x ) |
#define | KDE_MUST_USE_RESULT |
#define | KDE_NO_EXPORT |
#define | KDE_PACKED |
#define | KDE_WEAK_SYMBOL |
#define | RESERVE_VIRTUAL_1 virtual void reservedVirtual1() {} |
#define | RESERVE_VIRTUAL_2 |
#define | RESERVE_VIRTUAL_3 |
#define | RESERVE_VIRTUAL_4 |
#define | RESERVE_VIRTUAL_5 |
#define | RESERVE_VIRTUAL_6 |
#define | RESERVE_VIRTUAL_7 |
#define | RESERVE_VIRTUAL_8 |
#define | RESERVE_VIRTUAL_9 |
Define Documentation
#define K_GLOBAL_STATIC | ( | TYPE, | |||
NAME | ) | K_GLOBAL_STATIC_WITH_ARGS(TYPE, NAME, ()) |
This macro makes it easy to use non-POD types as global statics.
The object is created on first use and creation is threadsafe.
The object is destructed on library unload or application exit. Be careful with calling other objects in the destructor of the class as you have to be sure that they (or objects they depend on) are not already destructed.
- Parameters:
-
TYPE The type of the global static object. Do not add a *. NAME The name of the function to get a pointer to the global static object.
If needed (If the destructor of the global object calls other functions that depend on other global statics (e.g. KConfig::sync) your destructor has to be called before those global statics are destroyed. A Qt post routine does that.) you can also install a post routine (qAddPostRoutine) to clean up the object using the destroy() method. If you registered a post routine and the object is destroyed because of a lib unload you have to call qRemovePostRoutine!
Example:
class A { public: ~A(); ... }; K_GLOBAL_STATIC(A, globalA) // The above creates a new globally static variable named 'globalA' which you // can use as a pointer to an instance of A. void doSomething() { // The first time you access globalA a new instance of A will be created automatically. A *a = globalA; ... } void doSomethingElse() { if (globalA.isDestroyed()) { return; } A *a = globalA; ... } void installPostRoutine() { // A post routine can be used to delete the object when QCoreApplication destructs, // not adding such a post routine will delete the object normally at program unload qAddPostRoutine(globalA.destroy); } A::~A() { // When you install a post routine you have to remove the post routine from the destructor of // the class used as global static! qRemovePostRoutine(globalA.destroy); }
A common case for the need of deletion on lib unload/app shutdown are Singleton classes. Here's an example how to do it:
class MySingletonPrivate; class EXPORT_MACRO MySingleton { friend class MySingletonPrivate; public: static MySingleton *self(); QString someFunction(); private: MySingleton(); ~MySingleton(); };
// This class will be instantiated and referenced as a singleton in this example class MySingletonPrivate { public: QString foo; MySingleton instance; }; K_GLOBAL_STATIC(MySingletonPrivate, mySingletonPrivate) MySingleton *MySingleton::self() { // returns the singleton; automatically creates a new instance if that has not happened yet. return &mySingletonPrivate->instance; } QString MySingleton::someFunction() { // Refencing the singleton directly is possible for your convenience return mySingletonPrivate->foo; }
Instead of the above you can use also the following pattern (ignore the name of the namespace):
namespace MySingleton { EXPORT_MACRO QString someFunction(); }
class MySingletonPrivate { public: QString foo; }; K_GLOBAL_STATIC(MySingletonPrivate, mySingletonPrivate) QString MySingleton::someFunction() { return mySingletonPrivate->foo; }
Now code that wants to call someFunction() doesn't have to do
MySingleton::self()->someFunction();
MySingleton::someFunction();
#define K_GLOBAL_STATIC_WITH_ARGS | ( | TYPE, | |||
NAME, | |||||
ARGS | ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This is the same as K_GLOBAL_STATIC, but can take arguments that are passed to the object's constructor.
- Parameters:
-
TYPE The type of the global static object. Do not add a *. NAME The name of the function to get a pointer to the global static object. ARGS the list of arguments, between brackets
class A { public: A(const char *s, int i); ... }; K_GLOBAL_STATIC_WITH_ARG(A, globalA, ("foo", 0)) // The above creates a new globally static variable named 'globalA' which you // can use as a pointer to an instance of A. void doSomething() { // The first time you access globalA a new instance of A will be created automatically. A *a = globalA; ... }
#define KDE_BF_ENUM | ( | a | ) | a |
The KDE_BF_ENUM is used when storing an enum in a bitfield, to ensure correct conversion by all compilers.
- See also:
- KDE_CAST_BF_ENUM
Definition at line 429 of file kdemacros.h.cmake.
#define KDE_CAST_BF_ENUM | ( | a, | |||
b | ) | b |
The KDE_CAST_BF_ENUM is used when retrieving an enumfrom a bitfield, to ensure correct conversion by all compilers.
- See also:
- KDE_BF_ENUM
Definition at line 430 of file kdemacros.h.cmake.
#define KDE_CONSTRUCTOR_DEPRECATED Q_DECL_CONSTRUCTOR_DEPRECATED |
The KDE_CONSTRUCTOR_DEPRECATED macro can be used to trigger compile-time warnings with newer compilers when deprecated constructors are used.
For non-inline constructors, the macro gets inserted at front of the constructor declaration, right before the return type:
KDE_CONSTRUCTOR_DEPRECATED classA();
For constructors which are implemented inline, the KDE_CONSTRUCTOR_DEPRECATED macro is inserted at the front, but after the "inline" keyword:
KDE_CONSTRUCTOR_DEPRECATED classA() { .. }
- Note:
- Do not forget that inlined constructors are not allowed in public headers for KDE.
Definition at line 207 of file kdemacros.h.cmake.
#define KDE_DUMMY_COMPARISON_OPERATOR | ( | C | ) |
The KDE_DUMMY_COMPARISON_OPERATOR defines a simple compare operator for classes.
- See also:
- KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION
Definition at line 399 of file kdemacros.h.cmake.
#define KDE_DUMMY_QHASH_FUNCTION | ( | C | ) |
The KDE_DUMMY_QHASH_FUNCTION defines a simple hash-function for classes.
- See also:
- KDE_FULL_TEMPLATE_EXPORT_INSTANTIATION
Definition at line 400 of file kdemacros.h.cmake.
#define KDE_EXPORT |
The KDE_EXPORT macro marks the symbol of the given variable to be visible, so it can be used from outside the resulting library.
int KDE_NO_EXPORT foo; int KDE_EXPORT bar;
- See also:
- KDE_NO_EXPORT
Definition at line 82 of file kdemacros.h.cmake.
#define KDE_IMPORT |
Definition at line 83 of file kdemacros.h.cmake.
#define KDE_ISLIKELY | ( | x | ) | ( x ) |
The KDE_ISLIKELY macro tags a boolean expression as likely to evaluate to true
.
When used in an if ( )
statement, it gives a hint to the compiler that the following codeblock is likely to get executed. Providing this information helps the compiler to optimize the code for better performance. Using the macro has an insignificant code size or runtime memory footprint impact. The code semantics is not affected.
Example:
if ( KDE_ISLIKELY( testsomething() ) ) abort(); // assume its likely that the application aborts
- Note:
- Providing wrong information ( like marking a condition that almost never passes as 'likely' ) will cause a significant runtime slowdown. Therefore only use it for cases where you can be sure about the odds of the expression to pass in all cases ( independent from e.g. user configuration ).
Do NOT use ( !KDE_ISLIKELY(foo) ) as an replacement for KDE_ISUNLIKELY() !
- See also:
- KDE_ISUNLIKELY
Definition at line 275 of file kdemacros.h.cmake.
#define KDE_ISUNLIKELY | ( | x | ) | ( x ) |
The KDE_ISUNLIKELY macro tags a boolean expression as likely to evaluate to false
.
When used in an if ( )
statement, it gives a hint to the compiler that the following codeblock is unlikely to get executed. Providing this information helps the compiler to optimize the code for better performance. Using the macro has an insignificant code size or runtime memory footprint impact. The code semantics is not affected.
Example:
if ( KDE_ISUNLIKELY( testsomething() ) ) abort(); // assume its unlikely that the application aborts
- Note:
- Providing wrong information ( like marking a condition that almost never passes as 'unlikely' ) will cause a significant runtime slowdown. Therefore only use it for cases where you can be sure about the odds of the expression to pass in all cases ( independent from e.g. user configuration ).
Do NOT use ( !KDE_ISUNLIKELY(foo) ) as an replacement for KDE_ISLIKELY() !
- See also:
- KDE_ISLIKELY
Definition at line 276 of file kdemacros.h.cmake.
#define KDE_MUST_USE_RESULT |
The KDE_MUST_USE_RESULT macro can be used to tell the compiler that a particular functions return value must be checked.
Definition at line 460 of file kdemacros.h.cmake.
#define KDE_NO_EXPORT |
The KDE_NO_EXPORT macro marks the symbol of the given variable to be hidden.
A hidden symbol is stripped during the linking step, so it can't be used from outside the resulting library, which is similar to static. However, static limits the visibility to the current compilation unit. Hidden symbols can still be used in multiple compilation units.
int KDE_NO_EXPORT foo; int KDE_EXPORT bar;
- See also:
- KDE_EXPORT
Definition at line 81 of file kdemacros.h.cmake.
#define KDE_PACKED |
The KDE_PACKED macro can be used to hint the compiler that a particular structure or class should not contain unnecessary paddings.
Definition at line 97 of file kdemacros.h.cmake.
#define KDE_WEAK_SYMBOL |
The KDE_WEAK_SYMBOL macro can be used to tell the compiler that a particular function should be a weak symbol (that e.g.
may be overriden in another library, -Bdirect will not bind this symbol directly)
Definition at line 445 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_1 virtual void reservedVirtual1() {} |
This macro, and it's friends going up to 10 reserve a fixed number of virtual functions in a class.
Because adding virtual functions to a class changes the size of the vtable, adding virtual functions to a class breaks binary compatibility. However, by using this macro, and decrementing it as new virtual methods are added, binary compatibility can still be preserved.
- Note:
- The added functions must be added to the header at the same location as the macro; changing the order of virtual functions in a header is also binary incompatible as it breaks the layout of the vtable.
Definition at line 292 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_2 |
Value:
virtual void reservedVirtual2() {} \ RESERVE_VIRTUAL_1
Definition at line 297 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_3 |
Value:
virtual void reservedVirtual3() {} \ RESERVE_VIRTUAL_2
Definition at line 303 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_4 |
Value:
virtual void reservedVirtual4() {} \ RESERVE_VIRTUAL_3
Definition at line 309 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_5 |
Value:
virtual void reservedVirtual5() {} \ RESERVE_VIRTUAL_4
Definition at line 315 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_6 |
Value:
virtual void reservedVirtual6() {} \ RESERVE_VIRTUAL_5
Definition at line 321 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_7 |
Value:
virtual void reservedVirtual7() {} \ RESERVE_VIRTUAL_6
Definition at line 327 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_8 |
Value:
virtual void reservedVirtual8() {} \ RESERVE_VIRTUAL_7
Definition at line 333 of file kdemacros.h.cmake.
#define RESERVE_VIRTUAL_9 |
Value:
virtual void reservedVirtual9() {} \ RESERVE_VIRTUAL_8
Definition at line 339 of file kdemacros.h.cmake.