include/parrot/compiler.h

   1 /* compiler.h
   2  *  Copyright (C) 2007-2008, The Perl Foundation.
   3  *  SVN Info
   4  *     $Id$
   5  *  Overview:
   6  *     defines compiler capabilities
   7  */
   8
   9 #ifndef PARROT_COMPILER_H_GUARD
  10 #define PARROT_COMPILER_H_GUARD
  11
  12 /*
  13  * This set of macros define capabilities that may or may not be available
  14  * for a given compiler.  They are based on GCC's __attribute__ functionality.
  15  */
  16
  17 /*
  18  * Microsoft provides two annotations mechanisms.  __declspec, which has been
  19  * around for a while, and Microsoft's standard source code annotation
  20  * language (SAL), introduced with Visual C++ 8.0.
  21  * See <http://msdn2.microsoft.com/en-us/library/ms235402(VS.80).aspx>,
  22  * <http://msdn2.microsoft.com/en-us/library/dabb5z75(VS.80).aspx>.
  23  */
  24 #if defined(_MSC_VER) && (_MSC_VER > 1300)
  25 #  define PARROT_HAS_SAL 1
  26 #  include <sal.h>
  27 #else
  28 #  define PARROT_HAS_SAL 0
  29 #endif
  30
  31 #ifdef HASATTRIBUTE_NEVER_WORKS
  32  #  error This attribute can never succeed.  Something has mis-sniffed your configuration.
  33 #endif
  34 #ifdef HASATTRIBUTE_DEPRECATED
  35 #  ifdef _MSC_VER
  36 #    define __attribute__deprecated__       __declspec(deprecated)
  37 #  else
  38 #    define __attribute__deprecated__       __attribute__((__deprecated__))
  39 #  endif
  40 #endif
  41 #ifdef HASATTRIBUTE_FORMAT
  42 #  define __attribute__format__(x, y, z)    __attribute__((__format__((x), (y), (z))))
  43 #endif
  44 #ifdef HASATTRIBUTE_MALLOC
  45 #  define __attribute__malloc__             __attribute__((__malloc__))
  46 #endif
  47 #ifdef HASATTRIBUTE_NONNULL
  48 #  define __attribute__nonnull__(a)         __attribute__((__nonnull__(a)))
  49 #endif
  50 #ifdef HASATTRIBUTE_NORETURN
  51 #  ifdef _MSC_VER
  52 #    define __attribute__noreturn__         __declspec(noreturn)
  53 #  else
  54 #    define __attribute__noreturn__         __attribute__((__noreturn__))
  55 #  endif
  56 #endif
  57 #ifdef HASATTRIBUTE_PURE
  58 #  define __attribute__pure__               __attribute__((__pure__))
  59 #endif
  60 #ifdef HASATTRIBUTE_CONST
  61 #  define __attribute__const__              __attribute__((__const__))
  62 #endif
  63 #ifdef HASATTRIBUTE_UNUSED
  64 #  define __attribute__unused__             __attribute__((__unused__))
  65 #endif
  66 #ifdef HASATTRIBUTE_WARN_UNUSED_RESULT
  67 #  define __attribute__warn_unused_result__ __attribute__((__warn_unused_result__))
  68 #endif
  69
  70 /* If we haven't defined the attributes yet, define them to blank. */
  71 #ifndef __attribute__deprecated__
  72 #  define __attribute__deprecated__
  73 #endif
  74 #ifndef __attribute__format__
  75 #  define __attribute__format__(x, y, z)
  76 #endif
  77 #ifndef __attribute__malloc__
  78 #  define __attribute__malloc__
  79 #endif
  80 #ifndef __attribute__nonnull__
  81 #  define __attribute__nonnull__(a)
  82 #endif
  83 #ifndef __attribute__noreturn__
  84 #  define __attribute__noreturn__
  85 #endif
  86 #ifndef __attribute__const__
  87 #  define __attribute__const__
  88 #endif
  89 #ifndef __attribute__pure__
  90 #  define __attribute__pure__
  91 #endif
  92 #ifndef __attribute__unused__
  93 #  define __attribute__unused__
  94 #endif
  95 #ifndef __attribute__warn_unused_result__
  96 #  define __attribute__warn_unused_result__
  97 #endif
  98
  99
 100 /* Shim arguments are arguments that must be included in your function,
 101  * but serve no purpose inside.  Mark them with the SHIM() macro so that
 102  * the compiler and/or lint know that it's OK it's unused.  Shim arguments
 103  * get "_unused" added to them so that you can't accidentally use them
 104  * without removing the shim designation.
 105  */
 106 #define SHIM(a) /*@unused@*/ /*@null@*/ a##_unused __attribute__unused__
 107
 108 /* UNUSED() is the old way we handled shim arguments Should still be
 109    used in cases where the argument should, at some point be used.
 110  */
 111 #define UNUSED(a) if (0) (void)(a);
 112
 113 #if PARROT_HAS_SAL
 114 #  define PARROT_CAN_RETURN_NULL      /*@null@*/ __maybenull
 115 #  define PARROT_CANNOT_RETURN_NULL   /*@notnull@*/ __notnull
 116 #else
 117 #  define PARROT_CAN_RETURN_NULL      /*@null@*/
 118 #  define PARROT_CANNOT_RETURN_NULL   /*@notnull@*/
 119 #endif
 120
 121 #define PARROT_DEPRECATED           __attribute__deprecated__
 122
 123 #define PARROT_IGNORABLE_RESULT
 124 #define PARROT_WARN_UNUSED_RESULT   __attribute__warn_unused_result__
 125
 126 #define PARROT_PURE_FUNCTION                __attribute__pure__  __attribute__warn_unused_result__
 127 #define PARROT_CONST_FUNCTION               __attribute__const__ __attribute__warn_unused_result__
 128 #define PARROT_DOES_NOT_RETURN              /*@noreturn@*/ __attribute__noreturn__
 129 #define PARROT_DOES_NOT_RETURN_WHEN_FALSE   /*@noreturnwhenfalse@*/
 130 #define PARROT_MALLOC                       /*@only@*/ __attribute__malloc__ __attribute__warn_unused_result__
 131
 132 /* Function argument instrumentation */
 133 /* For explanations of the annotations, see http://www.splint.org/manual/manual.html */
 134
 135 #if PARROT_HAS_SAL
 136 #  define NOTNULL(x)                  /*@notnull@*/ __notnull x
 137     /* The pointer passed may not be NULL */
 138
 139 #  define NULLOK(x)                   /*@null@*/ __maybenull x
 140     /* The pointer passed may be NULL */
 141
 142 #  define ARGIN(x)                    /*@in@*/ /*@notnull@*/ __in x
 143 #  define ARGIN_NULLOK(x)             /*@in@*/ /*@null@*/ __in_opt x
 144     /* The pointer target must be completely defined before being passed */
 145     /* to the function. */
 146
 147 #  define ARGOUT(x)                   /*@out@*/ /*@notnull@*/ __out x
 148 #  define ARGOUT_NULLOK(x)            /*@out@*/ /*@null@*/ __out_opt x
 149     /* The pointer target will be defined by the function */
 150
 151 #  define ARGMOD(x)                   /*@in@*/ /*@notnull@*/ __inout x
 152 #  define ARGMOD_NULLOK(x)            /*@in@*/ /*@null@*/ __inout_opt x
 153     /* The pointer target must be completely defined before being passed, */
 154     /* and MAY be modified by the function. */
 155
 156 #  define FUNC_MODIFIES(x)            /*@modifies x@*/
 157     /* Never applied by a human, only by the headerizer. */
 158
 159 #else
 160
 161 #  define NOTNULL(x)                  /*@notnull@*/ x
 162     /* The pointer passed may not be NULL */
 163
 164 #  define NULLOK(x)                   /*@null@*/ x
 165     /* The pointer passed may be NULL */
 166
 167 #  define ARGIN(x)                    /*@in@*/ /*@notnull@*/ x
 168 #  define ARGIN_NULLOK(x)             /*@in@*/ /*@null@*/ x
 169     /* The pointer target must be completely defined before being passed */
 170     /* to the function. */
 171
 172 #  define ARGOUT(x)                   /*@out@*/ /*@notnull@*/ x
 173 #  define ARGOUT_NULLOK(x)            /*@out@*/ /*@null@*/ x
 174     /* The pointer target will be defined by the function */
 175
 176 #  define ARGMOD(x)                   /*@in@*/ /*@notnull@*/ x
 177 #  define ARGMOD_NULLOK(x)            /*@in@*/ /*@null@*/ x
 178     /* The pointer target must be completely defined before being passed, */
 179     /* and MAY be modified by the function. */
 180
 181 #  define FUNC_MODIFIES(x)            /*@modifies x@*/
 182     /* Never applied by a human, only by the headerizer. */
 183
 184 #endif
 185
 186 #define ARGFREE(x)                          /*@only@*/ /*@out@*/ /*@null@*/ x
 187     /* From the Splint manual: The parameter to free() must reference */
 188     /* an unshared object.  Since the parameter is declared using "only", */
 189     /* the caller may not use the referenced object after the call, and */
 190     /* may not pass in a reference to a shared object.  There is nothing */
 191     /* special about malloc and free — their behavior can be described */
 192     /* entirely in terms of the provided annotations. */
 193
 194 #endif /* PARROT_COMPILER_H_GUARD */
 195
 196 /*
 197  * Local variables:
 198  *   c-file-style: "parrot"
 199  * End:
 200  * vim: expandtab shiftwidth=4:
 201  */