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