gc/iface.d

   1 /**
   2  * Naive Garbage Collector (Tango/Druntime compliant) C interface.
   3  *
   4  * This module contains the C interface of the Naive Garbage Collector
   5  * implementation to comply with the Tango/Druntime specification.
   6  *
   7  * See_Also:  gc module
   8  * Copyright: Public Domain
   9  * License:   Public Domain
  10  * Authors:   Leandro Lucarella <llucax@gmail.com>
  11  */
  12
  13 module gc.iface;
  14
  15 private {
  16
  17     // Internal imports
  18     import gc.gc: GC, BlkInfo;
  19
  20     // Standard imports
  21     import tango.stdc.stdlib;
  22
  23     /// GC implementation instance.
  24     GC gc;
  25
  26     /// Dummy class for the GC lock.
  27     class GCLock {}
  28
  29     /**
  30      * The GC lock.
  31      *
  32      * This is a ClassInfo instance because is an easy way to get an object
  33      * instance that is not allocated in the GC heap (which is not an option
  34      * for implementing the GC).
  35      *
  36      * This avoids using OS-specific mutex.
  37      */
  38     ClassInfo lock;
  39
  40 }
  41
  42 /**
  43  * Initialize the GC.
  44  *
  45  * This function initializes the thread library too. This is a requirement
  46  * imposed by the current implementation, it's not in the D runtime specs.
  47  *
  48  * This method should be called before any other call to the GC.
  49  */
  50 extern (C) void gc_init()
  51 {
  52     lock = GCLock.classinfo;
  53     gc.init();
  54 }
  55
  56 /**
  57  * Terminate the GC.
  58  *
  59  * After this function is called, no other GC methods should be called, except
  60  * for gc_init(), which should initialize the GC again.
  61  */
  62 extern (C) void gc_term()
  63 {
  64     gc.term();
  65 }
  66
  67 /**
  68  * Enable the GC.
  69  *
  70  * When the GC is enabled, collections can happen at any time in the program.
  71  * Different implementations can trigger a collection for different reasons.
  72  *
  73  * gc_enable() and gc_disable() can be called recursively. The number of calls
  74  * to gc_enable() should match the number of calls to gc_disable(), though.
  75  *
  76  * If gc_disable() is called more times than gc_enable(), the GC will stay
  77  * disabled. If gc_enable() is called more times than gc_disable(), the
  78  * results of this function are undefined.
  79  *
  80  * See_Also: gc_disable()
  81  */
  82 extern (C) void gc_enable()
  83 {
  84     synchronized (lock)
  85         gc.enable();
  86 }
  87
  88 /**
  89  * Disable the GC.
  90  *
  91  * See_Also: gc_enable() for details.
  92  */
  93 extern (C) void gc_disable()
  94 {
  95     synchronized (lock)
  96         gc.disable();
  97 }
  98
  99 /**
 100  * Run a GC collection in order to free unreferenced objects.
 101  *
 102  * The gc_enable() and gc_disable() functions don't affect this function, the
 103  * collection will happen even if the GC is disabled.
 104  */
 105 extern (C) void gc_collect()
 106 {
 107     synchronized (lock)
 108         gc.collect();
 109 }
 110
 111 /**
 112  * Minimize free space usage.
 113  *
 114  * This function tries to minimize the programs memory footprint returning
 115  * free memory to the OS.
 116  *
 117  * This should be used with care, because it would impose a performance
 118  * penalty for further allocations.
 119  */
 120 extern (C) void gc_minimize()
 121 {
 122     synchronized (lock)
 123         gc.minimize();
 124 }
 125
 126 /**
 127  * Get the attributes of the cell pointed by ptr.
 128  *
 129  * Bit significance of the uint value used for block attribute passing is as
 130  * follows, by position:
 131  *
 132  *  $(UL
 133  *      $(LI 1: The object stored in the cell have to be finalized)
 134  *      $(LI 2: The cell should not be scanned for pointers)
 135  *      $(LI 4: The cell should not be moved during a collection)
 136  *      $(LI 3-15: Reserved for future use by the D standard library)
 137  *      $(LI 16-31: Reserved for internal use by the garbage collector and
 138  *                  compiler)
 139  *  )
 140  *
 141  * See_Also: BlkAttr, gc_setAttr(), gc_clrAttr()
 142  */
 143 extern (C) uint gc_getAttr(void* ptr)
 144 {
 145     synchronized (lock)
 146         return gc.getAttr(ptr);
 147 }
 148
 149 /**
 150  * Set the attributes of the memory block pointed by ptr.
 151  *
 152  * All bits present in attr are set, other bits are untouched. The old
 153  * attributes are returned.
 154  *
 155  * See_Also: BlkAttr, gc_getAttr(), gc_clrAttr()
 156  */
 157 extern (C) uint gc_setAttr(void* ptr, uint attr)
 158 {
 159     synchronized (lock)
 160         return gc.setAttr(ptr, attr);
 161 }
 162
 163 /**
 164  * Clear the attributes of the cell pointed by ptr.
 165  *
 166  * All bits present in attr are cleared, other bits are untouched. The old
 167  * attributes are returned.
 168  *
 169  * See_Also: BlkAttr, gc_getAttr(), gc_setAttr()
 170  */
 171 extern (C) uint gc_clrAttr(void* ptr, uint attr)
 172 {
 173     synchronized (lock)
 174         return gc.clrAttr(ptr, attr);
 175 }
 176
 177 /**
 178  * Allocate memory with attributes attr.
 179  *
 180  * See_Also: BlkAttr, gc_getAttr() for attr details.
 181  */
 182 extern (C) void* gc_malloc(size_t size, uint attr=0)
 183 {
 184     synchronized (lock)
 185         return gc.malloc(size, attr);
 186 }
 187
 188 /**
 189  * Allocate memory (set memory to zero).
 190  *
 191  * Same as gc_malloc() but set the allocated memory block to zero.
 192  */
 193 extern (C) void* gc_calloc(size_t size, uint attr=0)
 194 {
 195     synchronized (lock)
 196         return gc.calloc(size, attr);
 197 }
 198
 199 /**
 200  * Reallocate memory.
 201  *
 202  * This function attempts to extend the current memory block to size. If ptr
 203  * is null, then this function behaves exactly the same as gc_malloc(). If
 204  * size is 0, then this function behaves exactly like gc_free(). Otherwise
 205  * this function can resize the memory block in-place or it can move the
 206  * memory block to another address, in which case the new memory address is
 207  * returned (if the memory block is not moved, the return address is the same
 208  * as ptr).
 209  *
 210  * attr are the same as malloc().
 211  */
 212 extern (C) void* gc_realloc(void* ptr, size_t size, uint attr=0)
 213 {
 214     synchronized (lock)
 215         return gc.realloc(ptr, size, attr);
 216 }
 217
 218 /**
 219  * Attempt to in-place enlarge a memory block pointed to by ptr.
 220  *
 221  * The memory is enlarged to at least min_size beyond its current capacity, up
 222  * to a maximum of max_size. This does not attempt to move the memory block
 223  * (like gc_realloc() does).
 224  *
 225  * The total size of entire memory block is returned on success, 0 is returned
 226  * if the memory block could not be extended.
 227  */
 228 extern (C) size_t gc_extend(void* ptr, size_t min_size, size_t max_size)
 229 {
 230     synchronized (lock)
 231         return gc.extend(ptr, min_size, max_size);
 232 }
 233
 234 /**
 235  * Reserve memory to anticipate memory allocations.
 236  *
 237  * This method instructs the GC to pre-allocate at least size bytes of memory
 238  * in anticipation of future gc_malloc()s.
 239  *
 240  * The actual number of bytes reserver are returned, or 0 on error.
 241  */
 242 extern (C) size_t gc_reserve(size_t size)
 243 {
 244     synchronized (lock)
 245         return gc.reserve(size);
 246 }
 247
 248 /**
 249  * Free unused memory.
 250  *
 251  * This method tells the GC that a cell is not longer used. If the memory was
 252  * actually still used the effects of this function is undefined (but memory
 253  * corruption will probably happen).
 254  *
 255  * Note that finalizers are not called by this function. Finalizers are called
 256  * by the runtime when the delete operator is used, and the delete operator
 257  * calls this method through the runtime.
 258  */
 259 extern (C) void gc_free(void* ptr)
 260 {
 261     synchronized (lock)
 262         gc.free(ptr);
 263 }
 264
 265 /**
 266  * Get the base address of an interior pointer into the GC heap.
 267  *
 268  * If ptr is not pointing into the GC heap null is returned.
 269  */
 270 extern (C) void* gc_addrOf(void* ptr)
 271 {
 272     synchronized (lock)
 273         return gc.addrOf(ptr);
 274 }
 275
 276 /**
 277  * Return the real size (capacity) of the memory block pointed by ptr.
 278  *
 279  * ptr should be the base address of a heap allocated object, interior
 280  * pointers are not supported (use gc_addrOf() if you have an interior
 281  * pointer). If ptr is not the base address of a heap allocated object this
 282  * function returns 0.
 283  *
 284  * realloc(ptr, sizeOf(ptr), attr) is guaranteed not to allocate/move memory.
 285  */
 286 extern (C) size_t gc_sizeOf(void* ptr)
 287 {
 288     synchronized (lock)
 289         return gc.sizeOf(ptr);
 290 }
 291
 292 /** Get information about the memory block pointed by ptr.
 293  *
 294  * ptr should be the base address of a heap allocated object, interior
 295  * pointers are not supported (use gc_addrOf() if you have an interior
 296  * pointer). If ptr is not the base address of a heap allocated object this
 297  * function returns a BlkInfo structure with all zeros.
 298  *
 299  * See BlkInfo for the information provided by this method.
 300  */
 301 extern (C) BlkInfo gc_query(void* ptr)
 302 {
 303     synchronized (lock)
 304         return gc.query(ptr);
 305 }
 306
 307 /** Add a root pointer to the root set.
 308  *
 309  * This method can be used to register new root to the GC heap. This is only
 310  * needed when the user has custom memory that has pointers into the GC heap
 311  * (for example for interfacing with C programs, which allocates memory using
 312  * malloc() directly).
 313  *
 314  * See_Also: gc_removeRoot(), gc_addRange(), gc_removeRange()
 315  */
 316 extern (C) void gc_addRoot(void* ptr)
 317 {
 318     synchronized (lock)
 319         gc.addRoot(ptr);
 320 }
 321
 322 /**
 323  * Add a root range to the root set.
 324  *
 325  * This method can be used to register new root range (a memory chunk that
 326  * should be scanned for pointers into the GC heap). Pointers will be scanned
 327  * assuming they are aligned.
 328  *
 329  * See_Also: gc_removeRange(), gc_addRoot(), gc_removeRoot()
 330  */
 331 extern (C) void gc_addRange(void* ptr, size_t size)
 332 {
 333     synchronized (lock)
 334         gc.addRange(ptr, size);
 335 }
 336
 337 /**
 338  * Remove a root pointer from the root set.
 339  *
 340  * ptr has to be previously registered using gc_addRoot(), in other case the
 341  * results of this function is undefined.
 342  *
 343  * See_Also: gc_addRoot(), gc_addRange(), gc_removeRange()
 344  */
 345 extern (C) void gc_removeRoot(void* ptr)
 346 {
 347     synchronized (lock)
 348         gc.removeRoot(ptr);
 349 }
 350
 351 /**
 352  * Remove a root range from the root set.
 353  *
 354  * ptr has to be previously registered using gc_addRange(), in other case the
 355  * results of this function is undefined.
 356  *
 357  * See_Also: gc_addRange(), gc_addRoot(), gc_removeRoot()
 358  */
 359 extern (C) void gc_removeRange(void* ptr)
 360 {
 361     synchronized (lock)
 362         gc.removeRange(ptr);
 363 }
 364
 365 // vim: set et sw=4 sts=4 :