572 |
@code{UNGCPRO} cancels the protection of the variables that are |
@code{UNGCPRO} cancels the protection of the variables that are |
573 |
protected in the current function. It is necessary to do this explicitly. |
protected in the current function. It is necessary to do this explicitly. |
574 |
|
|
575 |
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 |
576 |
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 |
577 |
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 |
578 |
can move them. When the garbage collector moves a string, it relocates |
an object that will be preserved by some other pointer, that local |
579 |
all the pointers it knows about; any other pointers become invalid. |
variable does not need a GCPRO. (Formerly, strings were an exception |
580 |
Therefore, you must protect all pointers to strings across any point |
to this rule; in older Emacs versions, every pointer to a string |
581 |
where garbage collection may be possible. |
needed to be marked by GC.) |
582 |
|
|
583 |
The macro @code{GCPRO1} protects just one local variable. If you want |
The macro @code{GCPRO1} protects just one local variable. If you |
584 |
to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will |
want to protect two, use @code{GCPRO2} instead; repeating |
585 |
not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist. |
@code{GCPRO1} will not work. Macros, @code{GCPRO3}, @code{GCPRO4}, |
586 |
|
@code{GCPRO5}, and @code{GCPRO6} also exist. These macros implicitly |
587 |
These macros implicitly use local variables such as @code{gcpro1}; you |
use local variables such as @code{gcpro1}; you must declare these |
588 |
must declare these explicitly, with type @code{struct gcpro}. Thus, if |
explicitly, with type @code{struct gcpro}. Thus, if you use |
589 |
you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. |
@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. |
590 |
Alas, we can't explain all the tricky details here. |
Alas, we can't explain all the tricky details here. |
591 |
|
|
592 |
|
Built-in functions that take a variable number of arguments actually |
593 |
|
accept two arguments at the C level: the number of Lisp arguments, and |
594 |
|
a @code{Lisp_Object *} pointer to a C vector containing those Lisp |
595 |
|
arguments. This C vector may be part of a Lisp vector, but it need |
596 |
|
not be. The responsibility for protecting the Lisp arguments from GC |
597 |
|
rests with the caller in this case. |
598 |
|
|
599 |
You must not use C initializers for static or global variables unless |
You must not use C initializers for static or global variables unless |
600 |
the variables are never written once Emacs is dumped. These variables |
the variables are never written once Emacs is dumped. These variables |
601 |
with initializers are allocated in an area of memory that becomes |
with initializers are allocated in an area of memory that becomes |