/[emacs]/emacs/lispref/internals.texi
ViewVC logotype

Diff of /emacs/lispref/internals.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.24.4.1 by miles, Fri Apr 4 06:20:41 2003 UTC revision 1.24.4.2 by miles, Tue Oct 14 23:10:12 2003 UTC
# Line 339  beginning and end of garbage collection. Line 339  beginning and end of garbage collection.
339  @code{nil}, meaning there are no such messages.  @code{nil}, meaning there are no such messages.
340  @end defopt  @end defopt
341    
342    @defvar post-gc-hook
343    This is a normal hook that is run at the end of garbage collection.
344    Garbage collection is inhibited while the hook functions run, so be
345    careful writing them.
346    @end defvar
347    
348  @defopt gc-cons-threshold  @defopt gc-cons-threshold
349  The value of this variable is the number of bytes of storage that must  The value of this variable is the number of bytes of storage that must
350  be allocated for Lisp objects after one garbage collection in order to  be allocated for Lisp objects after one garbage collection in order to
# Line 376  You can use this to get a general idea o Line 382  You can use this to get a general idea o
382  memory usage.  memory usage.
383  @end defun  @end defun
384    
385    @defvar gcs-done
386    This variable contains the total number of garbage collections
387    done so far in this Emacs session.
388    @end defvar
389    
390    @defvar gc-elapsed
391    This variable contains the total number of seconds of elapsed time
392    during garbage collection so far in this Emacs session, as a floating
393    point number.
394    @end defvar
395    
396  @node Memory Usage  @node Memory Usage
397  @section Memory Usage  @section Memory Usage
398    
# Line 546  If the last line of the documentation st Line 563  If the last line of the documentation st
563  @samp{usage:}, the rest of the line is treated as the argument list  @samp{usage:}, the rest of the line is treated as the argument list
564  for documentation purposes.  This way, you can use different argument  for documentation purposes.  This way, you can use different argument
565  names in the documentation string from the ones used in the C code.  names in the documentation string from the ones used in the C code.
566    @samp{usage:} is required if the function has an unlimited number of
567    arguments.
568    
569  All the usual rules for documentation strings in Lisp code  All the usual rules for documentation strings in Lisp code
570  (@pxref{Documentation Tips}) apply to C code documentation strings  (@pxref{Documentation Tips}) apply to C code documentation strings
# Line 572  Lisp object that you intend to refer to Line 591  Lisp object that you intend to refer to
591  @code{UNGCPRO} cancels the protection of the variables that are  @code{UNGCPRO} cancels the protection of the variables that are
592  protected in the current function.  It is necessary to do this explicitly.  protected in the current function.  It is necessary to do this explicitly.
593    
594    For most data types, it suffices to protect at least one pointer to    It suffices to ensure that at least one pointer to each object is
595  the object; as long as the object is not recycled, all pointers to it  GC-protected; as long as the object is not recycled, all pointers to
596  remain valid.  This is not so for strings, because the garbage collector  it remain valid.  So if you are sure that a local variable points to
597  can move them.  When the garbage collector moves a string, it relocates  an object that will be preserved by some other pointer, that local
598  all the pointers it knows about; any other pointers become invalid.  variable does not need a GCPRO.  (Formerly, strings were an exception
599  Therefore, you must protect all pointers to strings across any point  to this rule; in older Emacs versions, every pointer to a string
600  where garbage collection may be possible.  needed to be marked by GC.)
601    
602    The macro @code{GCPRO1} protects just one local variable.  If you want    The macro @code{GCPRO1} protects just one local variable.  If you
603  to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will  want to protect two, use @code{GCPRO2} instead; repeating
604  not work.  Macros @code{GCPRO3} and @code{GCPRO4} also exist.  @code{GCPRO1} will not work.  Macros, @code{GCPRO3}, @code{GCPRO4},
605    @code{GCPRO5}, and @code{GCPRO6} also exist.  These macros implicitly
606    These macros implicitly use local variables such as @code{gcpro1}; you  use local variables such as @code{gcpro1}; you must declare these
607  must declare these explicitly, with type @code{struct gcpro}.  Thus, if  explicitly, with type @code{struct gcpro}.  Thus, if you use
608  you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.  @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
609  Alas, we can't explain all the tricky details here.  Alas, we can't explain all the tricky details here.
610    
611      Built-in functions that take a variable number of arguments actually
612    accept two arguments at the C level: the number of Lisp arguments, and
613    a @code{Lisp_Object *} pointer to a C vector containing those Lisp
614    arguments.  This C vector may be part of a Lisp vector, but it need
615    not be.  The responsibility for using GCPRO to protecting the Lisp
616    arguments from GC if necessary rests with the caller in this case,
617    since the caller allocated or found the storage for them.
618    
619    You must not use C initializers for static or global variables unless    You must not use C initializers for static or global variables unless
620  the variables are never written once Emacs is dumped.  These variables  the variables are never written once Emacs is dumped.  These variables
621  with initializers are allocated in an area of memory that becomes  with initializers are allocated in an area of memory that becomes
# Line 721  number of arguments.  They work by calli Line 748  number of arguments.  They work by calli
748  @file{lisp.h} contains the definitions for some important macros and  @file{lisp.h} contains the definitions for some important macros and
749  functions.  functions.
750    
751    If you define a function which is side-effect free, update the code in    If you define a function which is side-effect free, update the code
752  @file{byte-opt.el} which binds @code{side-effect-free-fns} and  in @file{byte-opt.el} which binds @code{side-effect-free-fns} and
753  @code{side-effect-and-error-free-fns} to include it.  This will help the  @code{side-effect-and-error-free-fns} so that the compiler optimizer
754  optimizer.  knows about it.
755    
756  @node Object Internals  @node Object Internals
757  @appendixsec Object Internals  @appendixsec Object Internals
# Line 1431  Size of carryover in encoding. Line 1458  Size of carryover in encoding.
1458  Flag to set @code{coding-system} of the process buffer from the  Flag to set @code{coding-system} of the process buffer from the
1459  coding system used to decode process output.  coding system used to decode process output.
1460  @end table  @end table
1461    
1462    @ignore
1463       arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e
1464    @end ignore

Legend:
Removed from v.1.24.4.1  
changed lines
  Added in v.1.24.4.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26