diff options
Diffstat (limited to 'doc/lispref/internals.texi')
| -rw-r--r-- | doc/lispref/internals.texi | 64 |
1 files changed, 55 insertions, 9 deletions
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index bfc9d491c5e..092ec003fb5 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -14,6 +14,7 @@ internal aspects of GNU Emacs that may be of interest to C programmers. * Building Emacs:: How the dumped Emacs is made. * Pure Storage:: Kludge to make preloaded Lisp functions shareable. * Garbage Collection:: Reclaiming space for Lisp objects no longer used. +* Stack-allocated Objects:: Temporary conses and strings on C stack. * Memory Usage:: Info about total size of Lisp objects made so far. * C Dialect:: What C variant Emacs is written in. * Writing Emacs Primitives:: Writing C code for Emacs. @@ -513,6 +514,11 @@ created in this Emacs session. Each of these counters increments for a certain kind of object. See the documentation string for details. @end defun +@defun memory-info +This functions returns an amount of total system memory and how much +of it is free. On an unsupported system, the value may be @code{nil}. +@end defun + @defvar gcs-done This variable contains the total number of garbage collections done so far in this Emacs session. @@ -524,6 +530,35 @@ during garbage collection so far in this Emacs session, as a floating-point number. @end defvar +@node Stack-allocated Objects +@section Stack-allocated Objects + +@cindex stack allocated Lisp objects +@cindex Lisp objects, stack-allocated + The garbage collector described above is used to manage data visible +from Lisp programs, as well as most of the data internally used by the +Lisp interpreter. Sometimes it may be useful to allocate temporary +internal objects using the C stack of the interpreter. This can help +performance, as stack allocation is typically faster than using heap +memory to allocate and the garbage collector to free. The downside is +that using such objects after they are freed results in undefined +behavior, so uses should be well thought out and carefully debugged by +using the @code{GC_CHECK_MARKED_OBJECTS} feature (see +@file{src/alloc.c}). In particular, stack-allocated objects should +never be made visible to user Lisp code. + + Currently, cons cells and strings can be allocated this way. This +is implemented by C macros like @code{AUTO_CONS} and +@code{AUTO_STRING} that define a named @code{Lisp_Object} with block +lifetime. These objects are not freed by the garbage collector; +instead, they have automatic storage duration, i.e., they are +allocated like local variables and are automatically freed at the end +of execution of the C block that defined the object. + + For performance reasons, stack-allocated strings are limited to +@acronym{ASCII} characters, and many of these strings are immutable, +i.e., calling @code{ASET} on them produces undefined behavior. + @node Memory Usage @section Memory Usage @cindex memory usage @@ -580,15 +615,14 @@ Emacs session. @section C Dialect @cindex C programming language -The C part of Emacs is portable to C89: C99-specific features such as -@samp{<stdbool.h>} and @samp{inline} are not used without a check, +The C part of Emacs is portable to C99 or later: C11-specific features such +as @samp{<stdalign.h>} and @samp{_Noreturn} are not used without a check, typically at configuration time, and the Emacs build procedure -provides a substitute implementation if necessary. Some C99 features, -such as declarations after statements, are too difficult to provide -substitutes for, so they are avoided entirely. +provides a substitute implementation if necessary. Some C11 features, +such as anonymous structures and unions, are too difficult to emulate, +so they are avoided entirely. -At some point in the not-too-distant future the base C dialect will -change from C89 to C99, and eventually it will no doubt change to C11. +At some point in the future the base C dialect will no doubt change to C11. @node Writing Emacs Primitives @section Writing Emacs Primitives @@ -1591,6 +1625,8 @@ of @code{intptr_t}). @item Prefer @code{int} for Emacs character codes, in the range 0 ..@: 0x3FFFFF. +More generally, prefer @code{int} for integers known to be in +@code{int} range, e.g., screen column counts. @item Prefer @code{ptrdiff_t} for sizes, i.e., for integers bounded by the @@ -1602,6 +1638,17 @@ anyway since they would break pointer subtraction, so this does not impose an arbitrary limit. @item +Avoid @code{ssize_t} except when communicating to low-level APIs that +have @code{ssize_t}-related limitations. Although it's equivalent to +@code{ptrdiff_t} on typical platforms, @code{ssize_t} is occasionally +narrower, so using it for size-related calculations could overflow. +Also, @code{ptrdiff_t} is more ubiquitous and better-standardized, has +standard @code{printf} formats, and is the basis for Emacs's internal +size-overflow checking. When using @code{ssize_t}, please note that +POSIX requires support only for values in the range @minus{}1 ..@: +@code{SSIZE_MAX}. + +@item Prefer @code{intptr_t} for internal representations of pointers, or for integers bounded only by the number of objects that can exist at any given time or by the total number of bytes that can be allocated. @@ -1637,8 +1684,7 @@ using @code{int}. Although it is also OK to use @code{int}, @code{0} and @code{1}, this older style is gradually being phased out. When using @code{bool}, respect the limitations of the replacement implementation of @code{bool}, as documented in the source file -@file{lib/stdbool.in.h}, so that Emacs remains portable to pre-C99 -platforms. In particular, boolean bitfields should be of type +@file{lib/stdbool.in.h}. In particular, boolean bitfields should be of type @code{bool_bf}, not @code{bool}, so that they work correctly even when compiling Objective C with standard GCC. |