X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Finternals.info-2;h=14bf7991456785a394204ef8cbbffb71515f9eb3;hb=b28ac6243eea138748b859a3a70e99f0853d725b;hp=e8fe7d4e7c94e9ac723e2b5ca8309ee00751cf37;hpb=3890a2e3064a7f562107c58e59d928284ec04741;p=chise%2Fxemacs-chise.git- diff --git a/info/internals.info-2 b/info/internals.info-2 index e8fe7d4..14bf799 100644 --- a/info/internals.info-2 +++ b/info/internals.info-2 @@ -1,4 +1,4 @@ -This is ../info/internals.info, produced by makeinfo version 4.0 from +This is ../info/internals.info, produced by makeinfo version 4.0b from internals/internals.texi. INFO-DIR-SECTION XEmacs Editor @@ -410,11 +410,11 @@ representation stuffs a pointer together with a tag, as follows: A tag of 00 is used for all pointer object types, a tag of 10 is used for characters, and the other two tags 01 and 11 are joined together to -form the integer object type. This representation gives us 31 bits -integers, 30 bits characters and pointers are represented directly -without any bit masking. This representation, though, assumes that -pointers to structs are always aligned to multiples of 4, so the lower 2 -bits are always zero. +form the integer object type. This representation gives us 31 bit +integers and 30 bit characters, while pointers are represented directly +without any bit masking or shifting. This representation, though, +assumes that pointers to structs are always aligned to multiples of 4, +so the lower 2 bits are always zero. Lisp objects use the typedef `Lisp_Object', but the actual C type used for the Lisp object can vary. It can be either a simple type @@ -425,24 +425,23 @@ because it ensures that the compiler will actually use a machine word to represent the object (some compilers will use more general and less efficient code for unions and structs even if they can fit in a machine word). The union type, however, has the advantage of stricter type -checking (if you accidentally pass an integer where a Lisp object is -desired, you get a compile error), and it makes it easier to decode -Lisp objects when debugging. The choice of which type to use is +checking. If you accidentally pass an integer where a Lisp object is +desired, you get a compile error. The choice of which type to use is determined by the preprocessor constant `USE_UNION_TYPE' which is defined via the `--use-union-type' option to `configure'. - Various macros are used to construct Lisp objects and extract the -components. Macros of the form `XINT()', `XCHAR()', `XSTRING()', -`XSYMBOL()', etc. shift out the tag field if needed cast it to the -appropriate type. `XINT()' needs to be a bit tricky so that negative -numbers are properly sign-extended. Since integers are stored -left-shifted, if the right-shift operator does an arithmetic shift -(i.e. it leaves the most-significant bit as-is rather than shifting in -a zero, so that it mimics a divide-by-two even for negative numbers) -the shift to remove the tag bit is enough. This is the case on all the -systems we support. - - Note that when `ERROR_CHECK_TYPECHECK' is defined, the extractor + Various macros are used to convert between Lisp_Objects and the +corresponding C type. Macros of the form `XINT()', `XCHAR()', +`XSTRING()', `XSYMBOL()', do any required bit shifting and/or masking +and cast it to the appropriate type. `XINT()' needs to be a bit tricky +so that negative numbers are properly sign-extended. Since integers +are stored left-shifted, if the right-shift operator does an arithmetic +shift (i.e. it leaves the most-significant bit as-is rather than +shifting in a zero, so that it mimics a divide-by-two even for negative +numbers) the shift to remove the tag bit is enough. This is the case +on all the systems we support. + + Note that when `ERROR_CHECK_TYPECHECK' is defined, the converter macros become more complicated--they check the tag bits and/or the type field in the first four bytes of a record type to ensure that the object is really of the correct type. This is great for catching places @@ -454,22 +453,24 @@ unpredictable (and sometimes not easily traceable) results. These macros are of the form `XSETTYPE (LVALUE, RESULT)', i.e. they have to be a statement rather than just used in an expression. The reason for this is that standard C doesn't let you "construct" a -structure (but GCC does). Granted, this sometimes isn't too convenient; -for the case of integers, at least, you can use the function -`make_int()', which constructs and _returns_ an integer Lisp object. -Note that the `XSETTYPE()' macros are also affected by +structure (but GCC does). Granted, this sometimes isn't too +convenient; for the case of integers, at least, you can use the +function `make_int()', which constructs and _returns_ an integer Lisp +object. Note that the `XSETTYPE()' macros are also affected by `ERROR_CHECK_TYPECHECK' and make sure that the structure is of the right type in the case of record types, where the type is contained in the structure. The C programmer is responsible for *guaranteeing* that a -Lisp_Object is is the correct type before using the `XTYPE' macros. -This is especially important in the case of lists. Use `XCAR' and -`XCDR' if a Lisp_Object is certainly a cons cell, else use `Fcar()' and -`Fcdr()'. Trust other C code, but not Lisp code. On the other hand, -if XEmacs has an internal logic error, it's better to crash -immediately, so sprinkle "unreachable" `abort()'s liberally about the -source code. +Lisp_Object is the correct type before using the `XTYPE' macros. This +is especially important in the case of lists. Use `XCAR' and `XCDR' if +a Lisp_Object is certainly a cons cell, else use `Fcar()' and `Fcdr()'. +Trust other C code, but not Lisp code. On the other hand, if XEmacs +has an internal logic error, it's better to crash immediately, so +sprinkle `assert()'s and "unreachable" `abort()'s liberally about the +source code. Where performance is an issue, use `type_checking_assert', +`bufpos_checking_assert', and `gc_checking_assert', which do nothing +unless the corresponding configure error checking flag was specified.  File: internals.info, Node: Rules When Writing New C Code, Next: A Summary of the Various XEmacs Modules, Prev: How Lisp Objects Are Represented in C, Up: Top @@ -506,21 +507,6 @@ been found by compiling with C++. The ability to use both C and C++ tools means that a greater variety of development tools are available to the developer. - Almost every module contains a `syms_of_*()' function and a -`vars_of_*()' function. The former declares any Lisp primitives you -have defined and defines any symbols you will be using. The latter -declares any global Lisp variables you have added and initializes global -C variables in the module. For each such function, declare it in -`symsinit.h' and make sure it's called in the appropriate place in -`emacs.c'. *Important*: There are stringent requirements on exactly -what can go into these functions. See the comment in `emacs.c'. The -reason for this is to avoid obscure unwanted interactions during -initialization. If you don't follow these rules, you'll be sorry! If -you want to do anything that isn't allowed, create a -`complex_vars_of_*()' function for it. Doing this is tricky, though: -You have to make sure your function is called at the right time so that -all the initialization dependencies work out. - Every module includes `' (angle brackets so that `--srcdir' works correctly; `config.h' may or may not be in the same directory as the C sources) and `lisp.h'. `config.h' must always be @@ -529,13 +515,30 @@ to ensure that certain tricks played by various `s/' and `m/' files work out correctly. When including header files, always use angle brackets, not double -quotes, except when the file to be included is in the same directory as -the including file. If either file is a generated file, then that is -not likely to be the case. In order to understand why we have this -rule, imagine what happens when you do a build in the source directory -using `./configure' and another build in another directory using -`../work/configure'. There will be two different `config.h' files. -Which one will be used if you `#include "config.h"'? +quotes, except when the file to be included is always in the same +directory as the including file. If either file is a generated file, +then that is not likely to be the case. In order to understand why we +have this rule, imagine what happens when you do a build in the source +directory using `./configure' and another build in another directory +using `../work/configure'. There will be two different `config.h' +files. Which one will be used if you `#include "config.h"'? + + Almost every module contains a `syms_of_*()' function and a +`vars_of_*()' function. The former declares any Lisp primitives you +have defined and defines any symbols you will be using. The latter +declares any global Lisp variables you have added and initializes global +C variables in the module. *Important*: There are stringent +requirements on exactly what can go into these functions. See the +comment in `emacs.c'. The reason for this is to avoid obscure unwanted +interactions during initialization. If you don't follow these rules, +you'll be sorry! If you want to do anything that isn't allowed, create +a `complex_vars_of_*()' function for it. Doing this is tricky, though: +you have to make sure your function is called at the right time so that +all the initialization dependencies work out. + + Declare each function of these kinds in `symsinit.h'. Make sure +it's called in the appropriate place in `emacs.c'. You never need to +include `symsinit.h' directly, because it is included by `lisp.h'. *All global and static variables that are to be modifiable must be declared uninitialized.* This means that you may not use the "declare @@ -574,7 +577,7 @@ them. This awful kludge has been removed in XEmacs because The C source code makes heavy use of C preprocessor macros. One popular macro style is: - #define FOO(var, value) do { \ + #define FOO(var, value) do { \ Lisp_Object FOO_value = (value); \ ... /* compute using FOO_value */ \ (var) = bar; \ @@ -589,9 +592,9 @@ copying a supplied argument into a local variable, so that Lisp lists are popular data structures in the C code as well as in Elisp. There are two sets of macros that iterate over lists. `EXTERNAL_LIST_LOOP_N' should be used when the list has been supplied -by the user, and cannot be trusted to be acyclic and nil-terminated. A -`malformed-list' or `circular-list' error will be generated if the list -being iterated over is not entirely kosher. `LIST_LOOP_N', on the +by the user, and cannot be trusted to be acyclic and `nil'-terminated. +A `malformed-list' or `circular-list' error will be generated if the +list being iterated over is not entirely kosher. `LIST_LOOP_N', on the other hand, is faster and less safe, and can be used only on trusted lists.