6 /* Copyright (C) 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2006,
7 * 2007, 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
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.
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.
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
27 /**********************************************************************
28 This file is Guile's central public header.
30 When included by other files, this file should preceed any include
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.
41 "What's the difference between _scm.h and __scm.h?"
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.
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
51 **********************************************************************/
53 /* What did the configure script discover about the outside world? */
54 #include "libguile/scmconfig.h"
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.
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))
72 # define SCM_GNUC_PREREQ(maj, min) 0
75 /* The macro SCM_NORETURN indicates that a function will never return.
77 * 1) int foo (char arg) SCM_NORETURN;
80 #define SCM_NORETURN __attribute__ ((noreturn))
85 /* The macro SCM_UNUSED indicates that a function, function argument or
86 * variable may potentially be unused.
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;
93 #define SCM_UNUSED __attribute__ ((unused))
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
105 # define SCM_EXPECT(_expr, _value) (_expr)
108 #define SCM_LIKELY(_expr) SCM_EXPECT ((_expr), 1)
109 #define SCM_UNLIKELY(_expr) SCM_EXPECT ((_expr), 0)
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
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__))
124 # define SCM_DEPRECATED SCM_API
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))
135 /* Don't know how to align things. */
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__))
150 /* SCM_API is a macro prepended to all function and data definitions
151 which should be exported from libguile. */
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
160 # define SCM_API extern
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
171 Hence the `__gnu_inline__' attribute, in accordance with:
172 http://gcc.gnu.org/gcc-4.3/porting_to.html .
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.
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. */
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__))
187 # define SCM_C_EXTERN_INLINE extern __inline__
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
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
209 /* Fall back to static inline if GNU "extern inline" is unavailable. */
210 # define SCM_INLINE static SCM_C_INLINE
212 # define SCM_INLINE_IMPLEMENTATION SCM_INLINE
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
223 /* {Debugging Options}
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
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.
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 ..."
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.
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.
256 #ifndef SCM_DEBUG_CELL_ACCESSES
257 #define SCM_DEBUG_CELL_ACCESSES SCM_DEBUG
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.
264 #ifndef SCM_DEBUG_PAIR_ACCESSES
265 #define SCM_DEBUG_PAIR_ACCESSES SCM_DEBUG
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.
273 #ifndef SCM_DEBUG_REST_ARGUMENT
274 #define SCM_DEBUG_REST_ARGUMENT SCM_DEBUG
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.
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.
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.
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'.
298 #ifndef SCM_DEBUG_TYPING_STRICTNESS
299 #define SCM_DEBUG_TYPING_STRICTNESS 1
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.
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 ..."
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.
326 #ifndef SCM_ENABLE_DEPRECATED
327 #define SCM_ENABLE_DEPRECATED 0
332 /* {Architecture and compiler properties}
334 * Guile as of today can only work on systems which fulfill at least the
335 * following requirements:
337 * - scm_t_bits and SCM variables have at least 32 bits.
338 * Guile's type system is based on this assumption.
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
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
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.
358 * - numbers are encoded using two's complement.
359 * The implementation of the bitwise scheme level operations is based on
366 # define SCM_CHAR_BIT CHAR_BIT
368 # define SCM_CHAR_BIT 8
372 # define SCM_LONG_BIT LONG_BIT
374 # define SCM_LONG_BIT (SCM_CHAR_BIT * sizeof (long) / sizeof (char))
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)
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)
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)
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)
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)
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)
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)
407 #include "libguile/tags.h"
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
416 #ifdef BUILDING_LIBGUILE
417 typedef SCM (* scm_t_subr
) ();
419 typedef void *scm_t_subr
;
426 * The corresponding SCM_I_SETJMP and SCM_I_LONGJMP are defined in the
427 * _scm.h private header.
431 typedef int scm_i_jmp_buf
[17];
433 #elif defined (_CRAY1)
434 typedef int scm_i_jmp_buf
[112];
436 #elif defined (__ia64__)
438 # include <ucontext.h>
446 typedef jmp_buf scm_i_jmp_buf
;
452 /* If stack is not longword aligned then
455 /* #define SHORT_ALIGN */
467 typedef short SCM_STACKITEM
;
469 typedef long SCM_STACKITEM
;
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))
477 #ifdef BUILDING_LIBGUILE
478 #define SCM_TICK SCM_ASYNC_TICK
480 #define SCM_TICK scm_async_tick ()
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 */
503 #endif /* SCM_MAGIC_SNARFER */
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
513 #define SCM_C_INLINE_KEYWORD SCM_C_INLINE
515 #define SCM_C_INLINE_KEYWORD
518 /* Handling thread-local storage (TLS). */
520 #ifdef SCM_HAVE_THREAD_STORAGE_CLASS
521 # define SCM_THREAD_LOCAL __thread
523 # define SCM_THREAD_LOCAL
526 #endif /* SCM___SCM_H */