1 #ifndef SCM_SCM_H 2 #define SCM_SCM_H 3 4 /* Copyright 1995-2004,2006-2015,2017-2019 5 Free Software Foundation, Inc. 6 7 This file is part of Guile. 8 9 Guile is free software: you can redistribute it and/or modify it 10 under the terms of the GNU Lesser General Public License as published 11 by the Free Software Foundation, either version 3 of the License, or 12 (at your option) any later version. 13 14 Guile is distributed in the hope that it will be useful, but WITHOUT 15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 16 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 17 License for more details. 18 19 You should have received a copy of the GNU Lesser General Public 20 License along with Guile. If not, see 21 <https://www.gnu.org/licenses/>. */ 22 23 /* This is the central header for Guile that defines how Scheme values 24 are represented. Enjoy the read! */ 25 26 27 28 #include <stdint.h> 29 30 #include "libguile/scmconfig.h" 31 32 33 34 35 /* The value of SCM_DEBUG determines the default for most of the not yet 36 defined debugging options. This allows, for example, to enable most 37 of the debugging options by simply defining SCM_DEBUG as 1. */ 38 #ifndef SCM_DEBUG 39 #define SCM_DEBUG 0 40 #endif 41 42 /* If SCM_DEBUG_PAIR_ACCESSES is set to 1, accesses to cons cells will 43 be exhaustively checked. Note: If this option is enabled, guile 44 will run slower than normally. */ 45 #ifndef SCM_DEBUG_PAIR_ACCESSES 46 #define SCM_DEBUG_PAIR_ACCESSES SCM_DEBUG 47 #endif 48 49 /* If SCM_DEBUG_REST_ARGUMENT is set to 1, functions that take rest 50 arguments will check whether the rest arguments are actually passed 51 as a proper list. Otherwise, if SCM_DEBUG_REST_ARGUMENT is 0, 52 functions that take rest arguments will take it for granted that 53 these are passed as a proper list. */ 54 #ifndef SCM_DEBUG_REST_ARGUMENT 55 #define SCM_DEBUG_REST_ARGUMENT SCM_DEBUG 56 #endif 57 58 /* The macro SCM_DEBUG_TYPING_STRICTNESS indicates what level of type 59 checking shall be performed with respect to the use of the SCM 60 datatype. The macro may be defined to one of the values 0, 1 and 2. 61 62 A value of 0 means that there will be no compile time type checking, 63 since the SCM datatype will be declared as an integral type. This 64 setting should only be used on systems, where casting from integral 65 types to pointers may lead to loss of bit information. 66 67 A value of 1 means that there will an intermediate level of compile 68 time type checking, since the SCM datatype will be declared as a 69 pointer to an undefined struct. This setting is the default, since 70 it does not cost anything in terms of performance or code size. 71 72 A value of 2 provides a maximum level of compile time type checking 73 since the SCM datatype will be declared as a struct. This setting 74 should be used for _compile time_ type checking only, since the 75 compiled result is likely to be quite inefficient. The right way to 76 make use of this option is to do a 'make clean; make 77 CFLAGS=-DSCM_DEBUG_TYPING_STRICTNESS=2', fix your errors, and then do 78 'make clean; make'. */ 79 #ifndef SCM_DEBUG_TYPING_STRICTNESS 80 #define SCM_DEBUG_TYPING_STRICTNESS 1 81 #endif 82 83 84 85 /* Guile as of today can only work on systems which fulfill at least the 86 following requirements: 87 88 - scm_t_bits and SCM variables have at least 32 bits. 89 Guile's type system is based on this assumption. 90 91 - sizeof (scm_t_bits) >= sizeof (void*) and sizeof (SCM) >= sizeof (void*) 92 Guile's type system is based on this assumption, since it must be 93 possible to store pointers to cells on the heap in scm_t_bits and 94 SCM variables. 95 96 - sizeof (scm_t_bits) >= 4 and sizeof (scm_t_bits) is a power of 2. 97 Guile's type system is based on this assumption. In particular, it 98 is assumed that cells, i. e. pairs of scm_t_bits variables, are 99 eight-byte aligned. This is because three bits of a scm_t_bits 100 variable that is holding a pointer to a cell on the heap must be 101 available for storing type data. 102 103 - sizeof (scm_t_bits) <= sizeof (void*) and sizeof (SCM) <= sizeof (void*) 104 In some parts of guile, scm_t_bits and SCM variables are passed to 105 functions as void* arguments. Together with the requirement above, 106 this requires a one-to-one correspondence between the size of a 107 void* and the sizes of scm_t_bits and SCM variables. 108 109 - numbers are encoded using two's complement. 110 The implementation of the bitwise Scheme-level operations is based on 111 this assumption. */ 112 113 114 115 /* In the beginning was the Word: 116 117 For the representation of scheme objects and their handling, Guile 118 provides two types: scm_t_bits and SCM. 119 120 - scm_t_bits values can hold bit patterns of non-objects and objects: 121 122 Non-objects -- in this case the value may not be changed into a SCM 123 value in any way. 124 125 Objects -- in this case the value may be changed into a SCM value 126 using the SCM_PACK macro. 127 128 - SCM values can hold proper scheme objects only. They can be 129 changed into a scm_t_bits value using the SCM_UNPACK macro. 130 131 When working in the domain of scm_t_bits values, programmers must 132 keep track of any scm_t_bits value they create that is not a proper 133 scheme object. This makes sure that in the domain of SCM values 134 developers can rely on the fact that they are dealing with proper 135 scheme objects only. Thus, the distinction between scm_t_bits and 136 SCM values helps to identify those parts of the code where special 137 care has to be taken not to create bad SCM values. */ 138 139 /* For dealing with the bit level representation of scheme objects we 140 define scm_t_bits. */ 141 typedef intptr_t scm_t_signed_bits; 142 typedef uintptr_t scm_t_bits; 143 144 #define SCM_T_SIGNED_BITS_MAX INTPTR_MAX 145 #define SCM_T_SIGNED_BITS_MIN INTPTR_MIN 146 #define SCM_T_BITS_MAX UINTPTR_MAX 147 148 149 /* But as external interface, we define SCM, which may, according to the 150 desired level of type checking, be defined in several ways. */ 151 #if (SCM_DEBUG_TYPING_STRICTNESS == 2) 152 typedef union SCM { struct { scm_t_bits n; } n; } SCM; 153 # define SCM_UNPACK(x) ((x).n.n) 154 # define SCM_PACK(x) ((SCM) { { (scm_t_bits) (x) } }) 155 #elif (SCM_DEBUG_TYPING_STRICTNESS == 1) 156 /* This is the default, which provides an intermediate level of compile 157 time type checking while still resulting in very efficient code. */ 158 typedef struct scm_unused_struct { char scm_unused_field; } *SCM; 159 160 /* The 0?: constructions makes sure that the code is never executed, and 161 that there is no performance hit. However, the alternative is 162 compiled, and does generate a warning when used with the wrong 163 pointer type. We use a volatile pointer type to avoid warnings from 164 clang. 165 166 The Tru64 and ia64-hp-hpux11.23 compilers fail on `case (0?0=0:x)' 167 statements, so for them type-checking is disabled. */ 168 # if defined __DECC || defined __HP_cc 169 # define SCM_UNPACK(x) ((scm_t_bits) (x)) 170 # else 171 # define SCM_UNPACK(x) ((scm_t_bits) (0? (*(volatile SCM *)0=(x)): x)) 172 # endif 173 174 /* There is no typechecking on SCM_PACK, since all kinds of types 175 (unsigned long, void*) go in SCM_PACK. */ 176 # define SCM_PACK(x) ((SCM) (x)) 177 178 #else 179 /* This should be used as a fall back solution for machines on which 180 casting to a pointer may lead to loss of bit information, e. g. in 181 the three least significant bits. */ 182 typedef scm_t_bits SCM; 183 # define SCM_UNPACK(x) (x) 184 # define SCM_PACK(x) ((SCM) (x)) 185 #endif 186 187 /* Packing SCM objects into and out of pointers. */ 188 #define SCM_UNPACK_POINTER(x) ((scm_t_bits *) (SCM_UNPACK (x))) 189 #define SCM_PACK_POINTER(x) (SCM_PACK ((scm_t_bits) (x))) 190 191 /* SCM values can not be compared by using the operator ==. Use the 192 following macro instead, which is the equivalent of the scheme 193 predicate 'eq?'. */ 194 #define scm_is_eq(x, y) (SCM_UNPACK (x) == SCM_UNPACK (y)) 195 196 197 198 199 /* Representation of scheme objects: 200 201 Guile's type system is designed to work on systems where scm_t_bits 202 and SCM variables consist of at least 32 bits. The objects that a 203 SCM variable can represent belong to one of the following two major 204 categories: 205 206 - Immediates -- meaning that the SCM variable contains an entire 207 Scheme object. That means, all the object's data (including the 208 type tagging information that is required to identify the object's 209 type) must fit into 32 bits. 210 211 - Heap objects -- meaning that the SCM variable holds a pointer into 212 the heap. On systems where a pointer needs more than 32 bits this 213 means that scm_t_bits and SCM variables need to be large enough to 214 hold such pointers. In contrast to immediates, the data associated 215 with a heap object can consume arbitrary amounts of memory. 216 217 The 'heap' is the memory area that is under control of Guile's 218 garbage collector. It holds allocated memory of various sizes. The 219 impact on the runtime type system is that Guile needs to be able to 220 determine the type of an object given the pointer. Usually the way 221 that Guile does this is by storing a "type tag" in the first word of 222 the object. 223 224 Some objects are common enough that they get special treatment. 225 Since Guile guarantees that the address of a GC-allocated object on 226 the heap is 8-byte aligned, Guile can play tricks with the lower 3 227 bits. That is, since heap objects encode a pointer to an 228 8-byte-aligned pointer, the three least significant bits of a SCM can 229 be used to store additional information. The bits are used to store 230 information about the object's type and thus are called tc3-bits, 231 where tc stands for type-code. 232 233 For a given SCM value, the distinction whether it holds an immediate 234 or heap object is based on the tc3-bits (see above) of its scm_t_bits 235 equivalent: If the tc3-bits equal #b000, then the SCM value holds a 236 heap object, and the scm_t_bits variable's value is just the pointer 237 to the heap cell. 238 239 Summarized, the data of a scheme object that is represented by a SCM 240 variable consists of a) the SCM variable itself, b) in case of heap 241 objects memory that the SCM object points to, c) in case of heap 242 objects potentially additional data outside of the heap (like for 243 example malloc'ed data), and d) in case of heap objects potentially 244 additional data inside of the heap, since data stored in b) and c) 245 may hold references to other cells. 246 247 248 Immediates 249 250 Operations on immediate objects can typically be processed faster 251 than on heap objects. The reason is that the object's data can be 252 extracted directly from the SCM variable (or rather a corresponding 253 scm_t_bits variable), instead of having to perform additional memory 254 accesses to obtain the object's data from the heap. In order to get 255 the best possible performance frequently used data types should be 256 realized as immediates. This is, as has been mentioned above, only 257 possible if the objects can be represented with 32 bits (including 258 type tagging). 259 260 In Guile, the following data types and special objects are realized 261 as immediates: booleans, characters, small integers (see below), the 262 empty list, the end of file object, the 'unspecified' object (which 263 is delivered as a return value by functions for which the return 264 value is unspecified), a 'nil' object used in the elisp-compatibility 265 mode and certain other 'special' objects which are only used 266 internally in Guile. 267 268 Integers in Guile can be arbitrarily large. On the other hand, 269 integers are one of the most frequently used data types. Especially 270 integers with less than 32 bits are commonly used. Thus, internally 271 and transparently for application code guile distinguishes between 272 small and large integers. Whether an integer is a large or a small 273 integer depends on the number of bits needed to represent its value. 274 Small integers are those which can be represented as immediates. 275 Since they don't require more than a fixed number of bits for their 276 representation, they are also known as 'fixnums'. 277 278 The tc3-combinations #b010 and #b110 are used to represent small 279 integers, which allows to use the most significant bit of the 280 tc3-bits to be part of the integer value being represented. This 281 means that all integers with up to 30 bits (including one bit for the 282 sign) can be represented as immediates. On systems where SCM and 283 scm_t_bits variables hold more than 32 bits, the amount of bits 284 usable for small integers will even be larger. The tc3-code #b100 is 285 shared among booleans, characters and the other special objects 286 listed above. 287 288 289 Heap Objects 290 291 All object types not mentioned above in the list of immediate objects 292 are represented as heap objects. The amount of memory referenced by 293 a heap object depends on the object's type, namely on the set of 294 attributes that have to be stored with objects of that type. Every 295 heap object type is allowed to define its own layout and 296 interpretation of the data stored in its cell (with some 297 restrictions, see below). 298 299 One of the design goals of guile's type system is to make it possible 300 to store a scheme pair with as little memory usage as possible. The 301 minimum amount of memory that is required to store two scheme objects 302 (car and cdr of a pair) is the amount of memory required by two 303 scm_t_bits or SCM variables. Therefore pairs in guile are stored in 304 two words, and are tagged with a bit pattern in the SCM value, not 305 with a type tag on the heap. 306 307 308 Garbage collection 309 310 During garbage collection, unreachable objects on the heap will be 311 freed. To determine the set of reachable objects, by default, the GC 312 just traces all words in all heap objects. It is possible to 313 register custom tracing ("marking") procedures. 314 315 If an object is unreachable, by default, the GC just notes this fact 316 and moves on. Later allocations will clear out the memory associated 317 with the object, and re-use it. It is possible to register custom 318 finalizers, however. 319 320 321 Run-time type introspection 322 323 Guile's type system is designed to make it possible to determine a 324 the type of a heap object from the object's first scm_t_bits 325 variable. (Given a SCM variable X holding a heap object, the macro 326 SCM_CELL_TYPE(X) will deliver the corresponding object's first 327 scm_t_bits variable.) 328 329 If the object holds a scheme pair, then we already know that the 330 first scm_t_bits variable of the cell will hold a scheme object with 331 one of the following tc3-codes: #b000 (heap object), #b010 (small 332 integer), #b110 (small integer), #b100 (non-integer immediate). All 333 these tc3-codes have in common, that their least significant bit is 334 #b0. This fact is used by the garbage collector to identify cells 335 that hold pairs. The remaining tc3-codes are assigned as follows: 336 #b001 (class instance or, more precisely, a struct, of which a class 337 instance is a special case), #b011 (closure), #b101/#b111 (all 338 remaining heap object types). 339 340 341 Summary of type codes of scheme objects (SCM variables) 342 343 Here is a summary of tagging bits as they might occur in a scheme 344 object. The notation is as follows: tc stands for type code as 345 before, tc<n> with n being a number indicates a type code formed by 346 the n least significant bits of the SCM variables corresponding 347 scm_t_bits value. 348 349 Note that (as has been explained above) tc1==1 can only occur in the 350 first scm_t_bits variable of a cell belonging to a heap object that 351 is not a pair. For an explanation of the tc tags with tc1==1, see 352 the next section with the summary of the type codes on the heap. 353 354 tc1: 355 0: For scheme objects, tc1==0 must be fulfilled. 356 (1: This can never be the case for a scheme object.) 357 358 tc2: 359 00: Either a heap object or some non-integer immediate 360 (01: This can never be the case for a scheme object.) 361 10: Small integer 362 (11: This can never be the case for a scheme object.) 363 364 tc3: 365 000: a heap object (pair, closure, class instance etc.) 366 (001: This can never be the case for a scheme object.) 367 010: an even small integer (least significant bit is 0). 368 (011: This can never be the case for a scheme object.) 369 100: Non-integer immediate 370 (101: This can never be the case for a scheme object.) 371 110: an odd small integer (least significant bit is 1). 372 (111: This can never be the case for a scheme object.) 373 374 The remaining bits of the heap objects form the pointer to the heap 375 cell. The remaining bits of the small integers form the integer's 376 value and sign. Thus, the only scheme objects for which a further 377 subdivision is of interest are the ones with tc3==100. 378 379 tc8 (for objects with tc3==100): 380 00000-100: special objects ('flags') 381 00001-100: characters 382 00010-100: unused 383 00011-100: unused 384 385 386 Summary of type codes on the heap 387 388 Here is a summary of tagging in scm_t_bits values as they might occur 389 in the first scm_t_bits variable of a heap cell. 390 391 tc1: 392 0: the cell belongs to a pair. 393 1: the cell belongs to a non-pair. 394 395 tc2: 396 00: the cell belongs to a pair with no short integer in its car. 397 01: the cell belongs to a non-pair (struct or some other heap object). 398 10: the cell belongs to a pair with a short integer in its car. 399 11: the cell belongs to a non-pair (closure or some other heap object). 400 401 tc3: 402 000: the cell belongs to a pair with a heap object in its car. 403 001: the cell belongs to a struct 404 010: the cell belongs to a pair with an even short integer in its car. 405 011: the cell belongs to a closure 406 100: the cell belongs to a pair with a non-integer immediate in its car. 407 101: the cell belongs to some other heap object. 408 110: the cell belongs to a pair with an odd short integer in its car. 409 111: the cell belongs to some other heap object. 410 411 tc7 (for tc3==1x1): 412 See below for the list of types. Three special tc7-codes are of 413 interest: numbers, ports and smobs in fact each represent 414 collections of types, which are subdivided using tc16-codes. 415 416 tc16 (for tc7==scm_tc7_smob): 417 The largest part of the space of smob types is not subdivided in a 418 predefined way, since smobs can be added arbitrarily by user C 419 code. */ 420 421 422 423 /* Checking if a SCM variable holds an immediate or a heap object. This 424 check can either be performed by checking for tc3==000 or tc3==00x, 425 since for a SCM variable it is known that tc1==0. */ 426 #define SCM_IMP(x) (6 & SCM_UNPACK (x)) 427 #define SCM_NIMP(x) (!SCM_IMP (x)) 428 #define SCM_HEAP_OBJECT_P(x) (SCM_NIMP (x)) 429 430 /* Checking if a SCM variable holds an immediate integer: See numbers.h 431 for the definition of the following macros: SCM_I_FIXNUM_BIT, 432 SCM_MOST_POSITIVE_FIXNUM, SCM_I_INUMP, SCM_I_MAKINUM, SCM_I_INUM. */ 433 434 /* Checking if a SCM variable holds a pair (for historical reasons, in 435 Guile also known as a cons-cell): This is done by first checking that 436 the SCM variable holds a heap object, and second, by checking that 437 tc1==0 holds for the SCM_CELL_TYPE of the SCM variable. */ 438 #define SCM_I_CONSP(x) (!SCM_IMP (x) && ((1 & SCM_CELL_TYPE (x)) == 0)) 439 440 441 442 /* Definitions for tc2: */ 443 444 #define scm_tc2_int 2 445 446 447 /* Definitions for tc3: */ 448 449 #define SCM_ITAG3(x) (7 & SCM_UNPACK (x)) 450 #define SCM_TYP3(x) (7 & SCM_CELL_TYPE (x)) 451 452 #define scm_tc3_cons 0 453 #define scm_tc3_struct 1 454 #define scm_tc3_int_1 (scm_tc2_int + 0) 455 #define scm_tc3_unused 3 456 #define scm_tc3_imm24 4 457 #define scm_tc3_tc7_1 5 458 #define scm_tc3_int_2 (scm_tc2_int + 4) 459 #define scm_tc3_tc7_2 7 460 461 462 /* Definitions for tc7: */ 463 464 #define SCM_ITAG7(x) (0x7f & SCM_UNPACK (x)) 465 #define SCM_TYP7(x) (0x7f & SCM_CELL_TYPE (x)) 466 #define SCM_HAS_HEAP_TYPE(x, type, tag) \ 467 (SCM_NIMP (x) && type (x) == (tag)) 468 #define SCM_HAS_TYP7(x, tag) (SCM_HAS_HEAP_TYPE (x, SCM_TYP7, tag)) 469 470 /* These type codes form part of the ABI and cannot be changed in a 471 stable series. The low bits of each must have the tc3 of a heap 472 object type code (see above). If you do change them in a development 473 series, change them also in (system vm assembler) and (system base 474 types). Bonus points if you change the build to define these tag 475 values in only one place! */ 476 477 #define scm_tc7_symbol 0x05 478 #define scm_tc7_variable 0x07 479 #define scm_tc7_vector 0x0d 480 #define scm_tc7_wvect 0x0f 481 #define scm_tc7_string 0x15 482 #define scm_tc7_number 0x17 483 #define scm_tc7_hashtable 0x1d 484 #define scm_tc7_pointer 0x1f 485 #define scm_tc7_fluid 0x25 486 #define scm_tc7_stringbuf 0x27 487 #define scm_tc7_dynamic_state 0x2d 488 #define scm_tc7_frame 0x2f 489 #define scm_tc7_keyword 0x35 490 #define scm_tc7_atomic_box 0x37 491 #define scm_tc7_syntax 0x3d 492 #define scm_tc7_values 0x3f 493 #define scm_tc7_program 0x45 494 #define scm_tc7_vm_cont 0x47 495 #define scm_tc7_bytevector 0x4d 496 #define scm_tc7_unused_4f 0x4f 497 #define scm_tc7_weak_set 0x55 498 #define scm_tc7_weak_table 0x57 499 #define scm_tc7_array 0x5d 500 #define scm_tc7_bitvector 0x5f 501 #define scm_tc7_unused_65 0x65 502 #define scm_tc7_unused_67 0x67 503 #define scm_tc7_unused_6d 0x6d 504 #define scm_tc7_unused_6f 0x6f 505 #define scm_tc7_unused_75 0x75 506 #define scm_tc7_smob 0x77 507 #define scm_tc7_port 0x7d 508 #define scm_tc7_unused_7f 0x7f 509 510 511 /* Definitions for tc16: */ 512 #define SCM_TYP16(x) (0xffff & SCM_CELL_TYPE (x)) 513 #define SCM_HAS_TYP16(x, tag) (SCM_HAS_HEAP_TYPE (x, SCM_TYP16, tag)) 514 #define SCM_TYP16_PREDICATE(tag, x) (SCM_HAS_TYP16 (x, tag)) 515 516 517 518 519 /* Immediate values (besides fixnums). */ 520 521 enum scm_tc8_tags 522 { 523 scm_tc8_flag = scm_tc3_imm24 + 0x00, /* special objects ('flags') */ 524 scm_tc8_char = scm_tc3_imm24 + 0x08, /* characters */ 525 scm_tc8_unused_0 = scm_tc3_imm24 + 0x10, 526 scm_tc8_unused_1 = scm_tc3_imm24 + 0x18 527 }; 528 529 #define SCM_ITAG8(X) (SCM_UNPACK (X) & 0xff) 530 #define SCM_MAKE_ITAG8_BITS(X, TAG) (((X) << 8) + TAG) 531 #define SCM_MAKE_ITAG8(X, TAG) (SCM_PACK (SCM_MAKE_ITAG8_BITS (X, TAG))) 532 #define SCM_ITAG8_DATA(X) (SCM_UNPACK (X) >> 8) 533 534 535 536 /* Flags (special objects). The indices of the flags must agree with 537 the declarations in print.c: iflagnames. */ 538 539 #define SCM_IFLAGP(n) (SCM_ITAG8 (n) == scm_tc8_flag) 540 #define SCM_MAKIFLAG_BITS(n) (SCM_MAKE_ITAG8_BITS ((n), scm_tc8_flag)) 541 #define SCM_IFLAGNUM(n) (SCM_ITAG8_DATA (n)) 542 543 /* 544 IMPORTANT NOTE regarding IFLAG numbering!!! 545 546 Several macros depend upon careful IFLAG numbering of SCM_BOOL_F, 547 SCM_BOOL_T, SCM_ELISP_NIL, SCM_EOL, and the two SCM_XXX_*_DONT_USE 548 constants. In particular: 549 550 - SCM_BOOL_F and SCM_BOOL_T must differ in exactly one bit position. 551 (used to implement scm_is_bool_and_not_nil, aka scm_is_bool) 552 553 - SCM_ELISP_NIL and SCM_BOOL_F must differ in exactly one bit 554 position. (used to implement scm_is_false_or_nil and 555 scm_is_true_and_not_nil) 556 557 - SCM_ELISP_NIL and SCM_EOL must differ in exactly one bit position. 558 (used to implement scm_is_null_or_nil) 559 560 - SCM_ELISP_NIL, SCM_BOOL_F, SCM_EOL, 561 SCM_XXX_ANOTHER_LISP_FALSE_DONT_USE must all be equal except for 562 two bit positions. (used to implement scm_is_lisp_false) 563 564 - SCM_ELISP_NIL, SCM_BOOL_F, SCM_BOOL_T, 565 SCM_XXX_ANOTHER_BOOLEAN_DONT_USE_0 must all be equal except for two 566 bit positions. (used to implement scm_is_bool_or_nil) 567 568 These properties allow the aforementioned macros to be implemented by 569 bitwise ANDing with a mask and then comparing with a constant, using 570 as a common basis the macro SCM_MATCHES_BITS_IN_COMMON, defined 571 below. The properties are checked at compile-time using `verify' 572 macros near the top of boolean.c and pairs.c. */ 573 #define SCM_BOOL_F_BITS SCM_MAKIFLAG_BITS (0) 574 #define SCM_ELISP_NIL_BITS SCM_MAKIFLAG_BITS (1) 575 576 #define SCM_BOOL_F SCM_PACK (SCM_BOOL_F_BITS) 577 #define SCM_ELISP_NIL SCM_PACK (SCM_ELISP_NIL_BITS) 578 579 #ifdef BUILDING_LIBGUILE 580 #define SCM_XXX_ANOTHER_LISP_FALSE_DONT_USE SCM_MAKIFLAG_BITS (2) 581 #endif 582 583 #define SCM_EOL_BITS SCM_MAKIFLAG_BITS (3) 584 #define SCM_BOOL_T_BITS SCM_MAKIFLAG_BITS (4) 585 586 #define SCM_EOL SCM_PACK (SCM_EOL_BITS) 587 #define SCM_BOOL_T SCM_PACK (SCM_BOOL_T_BITS) 588 589 #ifdef BUILDING_LIBGUILE 590 #define SCM_XXX_ANOTHER_BOOLEAN_DONT_USE_0 SCM_MAKIFLAG_BITS (5) 591 #define SCM_XXX_ANOTHER_BOOLEAN_DONT_USE_1 SCM_MAKIFLAG_BITS (6) 592 #define SCM_XXX_ANOTHER_BOOLEAN_DONT_USE_2 SCM_MAKIFLAG_BITS (7) 593 #endif 594 595 #define SCM_UNSPECIFIED_BITS SCM_MAKIFLAG_BITS (8) 596 #define SCM_UNDEFINED_BITS SCM_MAKIFLAG_BITS (9) 597 #define SCM_EOF_VAL_BITS SCM_MAKIFLAG_BITS (10) 598 599 #define SCM_UNSPECIFIED SCM_PACK (SCM_UNSPECIFIED_BITS) 600 #define SCM_UNDEFINED SCM_PACK (SCM_UNDEFINED_BITS) 601 #define SCM_EOF_VAL SCM_PACK (SCM_EOF_VAL_BITS) 602 603 #define SCM_UNBNDP(x) (scm_is_eq ((x), SCM_UNDEFINED)) 604 605 /* SCM_MATCHES_BITS_IN_COMMON(x,a,b) returns 1 if and only if x matches 606 both a and b in every bit position where a and b are equal; otherwise 607 it returns 0. Bit positions where a and b differ are ignored. 608 609 This is used to efficiently compare against two values which differ 610 in exactly one bit position, or against four values which differ in 611 exactly two bit positions. It is the basis for the following macros: 612 613 scm_is_null_or_nil, 614 scm_is_false_or_nil, 615 scm_is_true_and_not_nil, 616 scm_is_lisp_false, 617 scm_is_lisp_true, 618 scm_is_bool_and_not_nil (aka scm_is_bool) 619 scm_is_bool_or_nil. */ 620 #define SCM_MATCHES_BITS_IN_COMMON(x,a,b) \ 621 ((SCM_UNPACK(x) & ~(SCM_UNPACK(a) ^ SCM_UNPACK(b))) == \ 622 (SCM_UNPACK(a) & SCM_UNPACK(b))) 623 624 /* These macros are used for compile-time verification that the 625 constants have the properties needed for the above macro to work 626 properly. */ 627 #ifdef BUILDING_LIBGUILE 628 #define SCM_WITH_LEAST_SIGNIFICANT_1_BIT_CLEARED(x) ((x) & ((x)-1)) 629 #define SCM_HAS_EXACTLY_ONE_BIT_SET(x) \ 630 ((x) != 0 && SCM_WITH_LEAST_SIGNIFICANT_1_BIT_CLEARED (x) == 0) 631 #define SCM_HAS_EXACTLY_TWO_BITS_SET(x) \ 632 (SCM_HAS_EXACTLY_ONE_BIT_SET (SCM_WITH_LEAST_SIGNIFICANT_1_BIT_CLEARED (x))) 633 634 #define SCM_BITS_DIFFER_IN_EXACTLY_ONE_BIT_POSITION(a,b) \ 635 (SCM_HAS_EXACTLY_ONE_BIT_SET ((a) ^ (b))) 636 #define SCM_BITS_DIFFER_IN_EXACTLY_TWO_BIT_POSITIONS(a,b,c,d) \ 637 (SCM_HAS_EXACTLY_TWO_BITS_SET (((a) ^ (b)) | \ 638 ((b) ^ (c)) | \ 639 ((c) ^ (d)))) 640 #endif /* BUILDING_LIBGUILE */ 641 642 643 644 645 /* Dispatching aids: 646 647 When switching on SCM_TYP7 of a SCM value, use these fake case 648 labels to catch types that use fewer than 7 bits for tagging. */ 649 650 /* Pairs with immediate values in the CAR. */ 651 #define scm_tcs_cons_imcar \ 652 scm_tc2_int + 0: case scm_tc2_int + 4: case scm_tc3_imm24 + 0:\ 653 case scm_tc2_int + 8: case scm_tc2_int + 12: case scm_tc3_imm24 + 8:\ 654 case scm_tc2_int + 16: case scm_tc2_int + 20: case scm_tc3_imm24 + 16:\ 655 case scm_tc2_int + 24: case scm_tc2_int + 28: case scm_tc3_imm24 + 24:\ 656 case scm_tc2_int + 32: case scm_tc2_int + 36: case scm_tc3_imm24 + 32:\ 657 case scm_tc2_int + 40: case scm_tc2_int + 44: case scm_tc3_imm24 + 40:\ 658 case scm_tc2_int + 48: case scm_tc2_int + 52: case scm_tc3_imm24 + 48:\ 659 case scm_tc2_int + 56: case scm_tc2_int + 60: case scm_tc3_imm24 + 56:\ 660 case scm_tc2_int + 64: case scm_tc2_int + 68: case scm_tc3_imm24 + 64:\ 661 case scm_tc2_int + 72: case scm_tc2_int + 76: case scm_tc3_imm24 + 72:\ 662 case scm_tc2_int + 80: case scm_tc2_int + 84: case scm_tc3_imm24 + 80:\ 663 case scm_tc2_int + 88: case scm_tc2_int + 92: case scm_tc3_imm24 + 88:\ 664 case scm_tc2_int + 96: case scm_tc2_int + 100: case scm_tc3_imm24 + 96:\ 665 case scm_tc2_int + 104: case scm_tc2_int + 108: case scm_tc3_imm24 + 104:\ 666 case scm_tc2_int + 112: case scm_tc2_int + 116: case scm_tc3_imm24 + 112:\ 667 case scm_tc2_int + 120: case scm_tc2_int + 124: case scm_tc3_imm24 + 120 668 669 /* Pairs with heap objects in the CAR. */ 670 #define scm_tcs_cons_nimcar \ 671 scm_tc3_cons + 0:\ 672 case scm_tc3_cons + 8:\ 673 case scm_tc3_cons + 16:\ 674 case scm_tc3_cons + 24:\ 675 case scm_tc3_cons + 32:\ 676 case scm_tc3_cons + 40:\ 677 case scm_tc3_cons + 48:\ 678 case scm_tc3_cons + 56:\ 679 case scm_tc3_cons + 64:\ 680 case scm_tc3_cons + 72:\ 681 case scm_tc3_cons + 80:\ 682 case scm_tc3_cons + 88:\ 683 case scm_tc3_cons + 96:\ 684 case scm_tc3_cons + 104:\ 685 case scm_tc3_cons + 112:\ 686 case scm_tc3_cons + 120 687 688 /* Structs. */ 689 #define scm_tcs_struct \ 690 scm_tc3_struct + 0:\ 691 case scm_tc3_struct + 8:\ 692 case scm_tc3_struct + 16:\ 693 case scm_tc3_struct + 24:\ 694 case scm_tc3_struct + 32:\ 695 case scm_tc3_struct + 40:\ 696 case scm_tc3_struct + 48:\ 697 case scm_tc3_struct + 56:\ 698 case scm_tc3_struct + 64:\ 699 case scm_tc3_struct + 72:\ 700 case scm_tc3_struct + 80:\ 701 case scm_tc3_struct + 88:\ 702 case scm_tc3_struct + 96:\ 703 case scm_tc3_struct + 104:\ 704 case scm_tc3_struct + 112:\ 705 case scm_tc3_struct + 120 706 707 708 709 710 /* If SCM_ENABLE_DEPRECATED is set to 1, deprecated code will be 711 included in Guile, as well as some functions to issue run-time 712 warnings about uses of deprecated functions. */ 713 #ifndef SCM_ENABLE_DEPRECATED 714 #define SCM_ENABLE_DEPRECATED 0 715 #endif 716 717 718 719 /* SCM_API is a macro prepended to all function and data definitions 720 which should be exported from libguile. */ 721 #if defined BUILDING_LIBGUILE && defined HAVE_VISIBILITY 722 # define SCM_API extern __attribute__((__visibility__("default"))) 723 #elif defined BUILDING_LIBGUILE && defined _MSC_VER 724 # define SCM_API __declspec(dllexport) extern 725 #elif defined _MSC_VER 726 # define SCM_API __declspec(dllimport) extern 727 #else 728 # define SCM_API extern 729 #endif 730 731 /* The SCM_INTERNAL macro makes it possible to explicitly declare a 732 function as having "internal" linkage. However our current tack on 733 this problem is to use GCC 4's -fvisibility=hidden, making functions 734 internal by default, and then SCM_API marks them for export. */ 735 #define SCM_INTERNAL extern 736 737 /* The SCM_DEPRECATED macro is used in declarations of deprecated 738 functions or variables. Defining `SCM_BUILDING_DEPRECATED_CODE' 739 allows deprecated functions to be implemented in terms of deprecated 740 functions, and allows deprecated functions to be referred to by 741 `scm_c_define_gsubr ()'. */ 742 #if !defined (SCM_BUILDING_DEPRECATED_CODE) && defined __GNUC__ 743 # define SCM_DEPRECATED SCM_API __attribute__ ((__deprecated__)) 744 #else 745 # define SCM_DEPRECATED SCM_API 746 #endif 747 748 /* The SCM_NORETURN macro indicates that a function will never return. 749 Examples: 750 1) int foo (char arg) SCM_NORETURN; */ 751 #ifdef __GNUC__ 752 # define SCM_NORETURN __attribute__ ((__noreturn__)) 753 #else 754 # define SCM_NORETURN 755 #endif 756 757 /* The SCM_UNUSED macro indicates that a function, function argument or 758 variable may potentially be unused. 759 Examples: 760 1) static int unused_function (char arg) SCM_UNUSED; 761 2) int foo (char unused_argument SCM_UNUSED); 762 3) int unused_variable SCM_UNUSED; */ 763 #ifdef __GNUC__ 764 # define SCM_UNUSED __attribute__ ((unused)) 765 #else 766 # define SCM_UNUSED 767 #endif 768 769 /* The SCM_MALLOC macro can be used in function declarations to tell the 770 compiler that a function may be treated as if any non-NULL pointer it 771 returns cannot alias any other pointer valid when the function 772 returns. */ 773 #ifdef __GNUC__ 774 # define SCM_MALLOC __attribute__ ((__malloc__)) 775 #else 776 # define SCM_MALLOC 777 #endif 778 779 /* The SCM_EXPECT macros provide branch prediction hints to the 780 compiler. To use only in places where the result of the expression 781 under "normal" circumstances is known. */ 782 #ifdef __GNUC__ 783 # define SCM_EXPECT __builtin_expect 784 #else 785 # define SCM_EXPECT(_expr, _value) (_expr) 786 #endif 787 788 #define SCM_LIKELY(_expr) SCM_EXPECT ((_expr), 1) 789 #define SCM_UNLIKELY(_expr) SCM_EXPECT ((_expr), 0) 790 791 /* The SCM_ALIGNED macro, when defined, can be used to instruct the 792 compiler to honor the given alignment constraint. Sun Studio 793 supports alignment since Sun Studio 12. */ 794 #if defined __GNUC__ || (defined( __SUNPRO_C ) && (__SUNPRO_C - 0 >= 0x590)) 795 # define SCM_ALIGNED(x) __attribute__ ((aligned (x))) 796 #elif defined __INTEL_COMPILER 797 # define SCM_ALIGNED(x) __declspec (align (x)) 798 #else 799 # undef SCM_ALIGNED 800 #endif 801 802 /* Thread-local storage (TLS). */ 803 #ifdef SCM_HAVE_THREAD_STORAGE_CLASS 804 # define SCM_THREAD_LOCAL __thread 805 #else 806 # define SCM_THREAD_LOCAL 807 #endif 808 809 810 811 812 /* The type of subrs, i.e., Scheme procedures implemented in C. Empty 813 function declarators are used internally for pointers to functions of 814 any arity. However, these are equivalent to `(void)' in C++, are 815 obsolescent as of C99, and trigger `strict-prototypes' GCC warnings 816 (bug #23681). */ 817 #ifdef BUILDING_LIBGUILE 818 typedef SCM (* scm_t_subr) (); 819 #else 820 typedef void *scm_t_subr; 821 #endif 822 823 typedef struct scm_dynamic_state scm_t_dynamic_state; 824 typedef struct scm_print_state scm_print_state; 825 typedef struct scm_dynstack scm_t_dynstack; 826 typedef int32_t scm_t_wchar; 827 struct scm_frame; 828 struct scm_vm; 829 union scm_vm_stack_element; 830 typedef struct scm_thread scm_thread; 831 832 833 834 #ifdef CHAR_BIT 835 # define SCM_CHAR_BIT CHAR_BIT 836 #else 837 # define SCM_CHAR_BIT 8 838 #endif 839 840 #ifdef LONG_BIT 841 # define SCM_LONG_BIT LONG_BIT 842 #else 843 # define SCM_LONG_BIT (SCM_SIZEOF_LONG * 8) 844 #endif 845 846 847 848 /* Cast pointer through (void *) in order to avoid compiler warnings 849 when strict aliasing is enabled */ 850 typedef long SCM_STACKITEM; 851 #define SCM_STACK_PTR(ptr) ((SCM_STACKITEM *) (void *) (ptr)) 852 853 854 #endif /* SCM_SCM_H */ 855