libguile/gc.h

   1 /* classes: h_files */
   2
   3 #ifndef SCM_GC_H
   4 #define SCM_GC_H
   5
   6 /* Copyright (C) 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006,
   7  *   2007, 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 3 of
  12  * the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful, but
  15  * WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  22  * 02110-1301 USA
  23  */
  24
  25 \f
  26
  27 #include "libguile/__scm.h"
  28
  29 #include "libguile/hooks.h"
  30 #include "libguile/threads.h"
  31
  32 \f
  33 typedef struct scm_t_cell
  34 {
  35   SCM word_0;
  36   SCM word_1;
  37 } scm_t_cell;
  38
  39 /* FIXME: deprecate. */
  40 #define PTR2SCM(x) (SCM_PACK_POINTER (x))
  41 #define SCM2PTR(x) ((scm_t_cell *) (SCM_UNPACK_POINTER (x)))
  42
  43 /* Low level cell data accessing macros.  These macros should only be used
  44  * from within code related to garbage collection issues, since they will
  45  * never check the cells they are applied to - not even if guile is compiled
  46  * in debug mode.  In particular these macros will even work for free cells,
  47  * which should never be encountered by user code.  */
  48
  49 #define SCM_GC_CELL_OBJECT(x, n) (((SCM *)SCM2PTR (x)) [n])
  50 #define SCM_GC_CELL_WORD(x, n)   (SCM_UNPACK (SCM_GC_CELL_OBJECT ((x), (n))))
  51
  52 #define SCM_GC_SET_CELL_OBJECT(x, n, v) ((((SCM *)SCM2PTR (x)) [n]) = (v))
  53 #define SCM_GC_SET_CELL_WORD(x, n, v)  \
  54   (SCM_GC_SET_CELL_OBJECT ((x), (n), SCM_PACK (v)))
  55
  56 #define SCM_GC_CELL_TYPE(x) (SCM_GC_CELL_OBJECT ((x), 0))
  57
  58
  59 /* Except for the garbage collector, no part of guile should ever run over a
  60  * free cell.  Thus, if guile is compiled in debug mode the SCM_CELL_* and
  61  * SCM_SET_CELL_* macros below report an error if they are applied to a free
  62  * cell.  Some other plausibility checks are also performed.  However, if
  63  * guile is not compiled in debug mode, there won't be any time penalty at all
  64  * when using these macros.  */
  65
  66 #if (SCM_DEBUG_CELL_ACCESSES == 1)
  67 #  define SCM_VALIDATE_CELL(cell, expr) (scm_assert_cell_valid (cell), (expr))
  68 #else
  69 #  define SCM_VALIDATE_CELL(cell, expr) (expr)
  70 #endif
  71
  72 #define SCM_CELL_WORD(x, n) \
  73   SCM_VALIDATE_CELL ((x), SCM_GC_CELL_WORD ((x), (n)))
  74 #define SCM_CELL_WORD_0(x) SCM_CELL_WORD ((x), 0)
  75 #define SCM_CELL_WORD_1(x) SCM_CELL_WORD ((x), 1)
  76 #define SCM_CELL_WORD_2(x) SCM_CELL_WORD ((x), 2)
  77 #define SCM_CELL_WORD_3(x) SCM_CELL_WORD ((x), 3)
  78
  79 #define SCM_CELL_OBJECT(x, n) \
  80   SCM_VALIDATE_CELL ((x), SCM_GC_CELL_OBJECT ((x), (n)))
  81 #define SCM_CELL_OBJECT_0(x) SCM_CELL_OBJECT ((x), 0)
  82 #define SCM_CELL_OBJECT_1(x) SCM_CELL_OBJECT ((x), 1)
  83 #define SCM_CELL_OBJECT_2(x) SCM_CELL_OBJECT ((x), 2)
  84 #define SCM_CELL_OBJECT_3(x) SCM_CELL_OBJECT ((x), 3)
  85
  86 #define SCM_SET_CELL_WORD(x, n, v) \
  87   SCM_VALIDATE_CELL ((x), SCM_GC_SET_CELL_WORD ((x), (n), (v)))
  88 #define SCM_SET_CELL_WORD_0(x, v) SCM_SET_CELL_WORD ((x), 0, (v))
  89 #define SCM_SET_CELL_WORD_1(x, v) SCM_SET_CELL_WORD ((x), 1, (v))
  90 #define SCM_SET_CELL_WORD_2(x, v) SCM_SET_CELL_WORD ((x), 2, (v))
  91 #define SCM_SET_CELL_WORD_3(x, v) SCM_SET_CELL_WORD ((x), 3, (v))
  92
  93 #define SCM_SET_CELL_OBJECT(x, n, v) \
  94   SCM_VALIDATE_CELL ((x), SCM_GC_SET_CELL_OBJECT ((x), (n), (v)))
  95 #define SCM_SET_CELL_OBJECT_0(x, v) SCM_SET_CELL_OBJECT ((x), 0, (v))
  96 #define SCM_SET_CELL_OBJECT_1(x, v) SCM_SET_CELL_OBJECT ((x), 1, (v))
  97 #define SCM_SET_CELL_OBJECT_2(x, v) SCM_SET_CELL_OBJECT ((x), 2, (v))
  98 #define SCM_SET_CELL_OBJECT_3(x, v) SCM_SET_CELL_OBJECT ((x), 3, (v))
  99
 100 #define SCM_CELL_OBJECT_LOC(x, n) (SCM_VALIDATE_CELL((x), &SCM_GC_CELL_OBJECT ((x), (n))))
 101 #define SCM_CARLOC(x)             (SCM_CELL_OBJECT_LOC ((x), 0))
 102 #define SCM_CDRLOC(x)             (SCM_CELL_OBJECT_LOC ((x), 1))
 103
 104 #define SCM_CELL_TYPE(x) SCM_CELL_WORD_0 (x)
 105 #define SCM_SET_CELL_TYPE(x, t) SCM_SET_CELL_WORD_0 ((x), (t))
 106
 107
 108 #if (SCM_DEBUG_CELL_ACCESSES == 1)
 109 /* Set this to != 0 if every cell that is accessed shall be checked:
 110  */
 111 SCM_API int scm_debug_cell_accesses_p;
 112 SCM_API int scm_expensive_debug_cell_accesses_p;
 113 SCM_API int scm_debug_cells_gc_interval ;
 114 SCM_API void scm_i_expensive_validation_check (SCM cell);
 115 #endif
 116
 117 SCM_INTERNAL scm_i_pthread_mutex_t scm_i_gc_admin_mutex;
 118
 119 #define scm_gc_running_p  0
 120 SCM_INTERNAL scm_i_pthread_mutex_t scm_i_sweep_mutex;
 121
 122 #ifdef __ia64__
 123 void *scm_ia64_register_backing_store_base (void);
 124 void *scm_ia64_ar_bsp (const void *);
 125 #endif
 126
 127 \f
 128
 129 SCM_API unsigned long scm_gc_ports_collected;
 130
 131 SCM_API SCM scm_after_gc_hook;
 132
 133 SCM_API scm_t_c_hook scm_before_gc_c_hook;
 134 SCM_API scm_t_c_hook scm_before_mark_c_hook;
 135 SCM_API scm_t_c_hook scm_before_sweep_c_hook;
 136 SCM_API scm_t_c_hook scm_after_sweep_c_hook;
 137 SCM_API scm_t_c_hook scm_after_gc_c_hook;
 138
 139 \f
 140
 141 #if (SCM_DEBUG_CELL_ACCESSES == 1)
 142 SCM_API void scm_assert_cell_valid (SCM);
 143 #endif
 144
 145 SCM_API SCM scm_set_debug_cell_accesses_x (SCM flag);
 146
 147
 148 SCM_API SCM scm_object_address (SCM obj);
 149 SCM_API SCM scm_gc_enable (void);
 150 SCM_API SCM scm_gc_disable (void);
 151 SCM_API SCM scm_gc_dump (void);
 152 SCM_API SCM scm_gc_stats (void);
 153 SCM_API SCM scm_gc_live_object_stats (void);
 154 SCM_API SCM scm_gc (void);
 155 SCM_INTERNAL void scm_i_gc (const char *what);
 156 SCM_API void scm_gc_mark (SCM p);
 157 SCM_API void scm_gc_sweep (void);
 158
 159 SCM_API void scm_gc_register_allocation (size_t size);
 160
 161 SCM_API void *scm_malloc (size_t size) SCM_MALLOC;
 162 SCM_API void *scm_calloc (size_t size) SCM_MALLOC;
 163 SCM_API void *scm_realloc (void *mem, size_t size);
 164 SCM_API char *scm_strdup (const char *str) SCM_MALLOC;
 165 SCM_API char *scm_strndup (const char *str, size_t n) SCM_MALLOC;
 166 SCM_API void scm_gc_register_collectable_memory (void *mem, size_t size,
 167                                                  const char *what);
 168 SCM_API void scm_gc_unregister_collectable_memory (void *mem, size_t size,
 169                                                    const char *what);
 170 SCM_API void *scm_gc_malloc_pointerless (size_t size, const char *what)
 171   SCM_MALLOC;
 172 SCM_API void *scm_gc_calloc (size_t size, const char *what)
 173   SCM_MALLOC;
 174 SCM_API void *scm_gc_malloc (size_t size, const char *what)
 175   SCM_MALLOC;
 176 SCM_API void *scm_gc_realloc (void *mem, size_t old_size,
 177                               size_t new_size, const char *what);
 178 SCM_API void scm_gc_free (void *mem, size_t size, const char *what);
 179 SCM_API char *scm_gc_strdup (const char *str, const char *what)
 180   SCM_MALLOC;
 181 SCM_API char *scm_gc_strndup (const char *str, size_t n, const char *what)
 182   SCM_MALLOC;
 183
 184 #define scm_gc_typed_calloc(t) ((t *) scm_gc_calloc (sizeof (t), #t))
 185
 186 #ifdef BUILDING_LIBGUILE
 187 #include "libguile/bdw-gc.h"
 188 #define SCM_GC_MALLOC(size) GC_MALLOC (size)
 189 #define SCM_GC_MALLOC_POINTERLESS(size) GC_MALLOC_ATOMIC (size)
 190 #else
 191 #define SCM_GC_MALLOC(size) scm_gc_malloc (size, NULL)
 192 #define SCM_GC_MALLOC_POINTERLESS(size) scm_gc_malloc_pointerless (size, NULL)
 193 #endif
 194
 195
 196 SCM_INLINE SCM scm_cell (scm_t_bits car, scm_t_bits cdr);
 197 SCM_INLINE SCM scm_double_cell (scm_t_bits car, scm_t_bits cbr,
 198                              scm_t_bits ccr, scm_t_bits cdr);
 199 SCM_INLINE SCM scm_words (scm_t_bits car, scm_t_uint32 n_words);
 200
 201 #if SCM_CAN_INLINE || defined SCM_INLINE_C_IMPLEMENTING_INLINES
 202
 203 SCM_INLINE_IMPLEMENTATION SCM
 204 scm_cell (scm_t_bits car, scm_t_bits cdr)
 205 {
 206   SCM cell = SCM_PACK_POINTER (SCM_GC_MALLOC (sizeof (scm_t_cell)));
 207
 208   /* Initialize the type slot last so that the cell is ignored by the GC
 209      until it is completely initialized.  This is only relevant when the GC
 210      can actually run during this code, which it can't since the GC only runs
 211      when all other threads are stopped.  */
 212   SCM_GC_SET_CELL_WORD (cell, 1, cdr);
 213   SCM_GC_SET_CELL_WORD (cell, 0, car);
 214
 215   return cell;
 216 }
 217
 218 SCM_INLINE_IMPLEMENTATION SCM
 219 scm_double_cell (scm_t_bits car, scm_t_bits cbr,
 220                  scm_t_bits ccr, scm_t_bits cdr)
 221 {
 222   SCM z;
 223
 224   z = SCM_PACK_POINTER (SCM_GC_MALLOC (2 * sizeof (scm_t_cell)));
 225   /* Initialize the type slot last so that the cell is ignored by the
 226      GC until it is completely initialized.  This is only relevant
 227      when the GC can actually run during this code, which it can't
 228      since the GC only runs when all other threads are stopped.
 229   */
 230   SCM_GC_SET_CELL_WORD (z, 1, cbr);
 231   SCM_GC_SET_CELL_WORD (z, 2, ccr);
 232   SCM_GC_SET_CELL_WORD (z, 3, cdr);
 233   SCM_GC_SET_CELL_WORD (z, 0, car);
 234
 235   /* When this function is inlined, it's possible that the last
 236      SCM_GC_SET_CELL_WORD above will be adjacent to a following
 237      initialization of z.  E.g., it occurred in scm_make_real.  GCC
 238      from around version 3 (e.g., certainly 3.2) began taking
 239      advantage of strict C aliasing rules which say that it's OK to
 240      interchange the initialization above and the one below when the
 241      pointer types appear to differ sufficiently.  We don't want that,
 242      of course.  GCC allows this behaviour to be disabled with the
 243      -fno-strict-aliasing option, but would also need to be supplied
 244      by Guile users.  Instead, the following statements prevent the
 245      reordering.
 246    */
 247 #ifdef __GNUC__
 248   __asm__ volatile ("" : : : "memory");
 249 #else
 250   /* portable version, just in case any other compiler does the same
 251      thing.  */
 252   scm_remember_upto_here_1 (z);
 253 #endif
 254
 255   return z;
 256 }
 257
 258 SCM_INLINE_IMPLEMENTATION SCM
 259 scm_words (scm_t_bits car, scm_t_uint32 n_words)
 260 {
 261   SCM z;
 262
 263   z = SCM_PACK_POINTER (SCM_GC_MALLOC (sizeof (scm_t_bits) * n_words));
 264   SCM_GC_SET_CELL_WORD (z, 0, car);
 265
 266   /* FIXME: is the following concern even relevant with BDW-GC? */
 267
 268   /* When this function is inlined, it's possible that the last
 269      SCM_GC_SET_CELL_WORD above will be adjacent to a following
 270      initialization of z.  E.g., it occurred in scm_make_real.  GCC
 271      from around version 3 (e.g., certainly 3.2) began taking
 272      advantage of strict C aliasing rules which say that it's OK to
 273      interchange the initialization above and the one below when the
 274      pointer types appear to differ sufficiently.  We don't want that,
 275      of course.  GCC allows this behaviour to be disabled with the
 276      -fno-strict-aliasing option, but would also need to be supplied
 277      by Guile users.  Instead, the following statements prevent the
 278      reordering.
 279    */
 280 #ifdef __GNUC__
 281   __asm__ volatile ("" : : : "memory");
 282 #else
 283   /* portable version, just in case any other compiler does the same
 284      thing.  */
 285   scm_remember_upto_here_1 (z);
 286 #endif
 287
 288   return z;
 289 }
 290
 291 #endif /* SCM_CAN_INLINE || defined SCM_INLINE_C_IMPLEMENTING_INLINES */
 292
 293 SCM_API void scm_remember_upto_here_1 (SCM obj);
 294 SCM_API void scm_remember_upto_here_2 (SCM obj1, SCM obj2);
 295 SCM_API void scm_remember_upto_here (SCM obj1, ...);
 296
 297 /* In GCC we can force a reference to an SCM by making it an input to an
 298    empty asm.  This avoids the code size and slowdown of an actual function
 299    call.  Unfortunately there doesn't seem to be any way to do the varargs
 300    scm_remember_upto_here like this.
 301
 302    __volatile__ ensures nothing will be moved across the asm, and it won't
 303    be optimized away (or only if proved unreachable).  Constraint "g" can be
 304    used on all processors and allows any memory or general register (or
 305    immediate) operand.  The actual asm syntax doesn't matter, we don't want
 306    to use it, just ensure the operand is still alive.  See "Extended Asm" in
 307    the GCC manual for more.  */
 308
 309 #ifdef __GNUC__
 310 #define scm_remember_upto_here_1(x)             \
 311   do {                                          \
 312     __asm__ __volatile__ ("" : : "g" (x));      \
 313   } while (0)
 314 #define scm_remember_upto_here_2(x, y)          \
 315   do {                                          \
 316     scm_remember_upto_here_1 (x);               \
 317     scm_remember_upto_here_1 (y);               \
 318   } while (0)
 319 #endif
 320
 321 SCM_API SCM scm_return_first (SCM elt, ...);
 322 SCM_API int scm_return_first_int (int x, ...);
 323 SCM_API SCM scm_permanent_object (SCM obj);
 324 SCM_API SCM scm_gc_protect_object (SCM obj);
 325 SCM_API SCM scm_gc_unprotect_object (SCM obj);
 326 SCM_API void scm_gc_register_root (SCM *p);
 327 SCM_API void scm_gc_unregister_root (SCM *p);
 328 SCM_API void scm_gc_register_roots (SCM *b, unsigned long n);
 329 SCM_API void scm_gc_unregister_roots (SCM *b, unsigned long n);
 330 SCM_INTERNAL void scm_storage_prehistory (void);
 331 SCM_INTERNAL void scm_init_gc_protect_object (void);
 332 SCM_INTERNAL void scm_init_gc (void);
 333
 334 #endif  /* SCM_GC_H */
 335
 336 /*
 337   Local Variables:
 338   c-file-style: "gnu"
 339   End:
 340 */