glib/gmacros.h

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19
  20 /*
  21  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GLib Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 /* This file must not include any other glib header file and must thus
  28  * not refer to variables from glibconfig.h
  29  */
  30
  31 #ifndef __G_MACROS_H__
  32 #define __G_MACROS_H__
  33
  34 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  35 #error "Only <glib.h> can be included directly."
  36 #endif
  37
  38 /* We include stddef.h to get the system's definition of NULL
  39  */
  40 #include <stddef.h>
  41
  42 /*
  43  * Note: Clang (but not clang-cl) defines __GNUC__ and __GNUC_MINOR__.
  44  * Both Clang 11.1 on current Arch Linux and Apple's Clang 12.0 define
  45  * __GNUC__ = 4 and __GNUC_MINOR__ = 2. So G_GNUC_CHECK_VERSION(4, 2) on
  46  * current Clang will be 1.
  47  */
  48 #ifdef __GNUC__
  49 #define G_GNUC_CHECK_VERSION(major, minor) \
  50     ((__GNUC__ > (major)) || \
  51      ((__GNUC__ == (major)) && \
  52       (__GNUC_MINOR__ >= (minor))))
  53 #else
  54 #define G_GNUC_CHECK_VERSION(major, minor) 0
  55 #endif
  56
  57 /* Here we provide G_GNUC_EXTENSION as an alias for __extension__,
  58  * where this is valid. This allows for warningless compilation of
  59  * "long long" types even in the presence of '-ansi -pedantic'.
  60  */
  61 #if G_GNUC_CHECK_VERSION(2, 8)
  62 #define G_GNUC_EXTENSION __extension__
  63 #else
  64 #define G_GNUC_EXTENSION
  65 #endif
  66
  67 /* Every compiler that we target supports inlining, but some of them may
  68  * complain about it if we don't say "__inline".  If we have C99, or if
  69  * we are using C++, then we can use "inline" directly.  Unfortunately
  70  * Visual Studio does not support __STDC_VERSION__, so we need to check
  71  * whether we are on Visual Studio 2013 or earlier to see that we need to
  72  * say "__inline" in C mode.
  73  * Otherwise, we say "__inline" to avoid the warning.
  74  */
  75 #define G_CAN_INLINE
  76 #ifndef __cplusplus
  77 # ifdef _MSC_VER
  78 #  if (_MSC_VER < 1900)
  79 #   define G_INLINE_DEFINE_NEEDED
  80 #  endif
  81 # elif !defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199900)
  82 #  define G_INLINE_DEFINE_NEEDED
  83 # endif
  84 #endif
  85
  86 #ifdef G_INLINE_DEFINE_NEEDED
  87 # undef inline
  88 # define inline __inline
  89 #endif
  90
  91 #undef G_INLINE_DEFINE_NEEDED
  92
  93 /**
  94  * G_INLINE_FUNC:
  95  *
  96  * This macro used to be used to conditionally define inline functions
  97  * in a compatible way before this feature was supported in all
  98  * compilers.  These days, GLib requires inlining support from the
  99  * compiler, so your GLib-using programs can safely assume that the
 100  * "inline" keyword works properly.
 101  *
 102  * Never use this macro anymore.  Just say "static inline".
 103  *
 104  * Deprecated: 2.48: Use "static inline" instead
 105  */
 106
 107 /* For historical reasons we need to continue to support those who
 108  * define G_IMPLEMENT_INLINES to mean "don't implement this here".
 109  */
 110 #ifdef G_IMPLEMENT_INLINES
 111 #  define G_INLINE_FUNC extern GLIB_DEPRECATED_MACRO_IN_2_48_FOR(static inline)
 112 #  undef  G_CAN_INLINE
 113 #else
 114 #  define G_INLINE_FUNC static inline GLIB_DEPRECATED_MACRO_IN_2_48_FOR(static inline)
 115 #endif /* G_IMPLEMENT_INLINES */
 116
 117 /*
 118  * Attribute support detection. Works on clang and GCC >= 5
 119  * https://clang.llvm.org/docs/LanguageExtensions.html#has-attribute
 120  * https://gcc.gnu.org/onlinedocs/cpp/_005f_005fhas_005fattribute.html
 121  */
 122
 123 #ifdef __has_attribute
 124 #define g_macro__has_attribute __has_attribute
 125 #else
 126
 127 /*
 128  * Fallback for GCC < 5 and other compilers not supporting __has_attribute.
 129  */
 130 #define g_macro__has_attribute(x) g_macro__has_attribute_##x
 131
 132 #define g_macro__has_attribute___pure__ G_GNUC_CHECK_VERSION (2, 96)
 133 #define g_macro__has_attribute___malloc__ G_GNUC_CHECK_VERSION (2, 96)
 134 #define g_macro__has_attribute___noinline__ G_GNUC_CHECK_VERSION (2, 96)
 135 #define g_macro__has_attribute___sentinel__ G_GNUC_CHECK_VERSION (4, 0)
 136 #define g_macro__has_attribute___alloc_size__ G_GNUC_CHECK_VERSION (4, 3)
 137 #define g_macro__has_attribute___format__ G_GNUC_CHECK_VERSION (2, 4)
 138 #define g_macro__has_attribute___format_arg__ G_GNUC_CHECK_VERSION (2, 4)
 139 #define g_macro__has_attribute___noreturn__ (G_GNUC_CHECK_VERSION (2, 8) || (0x5110 <= __SUNPRO_C))
 140 #define g_macro__has_attribute___const__ G_GNUC_CHECK_VERSION (2, 4)
 141 #define g_macro__has_attribute___unused__ G_GNUC_CHECK_VERSION (2, 4)
 142 #define g_macro__has_attribute___no_instrument_function__ G_GNUC_CHECK_VERSION (2, 4)
 143 #define g_macro__has_attribute_fallthrough G_GNUC_CHECK_VERSION (6, 0)
 144 #define g_macro__has_attribute___deprecated__ G_GNUC_CHECK_VERSION (3, 1)
 145 #define g_macro__has_attribute_may_alias G_GNUC_CHECK_VERSION (3, 3)
 146 #define g_macro__has_attribute_warn_unused_result G_GNUC_CHECK_VERSION (3, 4)
 147 #define g_macro__has_attribute_cleanup G_GNUC_CHECK_VERSION (3, 3)
 148
 149 #endif
 150
 151 /* Provide macros to feature the GCC function attribute.
 152  */
 153
 154 /**
 155  * G_GNUC_PURE:
 156  *
 157  * Expands to the GNU C `pure` function attribute if the compiler is gcc.
 158  * Declaring a function as `pure` enables better optimization of calls to
 159  * the function. A `pure` function has no effects except its return value
 160  * and the return value depends only on the parameters and/or global
 161  * variables.
 162  *
 163  * Place the attribute after the declaration, just before the semicolon.
 164  *
 165  * |[<!-- language="C" -->
 166  * gboolean g_type_check_value (const GValue *value) G_GNUC_PURE;
 167  * ]|
 168  *
 169  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-pure-function-attribute) for more details.
 170  */
 171
 172 /**
 173  * G_GNUC_MALLOC:
 174  *
 175  * Expands to the
 176  * [GNU C `malloc` function attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
 177  * if the compiler is gcc.
 178  * Declaring a function as `malloc` enables better optimization of the function,
 179  * but must only be done if the allocation behaviour of the function is fully
 180  * understood, otherwise miscompilation can result.
 181  *
 182  * A function can have the `malloc` attribute if it returns a pointer which is
 183  * guaranteed to not alias with any other pointer valid when the function
 184  * returns, and moreover no pointers to valid objects occur in any storage
 185  * addressed by the returned pointer.
 186  *
 187  * In practice, this means that `G_GNUC_MALLOC` can be used with any function
 188  * which returns unallocated or zeroed-out memory, but not with functions which
 189  * return initialised structures containing other pointers, or with functions
 190  * that reallocate memory. This definition changed in GLib 2.58 to match the
 191  * stricter definition introduced around GCC 5.
 192  *
 193  * Place the attribute after the declaration, just before the semicolon.
 194  *
 195  * |[<!-- language="C" -->
 196  * gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
 197  * ]|
 198  *
 199  * See the
 200  * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
 201  * for more details.
 202  *
 203  * Since: 2.6
 204  */
 205
 206 /**
 207  * G_GNUC_NO_INLINE:
 208  *
 209  * Expands to the GNU C `noinline` function attribute if the compiler is gcc.
 210  * If the compiler is not gcc, this macro expands to nothing.
 211  *
 212  * Declaring a function as `noinline` prevents the function from being
 213  * considered for inlining.
 214  *
 215  * This macro is provided for retro-compatibility and will be eventually
 216  * deprecated, but %G_NO_INLINE should be used instead.
 217  *
 218  * The attribute may be placed before the declaration or definition,
 219  * right before the `static` keyword.
 220  *
 221  * |[<!-- language="C" -->
 222  * G_GNUC_NO_INLINE
 223  * static int
 224  * do_not_inline_this (void)
 225  * {
 226  *   ...
 227  * }
 228  * ]|
 229  *
 230  * See the
 231  * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute)
 232  * for more details.
 233  *
 234  * See also: %G_NO_INLINE, %G_ALWAYS_INLINE.
 235  *
 236  * Since: 2.58
 237  */
 238
 239 #if g_macro__has_attribute(__pure__)
 240 #define G_GNUC_PURE __attribute__((__pure__))
 241 #else
 242 #define G_GNUC_PURE
 243 #endif
 244
 245 #if g_macro__has_attribute(__malloc__)
 246 #define G_GNUC_MALLOC __attribute__ ((__malloc__))
 247 #else
 248 #define G_GNUC_MALLOC
 249 #endif
 250
 251 #if g_macro__has_attribute(__noinline__)
 252 #define G_GNUC_NO_INLINE __attribute__ ((__noinline__)) \
 253   GLIB_AVAILABLE_MACRO_IN_2_58
 254 #else
 255 #define G_GNUC_NO_INLINE \
 256   GLIB_AVAILABLE_MACRO_IN_2_58
 257 #endif
 258
 259 /**
 260  * G_GNUC_NULL_TERMINATED:
 261  *
 262  * Expands to the GNU C `sentinel` function attribute if the compiler is gcc.
 263  * This function attribute only applies to variadic functions and instructs
 264  * the compiler to check that the argument list is terminated with an
 265  * explicit %NULL.
 266  *
 267  * Place the attribute after the declaration, just before the semicolon.
 268  *
 269  * |[<!-- language="C" -->
 270  * gchar *g_strconcat (const gchar *string1,
 271  *                     ...) G_GNUC_NULL_TERMINATED;
 272  * ]|
 273  *
 274  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-sentinel-function-attribute) for more details.
 275  *
 276  * Since: 2.8
 277  */
 278 #if g_macro__has_attribute(__sentinel__)
 279 #define G_GNUC_NULL_TERMINATED __attribute__((__sentinel__))
 280 #else
 281 #define G_GNUC_NULL_TERMINATED
 282 #endif
 283
 284 /*
 285  * Clang feature detection: http://clang.llvm.org/docs/LanguageExtensions.html
 286  * These are not available on GCC, but since the pre-processor doesn't do
 287  * operator short-circuiting, we can't use it in a statement or we'll get:
 288  *
 289  * error: missing binary operator before token "("
 290  *
 291  * So we define it to 0 to satisfy the pre-processor.
 292  */
 293
 294 #ifdef __has_feature
 295 #define g_macro__has_feature __has_feature
 296 #else
 297 #define g_macro__has_feature(x) 0
 298 #endif
 299
 300 #ifdef __has_builtin
 301 #define g_macro__has_builtin __has_builtin
 302 #else
 303 #define g_macro__has_builtin(x) 0
 304 #endif
 305
 306 #ifdef __has_extension
 307 #define g_macro__has_extension __has_extension
 308 #else
 309 #define g_macro__has_extension(x) 0
 310 #endif
 311
 312 /**
 313  * G_GNUC_ALLOC_SIZE:
 314  * @x: the index of the argument specifying the allocation size
 315  *
 316  * Expands to the GNU C `alloc_size` function attribute if the compiler
 317  * is a new enough gcc. This attribute tells the compiler that the
 318  * function returns a pointer to memory of a size that is specified
 319  * by the @xth function parameter.
 320  *
 321  * Place the attribute after the function declaration, just before the
 322  * semicolon.
 323  *
 324  * |[<!-- language="C" -->
 325  * gpointer g_malloc (gsize n_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE(1);
 326  * ]|
 327  *
 328  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
 329  *
 330  * Since: 2.18
 331  */
 332
 333 /**
 334  * G_GNUC_ALLOC_SIZE2:
 335  * @x: the index of the argument specifying one factor of the allocation size
 336  * @y: the index of the argument specifying the second factor of the allocation size
 337  *
 338  * Expands to the GNU C `alloc_size` function attribute if the compiler is a
 339  * new enough gcc. This attribute tells the compiler that the function returns
 340  * a pointer to memory of a size that is specified by the product of two
 341  * function parameters.
 342  *
 343  * Place the attribute after the function declaration, just before the
 344  * semicolon.
 345  *
 346  * |[<!-- language="C" -->
 347  * gpointer g_malloc_n (gsize n_blocks,
 348  *                      gsize n_block_bytes) G_GNUC_MALLOC G_GNUC_ALLOC_SIZE2(1, 2);
 349  * ]|
 350  *
 351  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-alloc_005fsize-function-attribute) for more details.
 352  *
 353  * Since: 2.18
 354  */
 355 #if g_macro__has_attribute(__alloc_size__)
 356 #define G_GNUC_ALLOC_SIZE(x) __attribute__((__alloc_size__(x)))
 357 #define G_GNUC_ALLOC_SIZE2(x,y) __attribute__((__alloc_size__(x,y)))
 358 #else
 359 #define G_GNUC_ALLOC_SIZE(x)
 360 #define G_GNUC_ALLOC_SIZE2(x,y)
 361 #endif
 362
 363 /**
 364  * G_GNUC_PRINTF:
 365  * @format_idx: the index of the argument corresponding to the
 366  *     format string (the arguments are numbered from 1)
 367  * @arg_idx: the index of the first of the format arguments, or 0 if
 368  *     there are no format arguments
 369  *
 370  * Expands to the GNU C `format` function attribute if the compiler is gcc.
 371  * This is used for declaring functions which take a variable number of
 372  * arguments, with the same syntax as `printf()`. It allows the compiler
 373  * to type-check the arguments passed to the function.
 374  *
 375  * Place the attribute after the function declaration, just before the
 376  * semicolon.
 377  *
 378  * See the
 379  * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
 380  * for more details.
 381  *
 382  * |[<!-- language="C" -->
 383  * gint g_snprintf (gchar  *string,
 384  *                  gulong       n,
 385  *                  gchar const *format,
 386  *                  ...) G_GNUC_PRINTF (3, 4);
 387  * ]|
 388  */
 389
 390 /**
 391  * G_GNUC_SCANF:
 392  * @format_idx: the index of the argument corresponding to
 393  *     the format string (the arguments are numbered from 1)
 394  * @arg_idx: the index of the first of the format arguments, or 0 if
 395  *     there are no format arguments
 396  *
 397  * Expands to the GNU C `format` function attribute if the compiler is gcc.
 398  * This is used for declaring functions which take a variable number of
 399  * arguments, with the same syntax as `scanf()`. It allows the compiler
 400  * to type-check the arguments passed to the function.
 401  *
 402  * |[<!-- language="C" -->
 403  * int my_scanf (MyStream *stream,
 404  *               const char *format,
 405  *               ...) G_GNUC_SCANF (2, 3);
 406  * int my_vscanf (MyStream *stream,
 407  *                const char *format,
 408  *                va_list ap) G_GNUC_SCANF (2, 0);
 409  * ]|
 410  *
 411  * See the
 412  * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
 413  * for details.
 414  */
 415
 416 /**
 417  * G_GNUC_STRFTIME:
 418  * @format_idx: the index of the argument corresponding to
 419  *     the format string (the arguments are numbered from 1)
 420  *
 421  * Expands to the GNU C `strftime` format function attribute if the compiler
 422  * is gcc. This is used for declaring functions which take a format argument
 423  * which is passed to `strftime()` or an API implementing its formats. It allows
 424  * the compiler check the format passed to the function.
 425  *
 426  * |[<!-- language="C" -->
 427  * gsize my_strftime (MyBuffer *buffer,
 428  *                    const char *format,
 429  *                    const struct tm *tm) G_GNUC_STRFTIME (2);
 430  * ]|
 431  *
 432  * See the
 433  * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
 434  * for details.
 435  *
 436  * Since: 2.60
 437  */
 438
 439 /**
 440  * G_GNUC_FORMAT:
 441  * @arg_idx: the index of the argument
 442  *
 443  * Expands to the GNU C `format_arg` function attribute if the compiler
 444  * is gcc. This function attribute specifies that a function takes a
 445  * format string for a `printf()`, `scanf()`, `strftime()` or `strfmon()` style
 446  * function and modifies it, so that the result can be passed to a `printf()`,
 447  * `scanf()`, `strftime()` or `strfmon()` style function (with the remaining
 448  * arguments to the format function the same as they would have been
 449  * for the unmodified string).
 450  *
 451  * Place the attribute after the function declaration, just before the
 452  * semicolon.
 453  *
 454  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-nonliteral-1) for more details.
 455  *
 456  * |[<!-- language="C" -->
 457  * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
 458  * ]|
 459  */
 460
 461 /**
 462  * G_GNUC_NORETURN:
 463  *
 464  * Expands to the GNU C `noreturn` function attribute if the compiler is gcc.
 465  * It is used for declaring functions which never return. It enables
 466  * optimization of the function, and avoids possible compiler warnings.
 467  *
 468  * Since 2.68, it is recommended that code uses %G_NORETURN instead of
 469  * %G_GNUC_NORETURN, as that works on more platforms and compilers (in
 470  * particular, MSVC and C++11) than %G_GNUC_NORETURN, which works with GCC and
 471  * Clang only. %G_GNUC_NORETURN continues to work, so has not been deprecated
 472  * yet.
 473  *
 474  * Place the attribute after the declaration, just before the semicolon.
 475  *
 476  * |[<!-- language="C" -->
 477  * void g_abort (void) G_GNUC_NORETURN;
 478  * ]|
 479  *
 480  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noreturn-function-attribute) for more details.
 481  */
 482
 483 /**
 484  * G_GNUC_CONST:
 485  *
 486  * Expands to the GNU C `const` function attribute if the compiler is gcc.
 487  * Declaring a function as `const` enables better optimization of calls to
 488  * the function. A `const` function doesn't examine any values except its
 489  * parameters, and has no effects except its return value.
 490  *
 491  * Place the attribute after the declaration, just before the semicolon.
 492  *
 493  * |[<!-- language="C" -->
 494  * gchar g_ascii_tolower (gchar c) G_GNUC_CONST;
 495  * ]|
 496  *
 497  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-const-function-attribute) for more details.
 498  *
 499  * A function that has pointer arguments and examines the data pointed to
 500  * must not be declared `const`. Likewise, a function that calls a non-`const`
 501  * function usually must not be `const`. It doesn't make sense for a `const`
 502  * function to return `void`.
 503  */
 504
 505 /**
 506  * G_GNUC_UNUSED:
 507  *
 508  * Expands to the GNU C `unused` function attribute if the compiler is gcc.
 509  * It is used for declaring functions and arguments which may never be used.
 510  * It avoids possible compiler warnings.
 511  *
 512  * For functions, place the attribute after the declaration, just before the
 513  * semicolon. For arguments, place the attribute at the beginning of the
 514  * argument declaration.
 515  *
 516  * |[<!-- language="C" -->
 517  * void my_unused_function (G_GNUC_UNUSED gint unused_argument,
 518  *                          gint other_argument) G_GNUC_UNUSED;
 519  * ]|
 520  *
 521  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-unused-function-attribute) for more details.
 522  */
 523
 524 /**
 525  * G_GNUC_NO_INSTRUMENT:
 526  *
 527  * Expands to the GNU C `no_instrument_function` function attribute if the
 528  * compiler is gcc. Functions with this attribute will not be instrumented
 529  * for profiling, when the compiler is called with the
 530  * `-finstrument-functions` option.
 531  *
 532  * Place the attribute after the declaration, just before the semicolon.
 533  *
 534  * |[<!-- language="C" -->
 535  * int do_uninteresting_things (void) G_GNUC_NO_INSTRUMENT;
 536  * ]|
 537  *
 538  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-no_005finstrument_005ffunction-function-attribute) for more details.
 539  */
 540
 541 #if g_macro__has_attribute(__format__)
 542
 543 #if !defined (__clang__) && G_GNUC_CHECK_VERSION (4, 4)
 544 #define G_GNUC_PRINTF( format_idx, arg_idx )    \
 545   __attribute__((__format__ (gnu_printf, format_idx, arg_idx)))
 546 #define G_GNUC_SCANF( format_idx, arg_idx )     \
 547   __attribute__((__format__ (gnu_scanf, format_idx, arg_idx)))
 548 #define G_GNUC_STRFTIME( format_idx )    \
 549   __attribute__((__format__ (gnu_strftime, format_idx, 0))) \
 550   GLIB_AVAILABLE_MACRO_IN_2_60
 551 #else
 552 #define G_GNUC_PRINTF( format_idx, arg_idx )    \
 553   __attribute__((__format__ (__printf__, format_idx, arg_idx)))
 554 #define G_GNUC_SCANF( format_idx, arg_idx )     \
 555   __attribute__((__format__ (__scanf__, format_idx, arg_idx)))
 556 #define G_GNUC_STRFTIME( format_idx )    \
 557   __attribute__((__format__ (__strftime__, format_idx, 0))) \
 558   GLIB_AVAILABLE_MACRO_IN_2_60
 559 #endif
 560
 561 #else
 562
 563 #define G_GNUC_PRINTF( format_idx, arg_idx )
 564 #define G_GNUC_SCANF( format_idx, arg_idx )
 565 #define G_GNUC_STRFTIME( format_idx ) \
 566   GLIB_AVAILABLE_MACRO_IN_2_60
 567
 568 #endif
 569
 570 #if g_macro__has_attribute(__format_arg__)
 571 #define G_GNUC_FORMAT(arg_idx) \
 572   __attribute__ ((__format_arg__ (arg_idx)))
 573 #else
 574 #define G_GNUC_FORMAT( arg_idx )
 575 #endif
 576
 577 #if g_macro__has_attribute(__noreturn__)
 578 #define G_GNUC_NORETURN \
 579   __attribute__ ((__noreturn__))
 580 #else
 581 /* NOTE: MSVC has __declspec(noreturn) but unlike GCC __attribute__,
 582  * __declspec can only be placed at the start of the function prototype
 583  * and not at the end, so we can't use it without breaking API.
 584  */
 585 #define G_GNUC_NORETURN
 586 #endif
 587
 588 #if g_macro__has_attribute(__const__)
 589 #define G_GNUC_CONST \
 590   __attribute__ ((__const__))
 591 #else
 592 #define G_GNUC_CONST
 593 #endif
 594
 595 #if g_macro__has_attribute(__unused__)
 596 #define G_GNUC_UNUSED \
 597   __attribute__ ((__unused__))
 598 #else
 599 #define G_GNUC_UNUSED
 600 #endif
 601
 602 #if g_macro__has_attribute(__no_instrument_function__)
 603 #define G_GNUC_NO_INSTRUMENT \
 604   __attribute__ ((__no_instrument_function__))
 605 #else
 606 #define G_GNUC_NO_INSTRUMENT
 607 #endif
 608
 609 /**
 610  * G_GNUC_FALLTHROUGH:
 611  *
 612  * Expands to the GNU C `fallthrough` statement attribute if the compiler supports it.
 613  * This allows declaring case statement to explicitly fall through in switch
 614  * statements. To enable this feature, use `-Wimplicit-fallthrough` during
 615  * compilation.
 616  *
 617  * Put the attribute right before the case statement you want to fall through
 618  * to.
 619  *
 620  * |[<!-- language="C" -->
 621  * switch (foo)
 622  *   {
 623  *     case 1:
 624  *       g_message ("it's 1");
 625  *       G_GNUC_FALLTHROUGH;
 626  *     case 2:
 627  *       g_message ("it's either 1 or 2");
 628  *       break;
 629  *   }
 630  * ]|
 631  *
 632  *
 633  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Statement-Attributes.html#index-fallthrough-statement-attribute) for more details.
 634  *
 635  * Since: 2.60
 636  */
 637 #if g_macro__has_attribute(fallthrough)
 638 #define G_GNUC_FALLTHROUGH __attribute__((fallthrough)) \
 639   GLIB_AVAILABLE_MACRO_IN_2_60
 640 #else
 641 #define G_GNUC_FALLTHROUGH \
 642   GLIB_AVAILABLE_MACRO_IN_2_60
 643 #endif
 644
 645 /**
 646  * G_GNUC_DEPRECATED:
 647  *
 648  * Expands to the GNU C `deprecated` attribute if the compiler is gcc.
 649  * It can be used to mark `typedef`s, variables and functions as deprecated.
 650  * When called with the `-Wdeprecated-declarations` option,
 651  * gcc will generate warnings when deprecated interfaces are used.
 652  *
 653  * Place the attribute after the declaration, just before the semicolon.
 654  *
 655  * |[<!-- language="C" -->
 656  * int my_mistake (void) G_GNUC_DEPRECATED;
 657  * ]|
 658  *
 659  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
 660  *
 661  * Since: 2.2
 662  */
 663 #if g_macro__has_attribute(__deprecated__)
 664 #define G_GNUC_DEPRECATED __attribute__((__deprecated__))
 665 #else
 666 #define G_GNUC_DEPRECATED
 667 #endif /* __GNUC__ */
 668
 669 /**
 670  * G_GNUC_DEPRECATED_FOR:
 671  * @f: the intended replacement for the deprecated symbol,
 672  *     such as the name of a function
 673  *
 674  * Like %G_GNUC_DEPRECATED, but names the intended replacement for the
 675  * deprecated symbol if the version of gcc in use is new enough to support
 676  * custom deprecation messages.
 677  *
 678  * Place the attribute after the declaration, just before the semicolon.
 679  *
 680  * |[<!-- language="C" -->
 681  * int my_mistake (void) G_GNUC_DEPRECATED_FOR(my_replacement);
 682  * ]|
 683  *
 684  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-deprecated-function-attribute) for more details.
 685  *
 686  * Note that if @f is a macro, it will be expanded in the warning message.
 687  * You can enclose it in quotes to prevent this. (The quotes will show up
 688  * in the warning, but it's better than showing the macro expansion.)
 689  *
 690  * Since: 2.26
 691  */
 692 #if G_GNUC_CHECK_VERSION(4, 5) || defined(__clang__)
 693 #define G_GNUC_DEPRECATED_FOR(f)                        \
 694   __attribute__((deprecated("Use " #f " instead")))     \
 695   GLIB_AVAILABLE_MACRO_IN_2_26
 696 #else
 697 #define G_GNUC_DEPRECATED_FOR(f)      G_GNUC_DEPRECATED \
 698   GLIB_AVAILABLE_MACRO_IN_2_26
 699 #endif /* __GNUC__ */
 700
 701 #ifdef __ICC
 702 #define G_GNUC_BEGIN_IGNORE_DEPRECATIONS                \
 703   _Pragma ("warning (push)")                            \
 704   _Pragma ("warning (disable:1478)")
 705 #define G_GNUC_END_IGNORE_DEPRECATIONS                  \
 706   _Pragma ("warning (pop)")
 707 #elif G_GNUC_CHECK_VERSION(4, 6)
 708 #define G_GNUC_BEGIN_IGNORE_DEPRECATIONS                \
 709   _Pragma ("GCC diagnostic push")                       \
 710   _Pragma ("GCC diagnostic ignored \"-Wdeprecated-declarations\"")
 711 #define G_GNUC_END_IGNORE_DEPRECATIONS                  \
 712   _Pragma ("GCC diagnostic pop")
 713 #elif defined (_MSC_VER) && (_MSC_VER >= 1500) && !defined (__clang__)
 714 #define G_GNUC_BEGIN_IGNORE_DEPRECATIONS                \
 715   __pragma (warning (push))  \
 716   __pragma (warning (disable : 4996))
 717 #define G_GNUC_END_IGNORE_DEPRECATIONS                  \
 718   __pragma (warning (pop))
 719 #elif defined (__clang__)
 720 #define G_GNUC_BEGIN_IGNORE_DEPRECATIONS \
 721   _Pragma("clang diagnostic push") \
 722   _Pragma("clang diagnostic ignored \"-Wdeprecated-declarations\"")
 723 #define G_GNUC_END_IGNORE_DEPRECATIONS \
 724   _Pragma("clang diagnostic pop")
 725 #else
 726 #define G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 727 #define G_GNUC_END_IGNORE_DEPRECATIONS
 728 #define GLIB_CANNOT_IGNORE_DEPRECATIONS
 729 #endif
 730
 731 /**
 732  * G_GNUC_MAY_ALIAS:
 733  *
 734  * Expands to the GNU C `may_alias` type attribute if the compiler is gcc.
 735  * Types with this attribute will not be subjected to type-based alias
 736  * analysis, but are assumed to alias with any other type, just like `char`.
 737  *
 738  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Type-Attributes.html#index-may_005falias-type-attribute) for details.
 739  *
 740  * Since: 2.14
 741  */
 742 #if g_macro__has_attribute(may_alias)
 743 #define G_GNUC_MAY_ALIAS __attribute__((may_alias))
 744 #else
 745 #define G_GNUC_MAY_ALIAS
 746 #endif
 747
 748 /**
 749  * G_GNUC_WARN_UNUSED_RESULT:
 750  *
 751  * Expands to the GNU C `warn_unused_result` function attribute if the compiler
 752  * is gcc. This function attribute makes the compiler emit a warning if the
 753  * result of a function call is ignored.
 754  *
 755  * Place the attribute after the declaration, just before the semicolon.
 756  *
 757  * |[<!-- language="C" -->
 758  * GList *g_list_append (GList *list,
 759  *                       gpointer data) G_GNUC_WARN_UNUSED_RESULT;
 760  * ]|
 761  *
 762  * See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-warn_005funused_005fresult-function-attribute) for more details.
 763  *
 764  * Since: 2.10
 765  */
 766 #if g_macro__has_attribute(warn_unused_result)
 767 #define G_GNUC_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
 768 #else
 769 #define G_GNUC_WARN_UNUSED_RESULT
 770 #endif /* __GNUC__ */
 771
 772 /**
 773  * G_GNUC_FUNCTION:
 774  *
 775  * Expands to "" on all modern compilers, and to  __FUNCTION__ on gcc
 776  * version 2.x. Don't use it.
 777  *
 778  * Deprecated: 2.16: Use G_STRFUNC() instead
 779  */
 780
 781 /**
 782  * G_GNUC_PRETTY_FUNCTION:
 783  *
 784  * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
 785  * on gcc version 2.x. Don't use it.
 786  *
 787  * Deprecated: 2.16: Use G_STRFUNC() instead
 788  */
 789
 790 /* Wrap the gcc __PRETTY_FUNCTION__ and __FUNCTION__ variables with
 791  * macros, so we can refer to them as strings unconditionally.
 792  * usage not-recommended since gcc-3.0
 793  *
 794  * Mark them as deprecated since 2.26, since that’s when version macros were
 795  * introduced.
 796  */
 797 #if defined (__GNUC__) && (__GNUC__ < 3)
 798 #define G_GNUC_FUNCTION         __FUNCTION__ GLIB_DEPRECATED_MACRO_IN_2_26_FOR(G_STRFUNC)
 799 #define G_GNUC_PRETTY_FUNCTION  __PRETTY_FUNCTION__ GLIB_DEPRECATED_MACRO_IN_2_26_FOR(G_STRFUNC)
 800 #else   /* !__GNUC__ */
 801 #define G_GNUC_FUNCTION         "" GLIB_DEPRECATED_MACRO_IN_2_26_FOR(G_STRFUNC)
 802 #define G_GNUC_PRETTY_FUNCTION  "" GLIB_DEPRECATED_MACRO_IN_2_26_FOR(G_STRFUNC)
 803 #endif  /* !__GNUC__ */
 804
 805 #if g_macro__has_feature(attribute_analyzer_noreturn) && defined(__clang_analyzer__)
 806 #define G_ANALYZER_ANALYZING 1
 807 #define G_ANALYZER_NORETURN __attribute__((analyzer_noreturn))
 808 #elif defined(__COVERITY__)
 809 #define G_ANALYZER_ANALYZING 1
 810 #define G_ANALYZER_NORETURN __attribute__((noreturn))
 811 #else
 812 #define G_ANALYZER_ANALYZING 0
 813 #define G_ANALYZER_NORETURN
 814 #endif
 815
 816 #define G_STRINGIFY(macro_or_string)    G_STRINGIFY_ARG (macro_or_string)
 817 #define G_STRINGIFY_ARG(contents)       #contents
 818
 819 #ifndef __GI_SCANNER__ /* The static assert macro really confuses the introspection parser */
 820 #define G_PASTE_ARGS(identifier1,identifier2) identifier1 ## identifier2
 821 #define G_PASTE(identifier1,identifier2)      G_PASTE_ARGS (identifier1, identifier2)
 822 #if !defined(__cplusplus) && defined(__STDC_VERSION__) && \
 823     (__STDC_VERSION__ >= 201112L || g_macro__has_feature(c_static_assert) || g_macro__has_extension(c_static_assert))
 824 #define G_STATIC_ASSERT(expr) _Static_assert (expr, "Expression evaluates to false")
 825 #elif (defined(__cplusplus) && __cplusplus >= 201103L) || \
 826       (defined(__cplusplus) && defined (_MSC_VER) && (_MSC_VER >= 1600)) || \
 827       (defined (_MSC_VER) && (_MSC_VER >= 1800))
 828 #define G_STATIC_ASSERT(expr) static_assert (expr, "Expression evaluates to false")
 829 #else
 830 #ifdef __COUNTER__
 831 #define G_STATIC_ASSERT(expr) typedef char G_PASTE (_GStaticAssertCompileTimeAssertion_, __COUNTER__)[(expr) ? 1 : -1] G_GNUC_UNUSED
 832 #else
 833 #define G_STATIC_ASSERT(expr) typedef char G_PASTE (_GStaticAssertCompileTimeAssertion_, __LINE__)[(expr) ? 1 : -1] G_GNUC_UNUSED
 834 #endif
 835 #endif /* __STDC_VERSION__ */
 836 #define G_STATIC_ASSERT_EXPR(expr) ((void) sizeof (char[(expr) ? 1 : -1]))
 837 #endif /* !__GI_SCANNER__ */
 838
 839 /* Provide a string identifying the current code position */
 840 #if defined(__GNUC__) && (__GNUC__ < 3) && !defined(__cplusplus)
 841 #define G_STRLOC        __FILE__ ":" G_STRINGIFY (__LINE__) ":" __PRETTY_FUNCTION__ "()"
 842 #else
 843 #define G_STRLOC        __FILE__ ":" G_STRINGIFY (__LINE__)
 844 #endif
 845
 846 /* Provide a string identifying the current function, non-concatenatable */
 847 #if defined (__GNUC__) && defined (__cplusplus)
 848 #define G_STRFUNC     ((const char*) (__PRETTY_FUNCTION__))
 849 #elif defined (__STDC_VERSION__) && __STDC_VERSION__ >= 199901L
 850 #define G_STRFUNC     ((const char*) (__func__))
 851 #elif defined (__GNUC__) || (defined(_MSC_VER) && (_MSC_VER > 1300))
 852 #define G_STRFUNC     ((const char*) (__FUNCTION__))
 853 #else
 854 #define G_STRFUNC     ((const char*) ("???"))
 855 #endif
 856
 857 /* Guard C code in headers, while including them from C++ */
 858 #ifdef  __cplusplus
 859 #define G_BEGIN_DECLS  extern "C" {
 860 #define G_END_DECLS    }
 861 #else
 862 #define G_BEGIN_DECLS
 863 #define G_END_DECLS
 864 #endif
 865
 866 /* Provide definitions for some commonly used macros.
 867  *  Some of them are only provided if they haven't already
 868  *  been defined. It is assumed that if they are already
 869  *  defined then the current definition is correct.
 870  */
 871 #ifndef NULL
 872 #  ifdef __cplusplus
 873 #  define NULL        (0L)
 874 #  else /* !__cplusplus */
 875 #  define NULL        ((void*) 0)
 876 #  endif /* !__cplusplus */
 877 #endif
 878
 879 #ifndef FALSE
 880 #define FALSE   (0)
 881 #endif
 882
 883 #ifndef TRUE
 884 #define TRUE    (!FALSE)
 885 #endif
 886
 887 #undef  MAX
 888 #define MAX(a, b)  (((a) > (b)) ? (a) : (b))
 889
 890 #undef  MIN
 891 #define MIN(a, b)  (((a) < (b)) ? (a) : (b))
 892
 893 #undef  ABS
 894 #define ABS(a)     (((a) < 0) ? -(a) : (a))
 895
 896 #undef  CLAMP
 897 #define CLAMP(x, low, high)  (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x)))
 898
 899 #define G_APPROX_VALUE(a, b, epsilon) \
 900   (((a) > (b) ? (a) - (b) : (b) - (a)) < (epsilon))
 901
 902 /* Count the number of elements in an array. The array must be defined
 903  * as such; using this with a dynamically allocated array will give
 904  * incorrect results.
 905  */
 906 #define G_N_ELEMENTS(arr)               (sizeof (arr) / sizeof ((arr)[0]))
 907
 908 /* Macros by analogy to GINT_TO_POINTER, GPOINTER_TO_INT
 909  */
 910 #define GPOINTER_TO_SIZE(p)     ((gsize) (p))
 911 #define GSIZE_TO_POINTER(s)     ((gpointer) (gsize) (s))
 912
 913 /* Provide convenience macros for handling structure
 914  * fields through their offsets.
 915  */
 916
 917 #if G_GNUC_CHECK_VERSION(4, 0) || defined(_MSC_VER)
 918 #define G_STRUCT_OFFSET(struct_type, member) \
 919       ((glong) offsetof (struct_type, member))
 920 #else
 921 #define G_STRUCT_OFFSET(struct_type, member)    \
 922       ((glong) ((guint8*) &((struct_type*) 0)->member))
 923 #endif
 924
 925 #define G_STRUCT_MEMBER_P(struct_p, struct_offset)   \
 926     ((gpointer) ((guint8*) (struct_p) + (glong) (struct_offset)))
 927 #define G_STRUCT_MEMBER(member_type, struct_p, struct_offset)   \
 928     (*(member_type*) G_STRUCT_MEMBER_P ((struct_p), (struct_offset)))
 929
 930 /* Provide simple macro statement wrappers:
 931  *   G_STMT_START { statements; } G_STMT_END;
 932  * This can be used as a single statement, like:
 933  *   if (x) G_STMT_START { ... } G_STMT_END; else ...
 934  * This intentionally does not use compiler extensions like GCC's '({...})' to
 935  * avoid portability issue or side effects when compiled with different compilers.
 936  * MSVC complains about "while(0)": C4127: "Conditional expression is constant",
 937  * so we use __pragma to avoid the warning since the use here is intentional.
 938  */
 939 #if !(defined (G_STMT_START) && defined (G_STMT_END))
 940 #define G_STMT_START  do
 941 #if defined (_MSC_VER) && (_MSC_VER >= 1500)
 942 #define G_STMT_END \
 943     __pragma(warning(push)) \
 944     __pragma(warning(disable:4127)) \
 945     while(0) \
 946     __pragma(warning(pop))
 947 #else
 948 #define G_STMT_END    while (0)
 949 #endif
 950 #endif
 951
 952 /* Provide G_ALIGNOF alignment macro.
 953  *
 954  * Note we cannot use the gcc __alignof__ operator here, as that returns the
 955  * preferred alignment rather than the minimal alignment. See
 956  * https://gitlab.gnome.org/GNOME/glib/merge_requests/538/diffs#note_390790.
 957  */
 958
 959 /**
 960  * G_ALIGNOF
 961  * @type: a type-name
 962  *
 963  * Return the minimal alignment required by the platform ABI for values of the given
 964  * type. The address of a variable or struct member of the given type must always be
 965  * a multiple of this alignment. For example, most platforms require int variables
 966  * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms.
 967  *
 968  * Note this is not necessarily the same as the value returned by GCC’s
 969  * `__alignof__` operator, which returns the preferred alignment for a type.
 970  * The preferred alignment may be a stricter alignment than the minimal
 971  * alignment.
 972  *
 973  * Since: 2.60
 974  */
 975 #if defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L && !defined(__cplusplus)
 976 #define G_ALIGNOF(type) _Alignof (type) \
 977   GLIB_AVAILABLE_MACRO_IN_2_60
 978 #else
 979 #define G_ALIGNOF(type) (G_STRUCT_OFFSET (struct { char a; type b; }, b)) \
 980   GLIB_AVAILABLE_MACRO_IN_2_60
 981 #endif
 982
 983 /**
 984  * G_CONST_RETURN:
 985  *
 986  * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
 987  * to nothing. By default, the macro expands to const. The macro
 988  * can be used in place of const for functions that return a value
 989  * that should not be modified. The purpose of this macro is to allow
 990  * us to turn on const for returned constant strings by default, while
 991  * allowing programmers who find that annoying to turn it off. This macro
 992  * should only be used for return values and for "out" parameters, it
 993  * doesn't make sense for "in" parameters.
 994  *
 995  * Deprecated: 2.30: API providers should replace all existing uses with
 996  * const and API consumers should adjust their code accordingly
 997  */
 998 #ifdef G_DISABLE_CONST_RETURNS
 999 #define G_CONST_RETURN GLIB_DEPRECATED_MACRO_IN_2_30_FOR(const)
1000 #else
1001 #define G_CONST_RETURN const GLIB_DEPRECATED_MACRO_IN_2_30_FOR(const)
1002 #endif
1003
1004 /**
1005  * G_NORETURN:
1006  *
1007  * Expands to the GNU C or MSVC `noreturn` function attribute depending on
1008  * the compiler. It is used for declaring functions which never return.
1009  * Enables optimization of the function, and avoids possible compiler warnings.
1010  *
1011  * Note that %G_NORETURN supersedes the previous %G_GNUC_NORETURN macro, which
1012  * will eventually be deprecated. %G_NORETURN supports more platforms.
1013  *
1014  * Place the attribute before the function declaration as follows:
1015  *
1016  * |[<!-- language="C" -->
1017  * G_NORETURN void g_abort (void);
1018  * ]|
1019  *
1020  * Since: 2.68
1021  */
1022 /* Note: We can’t annotate this with GLIB_AVAILABLE_MACRO_IN_2_68 because it’s
1023  * used within the GLib headers in function declarations which are always
1024  * evaluated when a header is included. This results in warnings in third party
1025  * code which includes glib.h, even if the third party code doesn’t use the new
1026  * macro itself. */
1027 #if g_macro__has_attribute(__noreturn__)
1028   /* For compatibility with G_NORETURN_FUNCPTR on clang, use
1029      __attribute__((__noreturn__)), not _Noreturn.  */
1030 # define G_NORETURN __attribute__ ((__noreturn__))
1031 #elif defined (_MSC_VER) && (1200 <= _MSC_VER)
1032   /* Use MSVC specific syntax.  */
1033 # define G_NORETURN __declspec (noreturn)
1034   /* Use ISO C++11 syntax when the compiler supports it.  */
1035 #elif defined (__cplusplus) && __cplusplus >= 201103
1036 # define G_NORETURN [[noreturn]]
1037   /* Use ISO C11 syntax when the compiler supports it.  */
1038 #elif defined (__STDC_VERSION__) && __STDC_VERSION__ >= 201112
1039 # define G_NORETURN _Noreturn
1040 #else
1041 # define G_NORETURN /* empty */
1042 #endif
1043
1044 /**
1045  * G_NORETURN_FUNCPTR:
1046  *
1047  * Expands to the GNU C or MSVC `noreturn` function attribute depending on
1048  * the compiler. It is used for declaring function pointers which never return.
1049  * Enables optimization of the function, and avoids possible compiler warnings.
1050  *
1051  * Place the attribute before the function declaration as follows:
1052  *
1053  * |[<!-- language="C" -->
1054  * G_NORETURN_FUNCPTR void (*funcptr) (void);
1055  * ]|
1056  *
1057  * Note that if the function is not a function pointer, you can simply use
1058  * the %G_NORETURN macro as follows:
1059  *
1060  * |[<!-- language="C" -->
1061  * G_NORETURN void g_abort (void);
1062  * ]|
1063  *
1064  * Since: 2.68
1065  */
1066 #if g_macro__has_attribute(__noreturn__)
1067 # define G_NORETURN_FUNCPTR __attribute__ ((__noreturn__))      \
1068   GLIB_AVAILABLE_MACRO_IN_2_68
1069 #else
1070 # define G_NORETURN_FUNCPTR /* empty */         \
1071   GLIB_AVAILABLE_MACRO_IN_2_68
1072 #endif
1073
1074 /**
1075  * G_ALWAYS_INLINE:
1076  *
1077  * Expands to the GNU C `always_inline` or MSVC `__forceinline` function
1078  * attribute depending on the compiler. It is used for declaring functions
1079  * as always inlined, ignoring the compiler optimization levels.
1080  *
1081  * The attribute may be placed before the declaration or definition,
1082  * right before the `static` keyword.
1083  *
1084  * |[<!-- language="C" -->
1085  * G_ALWAYS_INLINE
1086  * static int
1087  * do_inline_this (void)
1088  * {
1089  *   ...
1090  * }
1091  * ]|
1092  *
1093  * See the
1094  * [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-always_005finline-function-attribute)
1095  * and the
1096  * [MSVC documentation](https://docs.microsoft.com/en-us/visualstudio/misc/inline-inline-forceinline)
1097  *
1098  * Since: 2.74
1099  */
1100 /* Note: We can’t annotate this with GLIB_AVAILABLE_MACRO_IN_2_74 because it’s
1101  * used within the GLib headers in function declarations which are always
1102  * evaluated when a header is included. This results in warnings in third party
1103  * code which includes glib.h, even if the third party code doesn’t use the new
1104  * macro itself. */
1105 #if g_macro__has_attribute(__always_inline__)
1106 # if defined (__cplusplus) && __cplusplus >= 201103L
1107     /* Use ISO C++11 syntax when the compiler supports it. */
1108 #   define G_ALWAYS_INLINE [[gnu::always_inline]]
1109 # else
1110 #   define G_ALWAYS_INLINE __attribute__ ((__always_inline__))
1111 # endif
1112 #elif defined (_MSC_VER)
1113   /* Use MSVC specific syntax.  */
1114 # define G_ALWAYS_INLINE __forceinline
1115 #else
1116 # define G_ALWAYS_INLINE /* empty */
1117 #endif
1118
1119 /**
1120  * G_NO_INLINE:
1121  *
1122  * Expands to the GNU C or MSVC `noinline` function attribute
1123  * depending on the compiler. It is used for declaring functions
1124  * preventing from being considered for inlining.
1125  *
1126  * Note that %G_NO_INLINE supersedes the previous %G_GNUC_NO_INLINE
1127  * macro, which will eventually be deprecated.
1128  * %G_NO_INLINE supports more platforms.
1129  *
1130  * The attribute may be placed before the declaration or definition,
1131  * right before the `static` keyword.
1132  *
1133  * |[<!-- language="C" -->
1134  * G_NO_INLINE
1135  * static int
1136  * do_not_inline_this (void)
1137  * {
1138  *   ...
1139  * }
1140  * ]|
1141  *
1142  * Since: 2.74
1143  */
1144 /* Note: We can’t annotate this with GLIB_AVAILABLE_MACRO_IN_2_74 because it’s
1145  * used within the GLib headers in function declarations which are always
1146  * evaluated when a header is included. This results in warnings in third party
1147  * code which includes glib.h, even if the third party code doesn’t use the new
1148  * macro itself. */
1149 #if g_macro__has_attribute(__noinline__)
1150 # if defined (__cplusplus) && __cplusplus >= 201103L
1151     /* Use ISO C++11 syntax when the compiler supports it. */
1152 #   define G_NO_INLINE [[gnu::noinline]]
1153 # else
1154 #   define G_NO_INLINE __attribute__ ((__noinline__))
1155 # endif
1156 #elif defined (_MSC_VER) && (1200 <= _MSC_VER)
1157   /* Use MSVC specific syntax.  */
1158 # if defined (__cplusplus) && __cplusplus >= 201103L
1159     /* Use ISO C++11 syntax when the compiler supports it. */
1160 #   define G_NO_INLINE [[msvc::noinline]]
1161 # else
1162 #   define G_NO_INLINE __declspec (noinline)
1163 # endif
1164 #else
1165 # define G_NO_INLINE /* empty */
1166 #endif
1167
1168 /*
1169  * The G_LIKELY and G_UNLIKELY macros let the programmer give hints to
1170  * the compiler about the expected result of an expression. Some compilers
1171  * can use this information for optimizations.
1172  *
1173  * The _G_BOOLEAN_EXPR macro is intended to trigger a gcc warning when
1174  * putting assignments in g_return_if_fail ().
1175  */
1176 #if G_GNUC_CHECK_VERSION(2, 0) && defined(__OPTIMIZE__)
1177 #define _G_BOOLEAN_EXPR(expr)                   \
1178  G_GNUC_EXTENSION ({                            \
1179    int _g_boolean_var_;                         \
1180    if (expr)                                    \
1181       _g_boolean_var_ = 1;                      \
1182    else                                         \
1183       _g_boolean_var_ = 0;                      \
1184    _g_boolean_var_;                             \
1185 })
1186 #define G_LIKELY(expr) (__builtin_expect (_G_BOOLEAN_EXPR(expr), 1))
1187 #define G_UNLIKELY(expr) (__builtin_expect (_G_BOOLEAN_EXPR(expr), 0))
1188 #else
1189 #define G_LIKELY(expr) (expr)
1190 #define G_UNLIKELY(expr) (expr)
1191 #endif
1192
1193 /* GLIB_CANNOT_IGNORE_DEPRECATIONS is defined above for compilers that do not
1194  * have a way to temporarily suppress deprecation warnings. In these cases,
1195  * suppress the deprecated attribute altogether (otherwise a simple #include
1196  * <glib.h> will emit a barrage of warnings).
1197  */
1198 #if defined(GLIB_CANNOT_IGNORE_DEPRECATIONS)
1199 #define G_DEPRECATED
1200 #elif G_GNUC_CHECK_VERSION(3, 1) || defined(__clang__)
1201 #define G_DEPRECATED __attribute__((__deprecated__))
1202 #elif defined(_MSC_VER) && (_MSC_VER >= 1300)
1203 #define G_DEPRECATED __declspec(deprecated)
1204 #else
1205 #define G_DEPRECATED
1206 #endif
1207
1208 #if defined(GLIB_CANNOT_IGNORE_DEPRECATIONS)
1209 #define G_DEPRECATED_FOR(f) G_DEPRECATED
1210 #elif G_GNUC_CHECK_VERSION(4, 5) || defined(__clang__)
1211 #define G_DEPRECATED_FOR(f) __attribute__((__deprecated__("Use '" #f "' instead")))
1212 #elif defined(_MSC_FULL_VER) && (_MSC_FULL_VER > 140050320)
1213 #define G_DEPRECATED_FOR(f) __declspec(deprecated("is deprecated. Use '" #f "' instead"))
1214 #else
1215 #define G_DEPRECATED_FOR(f) G_DEPRECATED
1216 #endif
1217
1218 #if G_GNUC_CHECK_VERSION(4, 5) || defined(__clang__)
1219 #define G_UNAVAILABLE(maj,min) __attribute__((deprecated("Not available before " #maj "." #min)))
1220 #elif defined(_MSC_FULL_VER) && (_MSC_FULL_VER > 140050320)
1221 #define G_UNAVAILABLE(maj,min) __declspec(deprecated("is not available before " #maj "." #min))
1222 #else
1223 #define G_UNAVAILABLE(maj,min) G_DEPRECATED
1224 #endif
1225
1226 #ifndef _GLIB_EXTERN
1227 #define _GLIB_EXTERN extern
1228 #endif
1229
1230 /* These macros are used to mark deprecated symbols in GLib headers,
1231  * and thus have to be exposed in installed headers. But please
1232  * do *not* use them in other projects. Instead, use G_DEPRECATED
1233  * or define your own wrappers around it.
1234  */
1235
1236 #ifdef GLIB_DISABLE_DEPRECATION_WARNINGS
1237 #define GLIB_DEPRECATED _GLIB_EXTERN
1238 #define GLIB_DEPRECATED_FOR(f) _GLIB_EXTERN
1239 #define GLIB_UNAVAILABLE(maj,min) _GLIB_EXTERN
1240 #define GLIB_UNAVAILABLE_STATIC_INLINE(maj,min)
1241 #else
1242 #define GLIB_DEPRECATED G_DEPRECATED _GLIB_EXTERN
1243 #define GLIB_DEPRECATED_FOR(f) G_DEPRECATED_FOR(f) _GLIB_EXTERN
1244 #define GLIB_UNAVAILABLE(maj,min) G_UNAVAILABLE(maj,min) _GLIB_EXTERN
1245 #define GLIB_UNAVAILABLE_STATIC_INLINE(maj,min) G_UNAVAILABLE(maj,min)
1246 #endif
1247
1248 #if !defined(GLIB_DISABLE_DEPRECATION_WARNINGS) && \
1249     (G_GNUC_CHECK_VERSION(4, 6) ||                 \
1250      __clang_major__ > 3 || (__clang_major__ == 3 && __clang_minor__ >= 4))
1251 #define _GLIB_GNUC_DO_PRAGMA(x) _Pragma(G_STRINGIFY (x))
1252 #define GLIB_DEPRECATED_MACRO _GLIB_GNUC_DO_PRAGMA(GCC warning "Deprecated pre-processor symbol")
1253 #define GLIB_DEPRECATED_MACRO_FOR(f) \
1254   _GLIB_GNUC_DO_PRAGMA(GCC warning G_STRINGIFY (Deprecated pre-processor symbol: replace with #f))
1255 #define GLIB_UNAVAILABLE_MACRO(maj,min) \
1256   _GLIB_GNUC_DO_PRAGMA(GCC warning G_STRINGIFY (Not available before maj.min))
1257 #else
1258 #define GLIB_DEPRECATED_MACRO
1259 #define GLIB_DEPRECATED_MACRO_FOR(f)
1260 #define GLIB_UNAVAILABLE_MACRO(maj,min)
1261 #endif
1262
1263 #if !defined(GLIB_DISABLE_DEPRECATION_WARNINGS) && \
1264     (G_GNUC_CHECK_VERSION(6, 1) ||                 \
1265      (defined (__clang_major__) && (__clang_major__ > 3 || (__clang_major__ == 3 && __clang_minor__ >= 0))))
1266 #define GLIB_DEPRECATED_ENUMERATOR G_DEPRECATED
1267 #define GLIB_DEPRECATED_ENUMERATOR_FOR(f) G_DEPRECATED_FOR(f)
1268 #define GLIB_UNAVAILABLE_ENUMERATOR(maj,min) G_UNAVAILABLE(maj,min)
1269 #else
1270 #define GLIB_DEPRECATED_ENUMERATOR
1271 #define GLIB_DEPRECATED_ENUMERATOR_FOR(f)
1272 #define GLIB_UNAVAILABLE_ENUMERATOR(maj,min)
1273 #endif
1274
1275 #if !defined(GLIB_DISABLE_DEPRECATION_WARNINGS) && \
1276     (G_GNUC_CHECK_VERSION(3, 1) ||                 \
1277      (defined (__clang_major__) && (__clang_major__ > 3 || (__clang_major__ == 3 && __clang_minor__ >= 0))))
1278 #define GLIB_DEPRECATED_TYPE G_DEPRECATED
1279 #define GLIB_DEPRECATED_TYPE_FOR(f) G_DEPRECATED_FOR(f)
1280 #define GLIB_UNAVAILABLE_TYPE(maj,min) G_UNAVAILABLE(maj,min)
1281 #else
1282 #define GLIB_DEPRECATED_TYPE
1283 #define GLIB_DEPRECATED_TYPE_FOR(f)
1284 #define GLIB_UNAVAILABLE_TYPE(maj,min)
1285 #endif
1286
1287 #ifndef __GI_SCANNER__
1288
1289 #if g_macro__has_attribute(cleanup)
1290
1291 /* these macros are private */
1292 #define _GLIB_AUTOPTR_FUNC_NAME(TypeName) glib_autoptr_cleanup_##TypeName
1293 #define _GLIB_AUTOPTR_CLEAR_FUNC_NAME(TypeName) glib_autoptr_clear_##TypeName
1294 #define _GLIB_AUTOPTR_TYPENAME(TypeName)  TypeName##_autoptr
1295 #define _GLIB_AUTOPTR_LIST_FUNC_NAME(TypeName) glib_listautoptr_cleanup_##TypeName
1296 #define _GLIB_AUTOPTR_LIST_TYPENAME(TypeName)  TypeName##_listautoptr
1297 #define _GLIB_AUTOPTR_SLIST_FUNC_NAME(TypeName) glib_slistautoptr_cleanup_##TypeName
1298 #define _GLIB_AUTOPTR_SLIST_TYPENAME(TypeName)  TypeName##_slistautoptr
1299 #define _GLIB_AUTOPTR_QUEUE_FUNC_NAME(TypeName) glib_queueautoptr_cleanup_##TypeName
1300 #define _GLIB_AUTOPTR_QUEUE_TYPENAME(TypeName)  TypeName##_queueautoptr
1301 #define _GLIB_AUTO_FUNC_NAME(TypeName)    glib_auto_cleanup_##TypeName
1302 #define _GLIB_CLEANUP(func)               __attribute__((cleanup(func)))
1303 #define _GLIB_DEFINE_AUTOPTR_CLEANUP_FUNCS(TypeName, ParentName, cleanup) \
1304   typedef TypeName *_GLIB_AUTOPTR_TYPENAME(TypeName);                                                           \
1305   typedef GList *_GLIB_AUTOPTR_LIST_TYPENAME(TypeName);                                                         \
1306   typedef GSList *_GLIB_AUTOPTR_SLIST_TYPENAME(TypeName);                                                       \
1307   typedef GQueue *_GLIB_AUTOPTR_QUEUE_TYPENAME(TypeName);                                                       \
1308   G_GNUC_BEGIN_IGNORE_DEPRECATIONS                                                                              \
1309   static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_CLEAR_FUNC_NAME(TypeName) (TypeName *_ptr)                     \
1310     { if (_ptr) (cleanup) ((ParentName *) _ptr); }                                                              \
1311   static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_FUNC_NAME(TypeName) (TypeName **_ptr)                          \
1312     { _GLIB_AUTOPTR_CLEAR_FUNC_NAME(TypeName) (*_ptr); }                                                        \
1313   static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_LIST_FUNC_NAME(TypeName) (GList **_l)                          \
1314     { g_list_free_full (*_l, (GDestroyNotify) (void(*)(void)) cleanup); }                                       \
1315   static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_SLIST_FUNC_NAME(TypeName) (GSList **_l)                        \
1316     { g_slist_free_full (*_l, (GDestroyNotify) (void(*)(void)) cleanup); }                                      \
1317   static G_GNUC_UNUSED inline void _GLIB_AUTOPTR_QUEUE_FUNC_NAME(TypeName) (GQueue **_q)                        \
1318     { if (*_q) g_queue_free_full (*_q, (GDestroyNotify) (void(*)(void)) cleanup); }                             \
1319   G_GNUC_END_IGNORE_DEPRECATIONS
1320 #define _GLIB_DEFINE_AUTOPTR_CHAINUP(ModuleObjName, ParentName) \
1321   _GLIB_DEFINE_AUTOPTR_CLEANUP_FUNCS(ModuleObjName, ParentName, _GLIB_AUTOPTR_CLEAR_FUNC_NAME(ParentName))
1322
1323
1324 /* these macros are API */
1325 #define G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func) \
1326   _GLIB_DEFINE_AUTOPTR_CLEANUP_FUNCS(TypeName, TypeName, func)
1327 #define G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func) \
1328   G_GNUC_BEGIN_IGNORE_DEPRECATIONS                                                                              \
1329   static G_GNUC_UNUSED inline void _GLIB_AUTO_FUNC_NAME(TypeName) (TypeName *_ptr) { (func) (_ptr); }                         \
1330   G_GNUC_END_IGNORE_DEPRECATIONS
1331 #define G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none) \
1332   G_GNUC_BEGIN_IGNORE_DEPRECATIONS                                                                              \
1333   static G_GNUC_UNUSED inline void _GLIB_AUTO_FUNC_NAME(TypeName) (TypeName *_ptr) { if (*_ptr != none) (func) (*_ptr); }     \
1334   G_GNUC_END_IGNORE_DEPRECATIONS
1335 #define g_autoptr(TypeName) _GLIB_CLEANUP(_GLIB_AUTOPTR_FUNC_NAME(TypeName)) _GLIB_AUTOPTR_TYPENAME(TypeName)
1336 #define g_autolist(TypeName) _GLIB_CLEANUP(_GLIB_AUTOPTR_LIST_FUNC_NAME(TypeName)) _GLIB_AUTOPTR_LIST_TYPENAME(TypeName)
1337 #define g_autoslist(TypeName) _GLIB_CLEANUP(_GLIB_AUTOPTR_SLIST_FUNC_NAME(TypeName)) _GLIB_AUTOPTR_SLIST_TYPENAME(TypeName)
1338 #define g_autoqueue(TypeName) _GLIB_CLEANUP(_GLIB_AUTOPTR_QUEUE_FUNC_NAME(TypeName)) _GLIB_AUTOPTR_QUEUE_TYPENAME(TypeName)
1339 #define g_auto(TypeName) _GLIB_CLEANUP(_GLIB_AUTO_FUNC_NAME(TypeName)) TypeName
1340 #define g_autofree _GLIB_CLEANUP(g_autoptr_cleanup_generic_gfree)
1341
1342 #else /* not GNU C */
1343 /* this (dummy) macro is private */
1344 #define _GLIB_DEFINE_AUTOPTR_CHAINUP(ModuleObjName, ParentName)
1345
1346 /* these (dummy) macros are API */
1347 #define G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func)
1348 #define G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func)
1349 #define G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none)
1350
1351 /* no declaration of g_auto() or g_autoptr() here */
1352 #endif /* __GNUC__ */
1353
1354 #else
1355
1356 #define _GLIB_DEFINE_AUTOPTR_CHAINUP(ModuleObjName, ParentName)
1357
1358 #define G_DEFINE_AUTOPTR_CLEANUP_FUNC(TypeName, func)
1359 #define G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(TypeName, func)
1360 #define G_DEFINE_AUTO_CLEANUP_FREE_FUNC(TypeName, func, none)
1361
1362 #endif /* __GI_SCANNER__ */
1363
1364 /**
1365  * G_SIZEOF_MEMBER:
1366  * @struct_type: a structure type, e.g. #GOutputVector
1367  * @member: a field in the structure, e.g. `size`
1368  *
1369  * Returns the size of @member in the struct definition without having a
1370  * declared instance of @struct_type.
1371  *
1372  * Returns: the size of @member in bytes.
1373  *
1374  * Since: 2.64
1375  */
1376 #define G_SIZEOF_MEMBER(struct_type, member) \
1377     GLIB_AVAILABLE_MACRO_IN_2_64 \
1378     sizeof (((struct_type *) 0)->member)
1379
1380 #endif /* __G_MACROS_H__ */