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