Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 5011:865c9a95f21c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
some internals-manual updates -------------------- ChangeLog entries follow: -------------------- man/ChangeLog addition: 2010-02-08 Ben Wing <ben@xemacs.org> * internals/internals.texi (How Lisp Objects Are Represented in C):
author Ben Wing <ben@xemacs.org>
date Mon, 08 Feb 2010 02:03:25 -0600
parents f23cd0184dcf
children c3cc3fa503a2
comparison
equal deleted inserted replaced
5002:0cd784a6ec44 5011:865c9a95f21c
7599 @chapter How Lisp Objects Are Represented in C 7599 @chapter How Lisp Objects Are Represented in C
7600 @cindex Lisp objects are represented in C, how 7600 @cindex Lisp objects are represented in C, how
7601 @cindex objects are represented in C, how Lisp 7601 @cindex objects are represented in C, how Lisp
7602 @cindex represented in C, how Lisp objects are 7602 @cindex represented in C, how Lisp objects are
7603 7603
7604 Lisp objects are represented in C using a 32-bit or 64-bit machine word 7604 Lisp objects are represented in C using a 32-bit or 64-bit machine
7605 (depending on the processor; i.e. DEC Alphas use 64-bit Lisp objects and 7605 word (depending on the processor). The representation stuffs a
7606 most other processors use 32-bit Lisp objects). The representation 7606 pointer together with a tag, as follows:
7607 stuffs a pointer together with a tag, as follows:
7608 7607
7609 @example 7608 @example
7610 [ 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 ] 7609 [ 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 ]
7611 [ 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 ] 7610 [ 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 ]
7612 7611
7622 assumes that pointers to structs are always aligned to multiples of 4, 7621 assumes that pointers to structs are always aligned to multiples of 4,
7623 so the lower 2 bits are always zero. 7622 so the lower 2 bits are always zero.
7624 7623
7625 Lisp objects use the typedef @code{Lisp_Object}, but the actual C type 7624 Lisp objects use the typedef @code{Lisp_Object}, but the actual C type
7626 used for the Lisp object can vary. It can be either a simple type 7625 used for the Lisp object can vary. It can be either a simple type
7627 (@code{long} on the DEC Alpha, @code{int} on other machines) or a 7626 (generally @code{long}) or a structure whose fields are bit fields
7628 structure whose fields are bit fields that line up properly (actually, a 7627 that line up properly (actually, a union of structures is used).
7629 union of structures is used). Generally the simple integral type is 7628 Generally the simple integral type is preferable because it ensures
7630 preferable because it ensures that the compiler will actually use a 7629 that the compiler will actually use a machine word to represent the
7631 machine word to represent the object (some compilers will use more 7630 object (some compilers will use more general and less efficient code
7632 general and less efficient code for unions and structs even if they can 7631 for unions and structs even if they can fit in a machine word). The
7633 fit in a machine word). The union type, however, has the advantage of 7632 union type, however, has the advantage of stricter type checking. If
7634 stricter type checking. If you accidentally pass an integer where a Lisp 7633 you accidentally pass an integer where a Lisp object is desired, you
7635 object is desired, you get a compile error. The choice of which type 7634 get a compile error. The choice of which type to use is determined by
7636 to use is determined by the preprocessor constant @code{USE_UNION_TYPE} 7635 the preprocessor constant @code{USE_UNION_TYPE} which is defined via
7637 which is defined via the @code{--use-union-type} option to 7636 the @code{--use-union-type} option to @code{configure}.
7638 @code{configure}.
7639 7637
7640 Various macros are used to convert between Lisp_Objects and the 7638 Various macros are used to convert between Lisp_Objects and the
7641 corresponding C type. Macros of the form @code{XINT()}, @code{XCHAR()}, 7639 corresponding C type. Macros of the form @code{XINT()}, @code{XCHAR()},
7642 @code{XSTRING()}, @code{XSYMBOL()}, do any required bit shifting and/or 7640 @code{XSTRING()}, @code{XSYMBOL()}, do any required bit shifting and/or
7643 masking and cast it to the appropriate type. @code{XINT()} needs to be 7641 masking and cast it to the appropriate type. @code{XINT()} needs to be
7646 arithmetic shift (i.e. it leaves the most-significant bit as-is rather 7644 arithmetic shift (i.e. it leaves the most-significant bit as-is rather
7647 than shifting in a zero, so that it mimics a divide-by-two even for 7645 than shifting in a zero, so that it mimics a divide-by-two even for
7648 negative numbers) the shift to remove the tag bit is enough. This is 7646 negative numbers) the shift to remove the tag bit is enough. This is
7649 the case on all the systems we support. 7647 the case on all the systems we support.
7650 7648
7651 Note that when @code{ERROR_CHECK_TYPECHECK} is defined, the converter 7649 Note that when @code{ERROR_CHECK_TYPES} is defined, the converter
7652 macros become more complicated---they check the tag bits and/or the 7650 macros become more complicated---they check the tag bits and/or the
7653 type field in the first four bytes of a record type to ensure that the 7651 type field in the first four bytes of a record type to ensure that the
7654 object is really of the correct type. This is great for catching places 7652 object is really of the correct type. This is great for catching places
7655 where an incorrect type is being dereferenced---this typically results 7653 where an incorrect type is being dereferenced---this typically results
7656 in a pointer being dereferenced as the wrong type of structure, with 7654 in a pointer being dereferenced as the wrong type of structure, with
7663 doesn't let you ``construct'' a structure (but GCC does). Granted, this 7661 doesn't let you ``construct'' a structure (but GCC does). Granted, this
7664 sometimes isn't too convenient; for the case of integers, at least, you 7662 sometimes isn't too convenient; for the case of integers, at least, you
7665 can use the function @code{make_int()}, which constructs and 7663 can use the function @code{make_int()}, which constructs and
7666 @emph{returns} an integer Lisp object. Note that the 7664 @emph{returns} an integer Lisp object. Note that the
7667 @code{XSET@var{TYPE}()} macros are also affected by 7665 @code{XSET@var{TYPE}()} macros are also affected by
7668 @code{ERROR_CHECK_TYPECHECK} and make sure that the structure is of the 7666 @code{ERROR_CHECK_TYPES} and make sure that the structure is of the
7669 right type in the case of record types, where the type is contained in 7667 right type in the case of record types, where the type is contained in
7670 the structure. 7668 the structure.
7671 7669
7672 The C programmer is responsible for @strong{guaranteeing} that a 7670 The C programmer is responsible for @strong{guaranteeing} that a
7673 Lisp_Object is the correct type before using the @code{X@var{TYPE}} 7671 Lisp_Object is the correct type before using the @code{X@var{TYPE}}
7674 macros. This is especially important in the case of lists. Use 7672 macros. This is especially important in the case of lists. Use
7675 @code{XCAR} and @code{XCDR} if a Lisp_Object is certainly a cons cell, 7673 @code{XCAR} and @code{XCDR} if a Lisp_Object is certainly a cons cell,
7676 else use @code{Fcar()} and @code{Fcdr()}. Trust other C code, but not 7674 else use @code{Fcar()} and @code{Fcdr()}. Trust other C code, but not
7677 Lisp code. On the other hand, if XEmacs has an internal logic error, 7675 Lisp code. On the other hand, if XEmacs has an internal logic error,
7678 it's better to crash immediately, so sprinkle @code{assert()}s and 7676 it's better to crash immediately, so sprinkle @code{assert()}s and
7679 ``unreachable'' @code{abort()}s liberally about the source code. Where 7677 ``unreachable'' @code{abort()}s liberally about the source code.
7680 performance is an issue, use @code{type_checking_assert}, 7678 Where performance is an issue, use @code{type_checking_assert},
7681 @code{bufpos_checking_assert}, and @code{gc_checking_assert}, which do 7679 @code{bufpos_checking_assert}, @code{gc_checking_assert}, and the
7682 nothing unless the corresponding configure error checking flag was 7680 like, which do nothing unless the corresponding configure error
7683 specified. 7681 checking flag was specified.
7684
7685 Note that in some cases @samp{assert}s will expand to nothing in a
7686 context where that produces an empty statement. Some compilers will
7687 warn about this.
7688 7682
7689 @node Allocation of Objects in XEmacs Lisp, The Lisp Reader and Compiler, How Lisp Objects Are Represented in C, Top 7683 @node Allocation of Objects in XEmacs Lisp, The Lisp Reader and Compiler, How Lisp Objects Are Represented in C, Top
7690 @chapter Allocation of Objects in XEmacs Lisp 7684 @chapter Allocation of Objects in XEmacs Lisp
7691 @cindex allocation of objects in XEmacs Lisp 7685 @cindex allocation of objects in XEmacs Lisp
7692 @cindex objects in XEmacs Lisp, allocation of 7686 @cindex objects in XEmacs Lisp, allocation of