xapian-core/include/xapian/attributes.h

   1 /** @file attributes.h
   2  * @brief Compiler attribute macros
   3  */
   4 // Copyright (C) 2012,2013,2014,2015,2017 Olly Betts
   5 //
   6 // This program is free software; you can redistribute it and/or modify
   7 // it under the terms of the GNU General Public License as published by
   8 // the Free Software Foundation; either version 2 of the License, or
   9 // (at your option) any later version.
  10 //
  11 // This program 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
  14 // GNU General Public License for more details.
  15 //
  16 // You should have received a copy of the GNU General Public License
  17 // along with this program; if not, write to the Free Software
  18 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19
  20 #ifndef XAPIAN_INCLUDED_ATTRIBUTES_H
  21 #define XAPIAN_INCLUDED_ATTRIBUTES_H
  22
  23 #if __cplusplus >= 201103L || (defined _MSC_VER && _MSC_VER >= 1900)
  24 // C++11 has noexcept(true) for marking a function which shouldn't throw.
  25 //
  26 // You need a C++11 compiler to build Xapian, but we still support using a
  27 // non-C++11 compiler to build code which uses Xapian (one reason is that
  28 // currently you need an option to enable C++11 support for most
  29 // compilers).  Once we require C++11 for using Xapian, XAPIAN_NOTHROW can go
  30 // away.
  31 //
  32 // We can't simply just add noexcept(true) via XAPIAN_NOTHROW as noexcept has
  33 // to be added to all declarations, whereas the GCC attribute can't be used on
  34 // a function definition.  So for now, XAPIAN_NOTHROW() goes around
  35 // declarations, and XAPIAN_NOEXCEPT needs to be explicitly added to
  36 // definitions.
  37 # define XAPIAN_NOEXCEPT noexcept(true)
  38 #else
  39 # define XAPIAN_NOEXCEPT
  40 #endif
  41
  42 #ifdef __GNUC__
  43
  44 // __attribute__((__const__)) is available at least as far back as GCC 2.95.
  45 # define XAPIAN_CONST_FUNCTION __attribute__((__const__))
  46 // __attribute__((__pure__)) is available from GCC 2.96 onwards.
  47 # define XAPIAN_PURE_FUNCTION __attribute__((__pure__))
  48 // __attribute__((__nothrow__)) is available from GCC 3.3 onwards.
  49 # if __GNUC__ >= 4 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 3)
  50 #  define XAPIAN_NOTHROW(D) D XAPIAN_NOEXCEPT __attribute__((__nothrow__))
  51 # endif
  52
  53 // We don't enable XAPIAN_NONNULL when building the library because that
  54 // results in warnings when we check the parameter really isn't NULL, and we
  55 // ought to still do that as (a) not all compilers support such annotations,
  56 // and (b) even those that do don't actually prevent you from passing NULL.
  57 # ifndef XAPIAN_LIB_BUILD
  58 // __attribute__((__nonnull__(a,b,c))) is available from GCC 3.3 onwards, but
  59 // seems to be buggy in GCC 4.8 so only enable it for versions after that.
  60 // It's also supported by clang, which we have to check for separately as
  61 // current versions pretend to be GCC 4.2.
  62 #  if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ > 8) || \
  63       defined __clang__
  64 #   define XAPIAN_NONNULL(LIST) __attribute__((__nonnull__ LIST))
  65 #  endif
  66 # endif
  67
  68 #else
  69
  70 /** A function which does not examine any values except its arguments and has
  71  *  no effects except its return value.
  72  *
  73  *  This means the compiler can perform CSE (common subexpression elimination)
  74  *  on calls to such a function with the same arguments, and also completely
  75  *  eliminate calls to this function when the return value isn't used.
  76  */
  77 # define XAPIAN_CONST_FUNCTION
  78
  79 /** Like XAPIAN_CONST_FUNCTION, but such a function can also examine global
  80  *  memory, perhaps via pointer or reference parameters.
  81  */
  82 # define XAPIAN_PURE_FUNCTION
  83
  84 #endif
  85
  86 #ifndef XAPIAN_NOTHROW
  87 /** A function or method which will never throw an exception. */
  88 # define XAPIAN_NOTHROW(D) D XAPIAN_NOEXCEPT
  89 #endif
  90
  91 #ifndef XAPIAN_NONNULL
  92 /** Annotate function parameters which should be non-NULL pointers.
  93  *
  94  *  If LIST isn't specified, all pointer parameters will be marked in this
  95  *  way (which is often sufficient):
  96  *
  97  *  int foo(const char* p) XAPIAN_NONNULL();
  98  *  int bar(char* p, const char* q) XAPIAN_NONNULL();
  99  *
 100  *  If there are other pointer parameters which can be NULL, then you need
 101  *  to specify a parenthesised list of the parameters to mark:
 102  *
 103  *  int foo(const char* p, int* maybenull) XAPIAN_NONNULL((1));
 104  *  int bar(char* p, void* maybenull, const char* q) XAPIAN_NONNULL((1,3));
 105  *
 106  *  NB In a non-class function, the first parameter is numbered 1, but in
 107  *  a non-static class method (which isn't a constructor) then the `this`
 108  *  pointer is implicitly counted as parameter 1, though this doesn't
 109  *  appear to be documented.  For confirmation see:
 110  *  https://gcc.gnu.org/bugzilla/show_bug.cgi?id=79961
 111  */
 112 # define XAPIAN_NONNULL(LIST)
 113 #endif
 114
 115 #endif // XAPIAN_INCLUDED_ATTRIBUTES_H