src/core/memory.d

   1 /**
   2  * The memory module provides an interface to the garbage collector and to
   3  * any other OS or API-level memory management facilities.
   4  *
   5  * Copyright: Copyright (c) 2005-2008, The D Runtime Project
   6  * License:   BSD Style, see LICENSE
   7  * Authors:   Sean Kelly
   8  */
   9 module memory;
  10
  11
  12 private
  13 {
  14     extern (C) void gc_init();
  15     extern (C) void gc_term();
  16
  17     extern (C) void gc_enable();
  18     extern (C) void gc_disable();
  19     extern (C) void gc_collect();
  20     extern (C) void gc_minimize();
  21
  22     extern (C) uint gc_getAttr( void* p );
  23     extern (C) uint gc_setAttr( void* p, uint a );
  24     extern (C) uint gc_clrAttr( void* p, uint a );
  25
  26     extern (C) void*  gc_malloc( size_t sz, uint ba = 0 );
  27     extern (C) void*  gc_calloc( size_t sz, uint ba = 0 );
  28     extern (C) void*  gc_realloc( void* p, size_t sz, uint ba = 0 );
  29     extern (C) size_t gc_extend( void* p, size_t mx, size_t sz );
  30     extern (C) size_t gc_reserve( size_t sz );
  31     extern (C) void   gc_free( void* p );
  32
  33     extern (C) void*   gc_addrOf( void* p );
  34     extern (C) size_t  gc_sizeOf( void* p );
  35
  36     struct BlkInfo_
  37     {
  38         void*  base;
  39         size_t size;
  40         uint   attr;
  41     }
  42
  43     extern (C) BlkInfo_ gc_query( void* p );
  44
  45     extern (C) void gc_addRoot( void* p );
  46     extern (C) void gc_addRange( void* p, size_t sz );
  47
  48     extern (C) void gc_removeRoot( void* p );
  49     extern (C) void gc_removeRange( void* p );
  50 }
  51
  52
  53 /**
  54  * This struct encapsulates all garbage collection functionality for the D
  55  * programming language.
  56  */
  57 struct GC
  58 {
  59     /**
  60      * Enables the garbage collector if collections have previously been
  61      * suspended by a call to disable.  This function is reentrant, and
  62      * must be called once for every call to disable before the garbage
  63      * collector is enabled.
  64      */
  65     static void enable()
  66     {
  67         gc_enable();
  68     }
  69
  70
  71     /**
  72      * Disables the garbage collector.  This function is reentrant, but
  73      * enable must be called once for each call to disable.
  74      */
  75     static void disable()
  76     {
  77         gc_disable();
  78     }
  79
  80
  81     /**
  82      * Begins a full collection.  While the meaning of this may change based
  83      * on the garbage collector implementation, typical behavior is to scan
  84      * all stack segments for roots, mark accessible memory blocks as alive,
  85      * and then to reclaim free space.  This action may need to suspend all
  86      * running threads for at least part of the collection process.
  87      */
  88     static void collect()
  89     {
  90         gc_collect();
  91     }
  92
  93     /**
  94      * Indicates that the managed memory space be minimized by returning free
  95      * physical memory to the operating system.  The amount of free memory
  96      * returned depends on the allocator design and on program behavior.
  97      */
  98     static void minimize()
  99     {
 100         gc_minimize();
 101     }
 102
 103
 104     /**
 105      * Elements for a bit field representing memory block attributes.  These
 106      * are manipulated via the getAttr, setAttr, clrAttr functions.
 107      */
 108     enum BlkAttr : uint
 109     {
 110         FINALIZE = 0b0000_0001, /// Finalize the data in this block on collect.
 111         NO_SCAN  = 0b0000_0010, /// Do not scan through this block on collect.
 112         NO_MOVE  = 0b0000_0100  /// Do not move this memory block on collect.
 113     }
 114
 115
 116     /**
 117      * Contains aggregate information about a block of managed memory.  The
 118      * purpose of this struct is to support a more efficient query style in
 119      * instances where detailed information is needed.
 120      *
 121      * base = A pointer to the base of the block in question.
 122      * size = The size of the block, calculated from base.
 123      * attr = Attribute bits set on the memory block.
 124      */
 125     alias BlkInfo_ BlkInfo;
 126
 127
 128     /**
 129      * Returns a bit field representing all block attributes set for the memory
 130      * referenced by p.  If p references memory not originally allocated by
 131      * this garbage collector, points to the interior of a memory block, or if
 132      * p is null, zero will be returned.
 133      *
 134      * Params:
 135      *  p = A pointer to the root of a valid memory block or to null.
 136      *
 137      * Returns:
 138      *  A bit field containing any bits set for the memory block referenced by
 139      *  p or zero on error.
 140      */
 141     static uint getAttr( void* p )
 142     {
 143         return gc_getAttr( p );
 144     }
 145
 146
 147     /**
 148      * Sets the specified bits for the memory references by p.  If p references
 149      * memory not originally allocated by this garbage collector, points to the
 150      * interior of a memory block, or if p is null, no action will be
 151      * performed.
 152      *
 153      * Params:
 154      *  p = A pointer to the root of a valid memory block or to null.
 155      *  a = A bit field containing any bits to set for this memory block.
 156      *
 157      *  The result of a call to getAttr after the specified bits have been
 158      *  set.
 159      */
 160     static uint setAttr( void* p, uint a )
 161     {
 162         return gc_setAttr( p, a );
 163     }
 164
 165
 166     /**
 167      * Clears the specified bits for the memory references by p.  If p
 168      * references memory not originally allocated by this garbage collector,
 169      * points to the interior of a memory block, or if p is null, no action
 170      * will be performed.
 171      *
 172      * Params:
 173      *  p = A pointer to the root of a valid memory block or to null.
 174      *  a = A bit field containing any bits to clear for this memory block.
 175      *
 176      * Returns:
 177      *  The result of a call to getAttr after the specified bits have been
 178      *  cleared.
 179      */
 180     static uint clrAttr( void* p, uint a )
 181     {
 182         return gc_clrAttr( p, a );
 183     }
 184
 185
 186     /**
 187      * Requests an aligned block of managed memory from the garbage collector.
 188      * This memory may be deleted at will with a call to free, or it may be
 189      * discarded and cleaned up automatically during a collection run.  If
 190      * allocation fails, this function will call onOutOfMemory which is
 191      * expected to throw an OutOfMemoryException.
 192      *
 193      * Params:
 194      *  sz = The desired allocation size in bytes.
 195      *  ba = A bitmask of the attributes to set on this block.
 196      *
 197      * Returns:
 198      *  A reference to the allocated memory or null if insufficient memory
 199      *  is available.
 200      *
 201      * Throws:
 202      *  OutOfMemoryException on allocation failure.
 203      */
 204     static void* malloc( size_t sz, uint ba = 0 )
 205     {
 206         return gc_malloc( sz, ba );
 207     }
 208
 209
 210     /**
 211      * Requests an aligned block of managed memory from the garbage collector,
 212      * which is initialized with all bits set to zero.  This memory may be
 213      * deleted at will with a call to free, or it may be discarded and cleaned
 214      * up automatically during a collection run.  If allocation fails, this
 215      * function will call onOutOfMemory which is expected to throw an
 216      * OutOfMemoryException.
 217      *
 218      * Params:
 219      *  sz = The desired allocation size in bytes.
 220      *  ba = A bitmask of the attributes to set on this block.
 221      *
 222      * Returns:
 223      *  A reference to the allocated memory or null if insufficient memory
 224      *  is available.
 225      *
 226      * Throws:
 227      *  OutOfMemoryException on allocation failure.
 228      */
 229     static void* calloc( size_t sz, uint ba = 0 )
 230     {
 231         return gc_calloc( sz, ba );
 232     }
 233
 234
 235     /**
 236      * If sz is zero, the memory referenced by p will be deallocated as if
 237      * by a call to free.  A new memory block of size sz will then be
 238      * allocated as if by a call to malloc, or the implementation may instead
 239      * resize the memory block in place.  The contents of the new memory block
 240      * will be the same as the contents of the old memory block, up to the
 241      * lesser of the new and old sizes.  Note that existing memory will only
 242      * be freed by realloc if sz is equal to zero.  The garbage collector is
 243      * otherwise expected to later reclaim the memory block if it is unused.
 244      * If allocation fails, this function will call onOutOfMemory which is
 245      * expected to throw an OutOfMemoryException.  If p references memory not
 246      * originally allocated by this garbage collector, or if it points to the
 247      * interior of a memory block, no action will be taken.  If ba is zero
 248      * (the default) and p references the head of a valid, known memory block
 249      * then any bits set on the current block will be set on the new block if a
 250      * reallocation is required.  If ba is not zero and p references the head
 251      * of a valid, known memory block then the bits in ba will replace those on
 252      * the current memory block and will also be set on the new block if a
 253      * reallocation is required.
 254      *
 255      * Params:
 256      *  p  = A pointer to the root of a valid memory block or to null.
 257      *  sz = The desired allocation size in bytes.
 258      *  ba = A bitmask of the attributes to set on this block.
 259      *
 260      * Returns:
 261      *  A reference to the allocated memory on success or null if sz is
 262      *  zero.  On failure, the original value of p is returned.
 263      *
 264      * Throws:
 265      *  OutOfMemoryException on allocation failure.
 266      */
 267     static void* realloc( void* p, size_t sz, uint ba = 0 )
 268     {
 269         return gc_realloc( p, sz, ba );
 270     }
 271
 272
 273     /**
 274      * Requests that the managed memory block referenced by p be extended in
 275      * place by at least mx bytes, with a desired extension of sz bytes.  If an
 276      * extension of the required size is not possible, if p references memory
 277      * not originally allocated by this garbage collector, or if p points to
 278      * the interior of a memory block, no action will be taken.
 279      *
 280      * Params:
 281      *  mx = The minimum extension size in bytes.
 282      *  sz = The  desired extension size in bytes.
 283      *
 284      * Returns:
 285      *  The size in bytes of the extended memory block referenced by p or zero
 286      *  if no extension occurred.
 287      */
 288     static size_t extend( void* p, size_t mx, size_t sz )
 289     {
 290         return gc_extend( p, mx, sz );
 291     }
 292
 293
 294     /**
 295      * Requests that at least sz bytes of memory be obtained from the operating
 296      * system and marked as free.
 297      *
 298      * Params:
 299      *  sz = The desired size in bytes.
 300      *
 301      * Returns:
 302      *  The actual number of bytes reserved or zero on error.
 303      */
 304     static size_t reserve( size_t sz )
 305     {
 306         return gc_reserve( sz );
 307     }
 308
 309
 310     /**
 311      * Deallocates the memory referenced by p.  If p is null, no action
 312      * occurs.  If p references memory not originally allocated by this
 313      * garbage collector, or if it points to the interior of a memory block,
 314      * no action will be taken.  The block will not be finalized regardless
 315      * of whether the FINALIZE attribute is set.  If finalization is desired,
 316      * use delete instead.
 317      *
 318      * Params:
 319      *  p = A pointer to the root of a valid memory block or to null.
 320      */
 321     static void free( void* p )
 322     {
 323         gc_free( p );
 324     }
 325
 326
 327     /**
 328      * Returns the base address of the memory block containing p.  This value
 329      * is useful to determine whether p is an interior pointer, and the result
 330      * may be passed to routines such as sizeOf which may otherwise fail.  If p
 331      * references memory not originally allocated by this garbage collector, if
 332      * p is null, or if the garbage collector does not support this operation,
 333      * null will be returned.
 334      *
 335      * Params:
 336      *  p = A pointer to the root or the interior of a valid memory block or to
 337      *      null.
 338      *
 339      * Returns:
 340      *  The base address of the memory block referenced by p or null on error.
 341      */
 342     static void* addrOf( void* p )
 343     {
 344         return gc_addrOf( p );
 345     }
 346
 347
 348     /**
 349      * Returns the true size of the memory block referenced by p.  This value
 350      * represents the maximum number of bytes for which a call to realloc may
 351      * resize the existing block in place.  If p references memory not
 352      * originally allocated by this garbage collector, points to the interior
 353      * of a memory block, or if p is null, zero will be returned.
 354      *
 355      * Params:
 356      *  p = A pointer to the root of a valid memory block or to null.
 357      *
 358      * Returns:
 359      *  The size in bytes of the memory block referenced by p or zero on error.
 360      */
 361     static size_t sizeOf( void* p )
 362     {
 363         return gc_sizeOf( p );
 364     }
 365
 366
 367     /**
 368      * Returns aggregate information about the memory block containing p.  If p
 369      * references memory not originally allocated by this garbage collector, if
 370      * p is null, or if the garbage collector does not support this operation,
 371      * BlkInfo.init will be returned.  Typically, support for this operation
 372      * is dependent on support for addrOf.
 373      *
 374      * Params:
 375      *  p = A pointer to the root or the interior of a valid memory block or to
 376      *      null.
 377      *
 378      * Returns:
 379      *  Information regarding the memory block referenced by p or BlkInfo.init
 380      *  on error.
 381      */
 382     static BlkInfo query( void* p )
 383     {
 384         return gc_query( p );
 385     }
 386
 387
 388     /**
 389      * Adds the memory address referenced by p to an internal list of roots to
 390      * be scanned during a collection.  If p is null, no operation is
 391      * performed.
 392      *
 393      * Params:
 394      *  p = A pointer to a valid memory address or to null.
 395      */
 396     static void addRoot( void* p )
 397     {
 398         gc_addRoot( p );
 399     }
 400
 401
 402     /**
 403      * Adds the memory block referenced by p and of size sz to an internal list
 404      * of ranges to be scanned during a collection.  If p is null, no operation
 405      * is performed.
 406      *
 407      * Params:
 408      *  p  = A pointer to a valid memory address or to null.
 409      *  sz = The size in bytes of the block to add.  If sz is zero then the
 410      *       no operation will occur.  If p is null then sz must be zero.
 411      */
 412     static void addRange( void* p, size_t sz )
 413     {
 414         gc_addRange( p, sz );
 415     }
 416
 417
 418     /**
 419      * Removes the memory block referenced by p from an internal list of roots
 420      * to be scanned during a collection.  If p is null or does not represent
 421      * a value previously passed to add(void*) then no operation is performed.
 422      *
 423      *  p  = A pointer to a valid memory address or to null.
 424      */
 425     static void removeRoot( void* p )
 426     {
 427         gc_removeRoot( p );
 428     }
 429
 430
 431     /**
 432      * Removes the memory block referenced by p from an internal list of ranges
 433      * to be scanned during a collection.  If p is null or does not represent
 434      * a value previously passed to add(void*, size_t) then no operation is
 435      * performed.
 436      *
 437      * Params:
 438      *  p  = A pointer to a valid memory address or to null.
 439      */
 440     static void removeRange( void* p )
 441     {
 442         gc_removeRange( p );
 443     }
 444 }