.. _attributes: ******************* Compiler attributes ******************* .. highlight:: c :: #include The macros in this section define compiler-agnostic versions of several common compiler attributes. .. function:: CORK_LIKELY(expression) CORK_UNLIKELY(expression) Indicate that the given Boolean *expression* is likely to be ``true`` or ``false``, respectively. The compiler can sometimes use this information to generate more efficient code. .. macro:: CORK_ATTR_CONST Declare a “constant” function. The return value of a constant function can only depend on its parameters. This is slightly more strict than a “pure” function (declared by :c:macro:`CORK_ATTR_PURE`); a constant function is not allowed to read from global variables, whereas a pure function is. .. note:: Note that the compiler won't verify that your function meets the requirements of a constant function. Instead, this attribute notifies the compiler of your intentions, which allows the compiler to assume more about your function when optimizing code that calls it. :: int square(int x) CORK_ATTR_CONST; .. macro:: CORK_ATTR_MALLOC Declare a function that returns a newly allocated pointer. The compiler can use this information to generate more accurate aliasing information, since it can infer that the result of the function cannot alias any other existing pointer. :: void *custom_malloc(size_t size) CORK_ATTR_MALLOC; .. macro:: CORK_ATTR_NOINLINE Declare that a function shouldn't be eligible for inlining. .. macro:: CORK_ATTR_PRINTF(format_index, args_index) Declare a function that takes in ``printf``\ -like parameters. *format_index* is the index (starting from 1) of the parameter that contains the ``printf`` format string. *args_index* is the index of the first parameter that contains the data to format. .. macro:: CORK_ATTR_PURE Declare a “pure” function. The return value of a pure function can only depend on its parameters, and on global variables. :: static int _next_id; int get_next_id(void) CORK_ATTR_PURE; .. macro:: CORK_ATTR_SENTINEL Declare a var-arg function whose last parameter must be a ``NULL`` sentinel value. When the compiler supports this attribute, it will check the actual parameters whenever this function is called, and ensure that the last parameter is a ``NULL``. .. macro:: CORK_ATTR_UNUSED Declare a entity that might not be used. This lets you keep ``-Wall`` activated in several cases where you're obligated to define something that you don't intend to use. :: CORK_ATTR_UNUSED static void unused_function(void) { CORK_ATTR_UNUSED int unused_value; } .. macro:: CORK_INITIALIZER(func_name) Declare a ``static`` function that will be automatically called at program startup. If there are multiple initializer functions linked into a program, there is no guarantee about the order in which the functions will be called. :: #include #include static cork_array(int) array; CORK_INITIALIZER(init_array) { cork_array_init(&array); }