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