libguile/__scm.h

   1 /* classes: h_files */
   2
   3 #ifndef SCM___SCM_H
   4 #define SCM___SCM_H
   5
   6 /* Copyright (C) 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2006,
   7  *   2007, 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 3 of
  12  * the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful, but
  15  * WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  22  * 02110-1301 USA
  23  */
  24
  25 \f
  26
  27 /**********************************************************************
  28  This file is Guile's central public header.
  29
  30  When included by other files, this file should preceed any include
  31  other than __scm.h.
  32
  33  Under *NO* circumstances should new items be added to the global
  34  namespace (via adding #define, typedef, or similar to this file) with
  35  generic names.  This usually means that any new names should be
  36  prefixed by either SCM_ or GUILE_.  i.e. do *not* #define HAVE_FOO or
  37  SIZEOF_BAR.  See configure.in, gen-scmconfig.h.in, and
  38  gen-scmconfig.c for examples of how to properly handle this issue.
  39  The main documentation is in gen-scmconfig.c.
  40
  41  "What's the difference between _scm.h and __scm.h?"
  42
  43    _scm.h is not installed; it's only visible to the libguile sources
  44    themselves, and it includes config.h, the private config header.
  45
  46    __scm.h is installed, and is #included by <libguile.h>.  If both
  47    the client and libguile need some piece of information, and it
  48    doesn't fit well into the header file for any particular module, it
  49    should go in __scm.h.  __scm.h includes scmconfig.h, the public
  50    config header.
  51  **********************************************************************/
  52
  53 /* What did the configure script discover about the outside world?  */
  54 #include "libguile/scmconfig.h"
  55
  56 \f
  57
  58 /* {Compiler hints}
  59  *
  60  * The following macros are used to provide additional information for the
  61  * compiler, which may help to do better error checking and code
  62  * optimization.  A second benefit of these macros is, that they also provide
  63  * additional information to the developers.
  64  */
  65
  66 /* Return true (non-zero) if GCC version MAJ.MIN or later is being used
  67  * (macro taken from glibc.)  */
  68 #if defined __GNUC__ && defined __GNUC_MINOR__
  69 # define SCM_GNUC_PREREQ(maj, min) \
  70         ((__GNUC__ << 16) + __GNUC_MINOR__ >= ((maj) << 16) + (min))
  71 #else
  72 # define SCM_GNUC_PREREQ(maj, min) 0
  73 #endif
  74
  75 /* The macro SCM_NORETURN indicates that a function will never return.
  76  * Examples:
  77  *   1) int foo (char arg) SCM_NORETURN;
  78  */
  79 #ifdef __GNUC__
  80 #define SCM_NORETURN __attribute__ ((__noreturn__))
  81 #else
  82 #define SCM_NORETURN
  83 #endif
  84
  85 /* The macro SCM_UNUSED indicates that a function, function argument or
  86  * variable may potentially be unused.
  87  * Examples:
  88  *   1) static int unused_function (char arg) SCM_UNUSED;
  89  *   2) int foo (char unused_argument SCM_UNUSED);
  90  *   3) int unused_variable SCM_UNUSED;
  91  */
  92 #ifdef __GNUC__
  93 #define SCM_UNUSED __attribute__ ((unused))
  94 #else
  95 #define SCM_UNUSED
  96 #endif
  97
  98
  99 /* The SCM_EXPECT macros provide branch prediction hints to the compiler.  To
 100  * use only in places where the result of the expression under "normal"
 101  * circumstances is known.  */
 102 #if SCM_GNUC_PREREQ (3, 0)
 103 # define SCM_EXPECT    __builtin_expect
 104 #else
 105 # define SCM_EXPECT(_expr, _value) (_expr)
 106 #endif
 107
 108 #define SCM_LIKELY(_expr)    SCM_EXPECT ((_expr), 1)
 109 #define SCM_UNLIKELY(_expr)  SCM_EXPECT ((_expr), 0)
 110
 111 /* The SCM_INTERNAL macro makes it possible to explicitly declare a function
 112  * as having "internal" linkage.  However our current tack on this problem is
 113  * to use GCC 4's -fvisibility=hidden, making functions internal by default,
 114  * and then SCM_API marks them for export. */
 115 #define SCM_INTERNAL  extern
 116
 117 /* The SCM_DEPRECATED macro is used in declarations of deprecated functions
 118  * or variables.  Defining `SCM_BUILDING_DEPRECATED_CODE' allows deprecated
 119  * functions to be implemented in terms of deprecated functions, and allows
 120  * deprecated functions to be referred to by `scm_c_define_gsubr ()'.  */
 121 #if !defined (SCM_BUILDING_DEPRECATED_CODE) && SCM_GNUC_PREREQ (3, 0)
 122 # define SCM_DEPRECATED  SCM_API __attribute__ ((__deprecated__))
 123 #else
 124 # define SCM_DEPRECATED  SCM_API
 125 #endif
 126
 127 /* The SCM_ALIGNED macro, when defined, can be used to instruct the compiler
 128  * to honor the given alignment constraint.  */
 129 /* Sun Studio supports alignment since Sun Studio 12 */
 130 #if defined __GNUC__ || (defined( __SUNPRO_C ) && (__SUNPRO_C - 0 >= 0x590))
 131 # define SCM_ALIGNED(x)  __attribute__ ((aligned (x)))
 132 #elif defined __INTEL_COMPILER
 133 # define SCM_ALIGNED(x)  __declspec (align (x))
 134 #else
 135 /* Don't know how to align things.  */
 136 # undef SCM_ALIGNED
 137 #endif
 138
 139 /* The SCM_MALLOC macro can be used in function declarations to tell the
 140  * compiler that a function may be treated as if any non-NULL pointer it returns
 141  * cannot alias any other pointer valid when the function returns.  */
 142 #if SCM_GNUC_PREREQ (3, 0)
 143 # define SCM_MALLOC  __attribute__ ((__malloc__))
 144 #else
 145 # define SCM_MALLOC
 146 #endif
 147
 148 \f
 149
 150 /* SCM_API is a macro prepended to all function and data definitions
 151    which should be exported from libguile. */
 152
 153 #if defined BUILDING_LIBGUILE && defined HAVE_VISIBILITY
 154 # define SCM_API extern __attribute__((__visibility__("default")))
 155 #elif defined BUILDING_LIBGUILE && defined _MSC_VER
 156 # define SCM_API __declspec(dllexport) extern
 157 #elif defined _MSC_VER
 158 # define SCM_API __declspec(dllimport) extern
 159 #else
 160 # define SCM_API extern
 161 #endif
 162
 163 \f
 164
 165 /* We would like gnu89 extern inline semantics, not C99 extern inline
 166    semantics, so that we can be sure to avoid reifying definitions of
 167    inline functions in all compilation units, which is a possibility at
 168    low optimization levels, or if a user takes the address of an inline
 169    function.
 170
 171    Hence the `__gnu_inline__' attribute, in accordance with:
 172    http://gcc.gnu.org/gcc-4.3/porting_to.html .
 173
 174    With GCC 4.2, `__GNUC_STDC_INLINE__' is never defined (because C99 inline
 175    semantics are not supported), but a warning is issued in C99 mode if
 176    `__gnu_inline__' is not used.
 177
 178    Apple's GCC build >5400 (since Xcode 3.0) doesn't support GNU inline in
 179    C99 mode and doesn't define `__GNUC_STDC_INLINE__'.  Fall back to "static
 180    inline" in that case.  */
 181
 182 # if (defined __GNUC__) && (!(((defined __APPLE_CC__) && (__APPLE_CC__ > 5400)) && __STDC_VERSION__ >= 199901L))
 183 #  if (defined __GNUC_STDC_INLINE__) || (__GNUC__ == 4 && __GNUC_MINOR__ == 2)
 184 #   define SCM_C_EXTERN_INLINE                                  \
 185            extern __inline__ __attribute__ ((__gnu_inline__))
 186 #  else
 187 #   define SCM_C_EXTERN_INLINE extern __inline__
 188 #  endif
 189 # endif
 190
 191 /* SCM_INLINE is a macro prepended to all public inline function
 192    declarations.  Implementations of those functions should also be in
 193    the header file, prefixed by SCM_INLINE_IMPLEMENTATION, and protected
 194    by SCM_CAN_INLINE and a CPP define for the C file in question, like
 195    SCM_INLINE_C_INCLUDING_INLINE_H.  See inline.h for an example
 196    usage.  */
 197
 198 #if defined SCM_IMPLEMENT_INLINES
 199 /* Reifying functions to a file, whether or not inlining is available.  */
 200 # define SCM_CAN_INLINE 0
 201 # define SCM_INLINE SCM_API
 202 # define SCM_INLINE_IMPLEMENTATION
 203 #elif defined SCM_C_INLINE
 204 /* Declarations when inlining is available.  */
 205 # define SCM_CAN_INLINE 1
 206 # ifdef SCM_C_EXTERN_INLINE
 207 #  define SCM_INLINE SCM_C_EXTERN_INLINE
 208 # else
 209 /* Fall back to static inline if GNU "extern inline" is unavailable.  */
 210 #  define SCM_INLINE static SCM_C_INLINE
 211 # endif
 212 # define SCM_INLINE_IMPLEMENTATION SCM_INLINE
 213 #else
 214 /* Declarations when inlining is not available.  */
 215 # define SCM_CAN_INLINE 0
 216 # define SCM_INLINE SCM_API
 217 /* Don't define SCM_INLINE_IMPLEMENTATION; it should never be seen in
 218    this case.  */
 219 #endif
 220
 221 \f
 222
 223 /* {Debugging Options}
 224  *
 225  * These compile time options determine whether to include code that is only
 226  * useful for debugging guile itself or C level extensions to guile.  The
 227  * common prefix for all option macros of this kind is "SCM_DEBUG_".  It is
 228  * guaranteed that a macro named SCM_DEBUG_XXX is always defined (typically to
 229  * either 0 or 1), i. e. there is no need to test for the undefined case.
 230  * This allows to use these definitions comfortably within code, as in the
 231  * following example:
 232  *   #define FOO do { if (SCM_DEBUG_XXX) bar(); else baz(); } while (0)
 233  * Any sane compiler will remove the unused branch without any performance
 234  * penalty for the resulting code.
 235  *
 236  * Note:  Some SCM_DEBUG_XXX options are not settable at configure time.
 237  * To change the value of such options you will have to edit this header
 238  * file or give suitable options to make, like:
 239  *   make all CFLAGS="-DSCM_DEBUG_XXX=1 ..."
 240  */
 241
 242
 243 /* The value of SCM_DEBUG determines the default for most of the not yet
 244  * defined debugging options.  This allows, for example, to enable most of the
 245  * debugging options by simply defining SCM_DEBUG as 1.
 246  */
 247 #ifndef SCM_DEBUG
 248 #define SCM_DEBUG 0
 249 #endif
 250
 251 /* If SCM_DEBUG_CELL_ACCESSES is set to 1, cell accesses will perform
 252  * exhaustive parameter checking:  It will be verified that cell parameters
 253  * actually point to a valid heap cell.  Note:  If this option is enabled,
 254  * guile will run about ten times slower than normally.
 255  */
 256 #ifndef SCM_DEBUG_CELL_ACCESSES
 257 #define SCM_DEBUG_CELL_ACCESSES SCM_DEBUG
 258 #endif
 259
 260 /* If SCM_DEBUG_PAIR_ACCESSES is set to 1, accesses to cons cells will be
 261  * exhaustively checked.  Note:  If this option is enabled, guile will run
 262  * slower than normally.
 263  */
 264 #ifndef SCM_DEBUG_PAIR_ACCESSES
 265 #define SCM_DEBUG_PAIR_ACCESSES SCM_DEBUG
 266 #endif
 267
 268 /* If SCM_DEBUG_REST_ARGUMENT is set to 1, functions that take rest arguments
 269  * will check whether the rest arguments are actually passed as a proper list.
 270  * Otherwise, if SCM_DEBUG_REST_ARGUMENT is 0, functions that take rest
 271  * arguments will take it for granted that these are passed as a proper list.
 272  */
 273 #ifndef SCM_DEBUG_REST_ARGUMENT
 274 #define SCM_DEBUG_REST_ARGUMENT SCM_DEBUG
 275 #endif
 276
 277 /* The macro SCM_DEBUG_TYPING_STRICTNESS indicates what level of type checking
 278  * shall be performed with respect to the use of the SCM datatype.  The macro
 279  * may be defined to one of the values 0, 1 and 2.
 280  *
 281  * A value of 0 means that there will be no compile time type checking, since
 282  * the SCM datatype will be declared as an integral type.  This setting should
 283  * only be used on systems, where casting from integral types to pointers may
 284  * lead to loss of bit information.
 285  *
 286  * A value of 1 means that there will an intermediate level of compile time
 287  * type checking, since the SCM datatype will be declared as a pointer to an
 288  * undefined struct.  This setting is the default, since it does not cost
 289  * anything in terms of performance or code size.
 290  *
 291  * A value of 2 provides a maximum level of compile time type checking since
 292  * the SCM datatype will be declared as a struct.  This setting should be used
 293  * for _compile time_ type checking only, since the compiled result is likely
 294  * to be quite inefficient.  The right way to make use of this option is to do
 295  * a 'make clean; make CFLAGS=-DSCM_DEBUG_TYPING_STRICTNESS=2', fix your
 296  * errors, and then do 'make clean; make'.
 297  */
 298 #ifndef SCM_DEBUG_TYPING_STRICTNESS
 299 #define SCM_DEBUG_TYPING_STRICTNESS 1
 300 #endif
 301
 302 \f
 303
 304 /* {Feature Options}
 305  *
 306  * These compile time options determine whether code for certain features
 307  * should be compiled into guile.  The common prefix for all option macros
 308  * of this kind is "SCM_ENABLE_".  It is guaranteed that a macro named
 309  * SCM_ENABLE_XXX is defined to be either 0 or 1, i. e. there is no need to
 310  * test for the undefined case.  This allows to use these definitions
 311  * comfortably within code, as in the following example:
 312  *   #define FOO do { if (SCM_ENABLE_XXX) bar(); else baz(); } while (0)
 313  * Any sane compiler will remove the unused branch without any performance
 314  * penalty for the resulting code.
 315  *
 316  * Note:  Some SCM_ENABLE_XXX options are not settable at configure time.
 317  * To change the value of such options you will have to edit this header
 318  * file or give suitable options to make, like:
 319  *   make all CFLAGS="-DSCM_ENABLE_XXX=1 ..."
 320  */
 321
 322 /* If SCM_ENABLE_DEPRECATED is set to 1, deprecated code will be included in
 323  * guile, as well as some functions to issue run-time warnings about uses of
 324  * deprecated functions.
 325  */
 326 #ifndef SCM_ENABLE_DEPRECATED
 327 #define SCM_ENABLE_DEPRECATED 0
 328 #endif
 329
 330 \f
 331
 332 /* {Architecture and compiler properties}
 333  *
 334  * Guile as of today can only work on systems which fulfill at least the
 335  * following requirements:
 336  *
 337  * - scm_t_bits and SCM variables have at least 32 bits.
 338  *   Guile's type system is based on this assumption.
 339  *
 340  * - sizeof (scm_t_bits) >= sizeof (void*) and sizeof (SCM) >= sizeof (void*)
 341  *   Guile's type system is based on this assumption, since it must be
 342  *   possible to store pointers to cells on the heap in scm_t_bits and SCM
 343  *   variables.
 344  *
 345  * - sizeof (scm_t_bits) >= 4 and sizeof (scm_t_bits) is a power of 2.
 346  *   Guile's type system is based on this assumption.  In particular, it is
 347  *   assumed that cells, i. e. pairs of scm_t_bits variables, are eight
 348  *   character aligned.  This is because three bits of a scm_t_bits variable
 349  *   that is holding a pointer to a cell on the heap must be available for
 350  *   storing type data.
 351  *
 352  * - sizeof (scm_t_bits) <= sizeof (void*) and sizeof (SCM) <= sizeof (void*)
 353  *   In some parts of guile, scm_t_bits and SCM variables are passed to
 354  *   functions as void* arguments.  Together with the requirement above, this
 355  *   requires a one-to-one correspondence between the size of a void* and the
 356  *   sizes of scm_t_bits and SCM variables.
 357  *
 358  * - numbers are encoded using two's complement.
 359  *   The implementation of the bitwise scheme level operations is based on
 360  *   this assumption.
 361  *
 362  * - ... add more
 363  */
 364
 365 #ifdef CHAR_BIT
 366 # define SCM_CHAR_BIT CHAR_BIT
 367 #else
 368 # define SCM_CHAR_BIT 8
 369 #endif
 370
 371 #ifdef LONG_BIT
 372 # define SCM_LONG_BIT LONG_BIT
 373 #else
 374 # define SCM_LONG_BIT (SCM_SIZEOF_LONG * 8)
 375 #endif
 376
 377 #define SCM_I_UTYPE_MAX(type)      ((type)-1)
 378 #define SCM_I_TYPE_MAX(type,umax)  ((type)((umax)/2))
 379 #define SCM_I_TYPE_MIN(type,umax)  (-((type)((umax)/2))-1)
 380
 381 #define SCM_T_UINT8_MAX   SCM_I_UTYPE_MAX(scm_t_uint8)
 382 #define SCM_T_INT8_MIN    SCM_I_TYPE_MIN(scm_t_int8,SCM_T_UINT8_MAX)
 383 #define SCM_T_INT8_MAX    SCM_I_TYPE_MAX(scm_t_int8,SCM_T_UINT8_MAX)
 384
 385 #define SCM_T_UINT16_MAX  SCM_I_UTYPE_MAX(scm_t_uint16)
 386 #define SCM_T_INT16_MIN   SCM_I_TYPE_MIN(scm_t_int16,SCM_T_UINT16_MAX)
 387 #define SCM_T_INT16_MAX   SCM_I_TYPE_MAX(scm_t_int16,SCM_T_UINT16_MAX)
 388
 389 #define SCM_T_UINT32_MAX  SCM_I_UTYPE_MAX(scm_t_uint32)
 390 #define SCM_T_INT32_MIN   SCM_I_TYPE_MIN(scm_t_int32,SCM_T_UINT32_MAX)
 391 #define SCM_T_INT32_MAX   SCM_I_TYPE_MAX(scm_t_int32,SCM_T_UINT32_MAX)
 392
 393 #define SCM_T_UINT64_MAX  SCM_I_UTYPE_MAX(scm_t_uint64)
 394 #define SCM_T_INT64_MIN   SCM_I_TYPE_MIN(scm_t_int64,SCM_T_UINT64_MAX)
 395 #define SCM_T_INT64_MAX   SCM_I_TYPE_MAX(scm_t_int64,SCM_T_UINT64_MAX)
 396
 397 #define SCM_T_UINTMAX_MAX SCM_I_UTYPE_MAX(scm_t_uintmax)
 398 #define SCM_T_INTMAX_MIN  SCM_I_TYPE_MIN(scm_t_intmax,SCM_T_UINTMAX_MAX)
 399 #define SCM_T_INTMAX_MAX  SCM_I_TYPE_MAX(scm_t_intmax,SCM_T_UINTMAX_MAX)
 400
 401 #define SCM_T_UINTPTR_MAX SCM_I_UTYPE_MAX(scm_t_uintptr)
 402 #define SCM_T_INTPTR_MIN  SCM_I_TYPE_MIN(scm_t_intptr,SCM_T_UINTPTR_MAX)
 403 #define SCM_T_INTPTR_MAX  SCM_I_TYPE_MAX(scm_t_intptr,SCM_T_UINTPTR_MAX)
 404
 405 \f
 406
 407 #include "libguile/tags.h"
 408
 409
 410 /* The type of subrs, i.e., Scheme procedures implemented in C.  Empty
 411    function declarators are used internally for pointers to functions of
 412    any arity.  However, these are equivalent to `(void)' in C++, are
 413    obsolescent as of C99, and trigger `strict-prototypes' GCC warnings
 414    (bug #23681).  */
 415
 416 #ifdef BUILDING_LIBGUILE
 417 typedef SCM (* scm_t_subr) ();
 418 #else
 419 typedef void *scm_t_subr;
 420 #endif
 421
 422 \f
 423
 424 /* scm_i_jmp_buf
 425  *
 426  * The corresponding SCM_I_SETJMP and SCM_I_LONGJMP are defined in the
 427  * _scm.h private header.
 428  */
 429
 430 #if defined (vms)
 431 typedef int scm_i_jmp_buf[17];
 432
 433 #elif defined (_CRAY1)
 434 typedef int scm_i_jmp_buf[112];
 435
 436 #elif defined (__ia64__)
 437 # include <signal.h>
 438 # include <ucontext.h>
 439 typedef struct {
 440   ucontext_t ctx;
 441   int fresh;
 442 } scm_i_jmp_buf;
 443
 444 #else
 445 # include <setjmp.h>
 446 typedef jmp_buf scm_i_jmp_buf;
 447 #endif
 448
 449
 450 \f
 451
 452 /* If stack is not longword aligned then
 453  */
 454
 455 /* #define SHORT_ALIGN */
 456 #ifdef THINK_C
 457 # define SHORT_ALIGN
 458 #endif
 459 #ifdef MSDOS
 460 # define SHORT_ALIGN
 461 #endif
 462 #ifdef atarist
 463 # define SHORT_ALIGN
 464 #endif
 465
 466 #ifdef SHORT_ALIGN
 467 typedef short SCM_STACKITEM;
 468 #else
 469 typedef long SCM_STACKITEM;
 470 #endif
 471
 472 /* Cast pointer through (void *) in order to avoid compiler warnings
 473    when strict aliasing is enabled */
 474 #define SCM_STACK_PTR(ptr) ((SCM_STACKITEM *) (void *) (ptr))
 475 \f
 476
 477 #ifdef BUILDING_LIBGUILE
 478 #define SCM_TICK SCM_ASYNC_TICK
 479 #else
 480 #define SCM_TICK scm_async_tick ()
 481 #endif
 482
 483 \f
 484
 485 #ifndef SCM_MAGIC_SNARFER
 486 /* Let these macros pass through if
 487    we are snarfing;  thus we can tell the
 488    difference between the use of an actual
 489    number vs. the use of one of these macros --
 490    actual numbers in SCM_VALIDATE_* and SCM_ASSERT
 491    constructs must match the formal argument name,
 492    but using SCM_ARG* avoids the test */
 493
 494 #define SCM_ARGn                0
 495 #define SCM_ARG1                1
 496 #define SCM_ARG2                2
 497 #define SCM_ARG3                3
 498 #define SCM_ARG4                4
 499 #define SCM_ARG5                5
 500 #define SCM_ARG6                6
 501 #define SCM_ARG7                7
 502
 503 #endif /* SCM_MAGIC_SNARFER */
 504
 505 \f
 506
 507 /* Define SCM_C_INLINE_KEYWORD so that it can be used as a replacement
 508    for the "inline" keyword, expanding to nothing when "inline" is not
 509    available.
 510 */
 511
 512 #ifdef SCM_C_INLINE
 513 #define SCM_C_INLINE_KEYWORD SCM_C_INLINE
 514 #else
 515 #define SCM_C_INLINE_KEYWORD
 516 #endif
 517
 518 /* Handling thread-local storage (TLS).  */
 519
 520 #ifdef SCM_HAVE_THREAD_STORAGE_CLASS
 521 # define SCM_THREAD_LOCAL __thread
 522 #else
 523 # define SCM_THREAD_LOCAL
 524 #endif
 525
 526 #endif  /* SCM___SCM_H */
 527
 528 /*
 529   Local Variables:
 530   c-file-style: "gnu"
 531   End:
 532 */