src/backtrace.h

   1 /* The lisp stack.
   2    Copyright (C) 1985, 1986, 1987, 1992, 1993 Free Software Foundation, Inc.
   3
   4 This file is part of XEmacs.
   5
   6 XEmacs is free software; you can redistribute it and/or modify it
   7 under the terms of the GNU General Public License as published by the
   8 Free Software Foundation; either version 2, or (at your option) any
   9 later version.
  10
  11 XEmacs is distributed in the hope that it will be useful, but WITHOUT
  12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14 for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with XEmacs; see the file COPYING.  If not, write to
  18 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19 Boston, MA 02111-1307, USA.  */
  20
  21 /* Synched up with: FSF 19.30.  Contained redundantly in various C files
  22    in FSFmacs. */
  23
  24 /* Authorship:
  25
  26    FSF: Original version; a long time ago.
  27    XEmacs: split out of some C files. (For some obscure reason, a header
  28            file couldn't be used in FSF Emacs, but XEmacs doesn't have
  29            that problem.)
  30    Mly (probably) or JWZ: Some changes.
  31  */
  32
  33 #ifndef INCLUDED_backtrace_h_
  34 #define INCLUDED_backtrace_h_
  35
  36 #include <setjmp.h>
  37
  38 /* These definitions are used in eval.c and alloc.c */
  39
  40 struct backtrace
  41   {
  42     struct backtrace *next;
  43     Lisp_Object *function;
  44     Lisp_Object *args;          /* Points to vector of args. */
  45     int nargs;                  /* Length of vector.
  46                                    If nargs is UNEVALLED, args points to
  47                                    slot holding list of unevalled args */
  48     int pdlcount;               /* specpdl_depth () when invoked */
  49     char evalargs;
  50     /* Nonzero means call value of debugger when done with this operation. */
  51     char debug_on_exit;
  52   };
  53
  54 /* This structure helps implement the `catch' and `throw' control
  55    structure.  A struct catchtag contains all the information needed
  56    to restore the state of the interpreter after a non-local jump.
  57
  58    Handlers for error conditions (represented by `struct handler'
  59    structures) just point to a catch tag to do the cleanup required
  60    for their jumps.
  61
  62    catchtag structures are chained together in the C calling stack;
  63    the `next' member points to the next outer catchtag.
  64
  65    A call like (throw TAG VAL) searches for a catchtag whose `tag'
  66    member is TAG, and then unbinds to it.  The `val' member is used to
  67    hold VAL while the stack is unwound; `val' is returned as the value
  68    of the catch form.
  69
  70    All the other members are concerned with restoring the interpreter
  71    state.  */
  72
  73 struct catchtag
  74   {
  75     Lisp_Object tag;
  76     Lisp_Object val;
  77     struct catchtag *next;
  78     struct gcpro *gcpro;
  79     JMP_BUF jmp;
  80     struct backtrace *backlist;
  81 #if 0 /* FSFmacs */
  82     /* #### */
  83     struct handler *handlerlist;
  84 #endif
  85     int lisp_eval_depth;
  86     int pdlcount;
  87 #if 0 /* FSFmacs */
  88     /* This is the equivalent of async_timer_suppress_count.
  89        We probably don't have to bother with this. */
  90     int poll_suppress_count;
  91 #endif
  92   };
  93
  94 /* Dynamic-binding-o-rama */
  95
  96 /* Structure for recording Lisp call stack for backtrace purposes.  */
  97
  98 /* The special binding stack holds the outer values of variables while
  99    they are bound by a function application or a let form, stores the
 100    code to be executed for Lisp unwind-protect forms, and stores the C
 101    functions to be called for record_unwind_protect.
 102
 103    If func is non-zero, undoing this binding applies func to old_value;
 104       This implements record_unwind_protect.
 105    If func is zero and symbol is nil, undoing this binding evaluates
 106       the list of forms in old_value; this implements Lisp's unwind-protect
 107       form.
 108    Otherwise, undoing this binding stores old_value as symbol's value; this
 109       undoes the bindings made by a let form or function call.  */
 110
 111 struct specbinding
 112   {
 113     Lisp_Object symbol;
 114     Lisp_Object old_value;
 115     Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
 116   };
 117
 118 #if 0 /* FSFmacs */
 119 /* #### */
 120 /* Everything needed to describe an active condition case.  */
 121 struct handler
 122   {
 123     /* The handler clauses and variable from the condition-case form.  */
 124     Lisp_Object handler;
 125     Lisp_Object var;
 126     /* Fsignal stores here the condition-case clause that applies,
 127        and Fcondition_case thus knows which clause to run.  */
 128     Lisp_Object chosen_clause;
 129
 130     /* Used to effect the longjmp() out to the handler.  */
 131     struct catchtag *tag;
 132
 133     /* The next enclosing handler.  */
 134     struct handler *next;
 135   };
 136
 137 extern struct handler *handlerlist;
 138
 139 #endif
 140
 141 /* These are extern because GC needs to mark them */
 142 extern struct specbinding *specpdl;
 143 extern struct specbinding *specpdl_ptr;
 144 extern struct catchtag *catchlist;
 145 extern struct backtrace *backtrace_list;
 146
 147 /* Most callers should simply use specbind() and unbind_to(), but if
 148    speed is REALLY IMPORTANT, you can use the faster macros below */
 149 void specbind_magic (Lisp_Object, Lisp_Object);
 150 void grow_specpdl (EMACS_INT reserved);
 151 void unbind_to_hairy (int);
 152 extern int specpdl_size;
 153
 154 /* Inline version of specbind().
 155    Use this instead of specbind() if speed is sufficiently important
 156    to save the overhead of even a single function call. */
 157 #define SPECBIND(symbol_object, value_object) do {                      \
 158   Lisp_Object SB_symbol = (symbol_object);                              \
 159   Lisp_Object SB_newval = (value_object);                               \
 160   Lisp_Object SB_oldval;                                                \
 161   Lisp_Symbol *SB_sym;                                                  \
 162                                                                         \
 163   SPECPDL_RESERVE (1);                                                  \
 164                                                                         \
 165   CHECK_SYMBOL (SB_symbol);                                             \
 166   SB_sym = XSYMBOL (SB_symbol);                                         \
 167   SB_oldval = SB_sym->value;                                            \
 168                                                                         \
 169   if (!SYMBOL_VALUE_MAGIC_P (SB_oldval) || UNBOUNDP (SB_oldval))        \
 170     {                                                                   \
 171       /* #### the following test will go away when we have a constant   \
 172          symbol magic object */                                         \
 173       if (EQ (SB_symbol, Qnil) ||                                       \
 174           EQ (SB_symbol, Qt)   ||                                       \
 175           SYMBOL_IS_KEYWORD (SB_symbol))                                \
 176         reject_constant_symbols (SB_symbol, SB_newval, 0,               \
 177                                  UNBOUNDP (SB_newval) ?                 \
 178                                  Qmakunbound : Qset);                   \
 179                                                                         \
 180       specpdl_ptr->symbol    = SB_symbol;                               \
 181       specpdl_ptr->old_value = SB_oldval;                               \
 182       specpdl_ptr->func      = 0;                                       \
 183       specpdl_ptr++;                                                    \
 184       specpdl_depth_counter++;                                          \
 185                                                                         \
 186       SB_sym->value = (SB_newval);                                      \
 187     }                                                                   \
 188   else                                                                  \
 189     specbind_magic (SB_symbol, SB_newval);                              \
 190 } while (0)
 191
 192 /* An even faster, but less safe inline version of specbind().
 193    Caller guarantees that:
 194    - SYMBOL is a non-constant symbol (i.e. not Qnil, Qt, or keyword).
 195    - specpdl_depth_counter >= specpdl_size.
 196    Else we crash.  */
 197 #define SPECBIND_FAST_UNSAFE(symbol_object, value_object) do {          \
 198   Lisp_Object SFU_symbol = (symbol_object);                             \
 199   Lisp_Object SFU_newval = (value_object);                              \
 200   Lisp_Symbol *SFU_sym   = XSYMBOL (SFU_symbol);                        \
 201   Lisp_Object SFU_oldval = SFU_sym->value;                              \
 202   if (!SYMBOL_VALUE_MAGIC_P (SFU_oldval) || UNBOUNDP (SFU_oldval))      \
 203     {                                                                   \
 204       specpdl_ptr->symbol    = SFU_symbol;                              \
 205       specpdl_ptr->old_value = SFU_oldval;                              \
 206       specpdl_ptr->func      = 0;                                       \
 207       specpdl_ptr++;                                                    \
 208       specpdl_depth_counter++;                                          \
 209                                                                         \
 210       SFU_sym->value = (SFU_newval);                                    \
 211     }                                                                   \
 212   else                                                                  \
 213     specbind_magic (SFU_symbol, SFU_newval);                            \
 214 } while (0)
 215
 216 /* Request enough room for SIZE future entries on special binding stack */
 217 /* SR_size will typically be compared to an unsigned short */
 218 #define SPECPDL_RESERVE(size) do {                      \
 219   EMACS_INT SR_size = (size);                           \
 220   if (specpdl_depth() + SR_size >= specpdl_size)        \
 221     grow_specpdl (SR_size);                             \
 222 } while (0)
 223
 224 /* Inline version of unbind_to().
 225    Use this instead of unbind_to() if speed is sufficiently important
 226    to save the overhead of even a single function call.
 227
 228    Most of the time, unbind_to() is called only on ordinary
 229    variables, so optimize for that.  */
 230 #define UNBIND_TO_GCPRO(count, value) do {              \
 231   int UNBIND_TO_count = (count);                        \
 232   while (specpdl_depth_counter != UNBIND_TO_count)      \
 233     {                                                   \
 234       Lisp_Symbol *sym;                                 \
 235       --specpdl_ptr;                                    \
 236       --specpdl_depth_counter;                          \
 237                                                         \
 238       if (specpdl_ptr->func != 0 ||                     \
 239           ((sym = XSYMBOL (specpdl_ptr->symbol)),       \
 240            SYMBOL_VALUE_MAGIC_P (sym->value)))          \
 241         {                                               \
 242           struct gcpro gcpro1;                          \
 243           GCPRO1 (value);                               \
 244           unbind_to_hairy (UNBIND_TO_count);            \
 245           UNGCPRO;                                      \
 246           break;                                        \
 247         }                                               \
 248                                                         \
 249       sym->value = specpdl_ptr->old_value;              \
 250     }                                                   \
 251 } while (0)
 252
 253 /* A slightly faster inline version of unbind_to,
 254    that doesn't offer GCPROing services. */
 255 #define UNBIND_TO(count) do {                           \
 256   int UNBIND_TO_count = (count);                        \
 257   while (specpdl_depth_counter != UNBIND_TO_count)      \
 258     {                                                   \
 259       Lisp_Symbol *sym;                                 \
 260       --specpdl_ptr;                                    \
 261       --specpdl_depth_counter;                          \
 262                                                         \
 263       if (specpdl_ptr->func != 0 ||                     \
 264           ((sym = XSYMBOL (specpdl_ptr->symbol)),       \
 265            SYMBOL_VALUE_MAGIC_P (sym->value)))          \
 266         {                                               \
 267           unbind_to_hairy (UNBIND_TO_count);            \
 268           break;                                        \
 269         }                                               \
 270                                                         \
 271       sym->value = specpdl_ptr->old_value;              \
 272     }                                                   \
 273 } while (0)
 274
 275 #ifdef ERROR_CHECK_TYPECHECK
 276 #define CHECK_SPECBIND_VARIABLE assert (specpdl_ptr->func == 0)
 277 #else
 278 #define CHECK_SPECBIND_VARIABLE DO_NOTHING
 279 #endif
 280
 281 #if 0
 282 /* Unused.  It's too hard to guarantee that the current bindings
 283    contain only variables.  */
 284 /* Another inline version of unbind_to().  VALUE is GC-protected.
 285    Caller guarantees that:
 286    - all of the elements on the binding stack are variable bindings.
 287    Else we crash.  */
 288 #define UNBIND_TO_GCPRO_VARIABLES_ONLY(count, value) do {       \
 289   int UNBIND_TO_count = (count);                                \
 290   while (specpdl_depth_counter != UNBIND_TO_count)              \
 291     {                                                           \
 292       Lisp_Symbol *sym;                                         \
 293       --specpdl_ptr;                                            \
 294       --specpdl_depth_counter;                                  \
 295                                                                 \
 296       CHECK_SPECBIND_VARIABLE;                                  \
 297       sym = XSYMBOL (specpdl_ptr->symbol);                      \
 298       if (!SYMBOL_VALUE_MAGIC_P (sym->value))                   \
 299         sym->value = specpdl_ptr->old_value;                    \
 300       else                                                      \
 301         {                                                       \
 302           struct gcpro gcpro1;                                  \
 303           GCPRO1 (value);                                       \
 304           unbind_to_hairy (UNBIND_TO_count);                    \
 305           UNGCPRO;                                              \
 306           break;                                                \
 307         }                                                       \
 308     }                                                           \
 309 } while (0)
 310 #endif /* unused */
 311
 312 /* A faster, but less safe inline version of Fset().
 313    Caller guarantees that:
 314    - SYMBOL is a non-constant symbol (i.e. not Qnil, Qt, or keyword).
 315    Else we crash.  */
 316 #define FSET_FAST_UNSAFE(sym, newval) do {                              \
 317   Lisp_Object FFU_sym = (sym);                                          \
 318   Lisp_Object FFU_newval = (newval);                                    \
 319   Lisp_Symbol *FFU_symbol = XSYMBOL (FFU_sym);                          \
 320   Lisp_Object FFU_oldval = FFU_symbol->value;                           \
 321   if (!SYMBOL_VALUE_MAGIC_P (FFU_oldval) || UNBOUNDP (FFU_oldval))      \
 322     FFU_symbol->value = FFU_newval;                                     \
 323   else                                                                  \
 324     Fset (FFU_sym, FFU_newval);                                         \
 325 } while (0)
 326
 327 #endif /* INCLUDED_backtrace_h_ */