memory.memory - ICE 0.1 API documentation

ICE 0.1 API documentation

# memory.memory

Manual memory management functions.

T* alloc(T, string file = __FILE__, uint line = __LINE__, Args...)(Args args);

  Allocate space for and optionally initialize a primitive value or struct.

  For now, if allocating a struct, that struct must not have its empty constructor disabled.

  Note:
  Some types, such as unions, can't be initialized since their default initializer (T.init) is ambiguous. Data of such types can still be initialized to zero bytes by adding an "annotation" static variable to the type, like in this example:

  Example:

       struct ZeroInitialized
       {
           static bool CAN_INITIALIZE_WITH_ZEROES;
           union
           {
               int i;
               float f;
           }
       }

  Parameters:

  args | Arguments to value's initializer/constructor. If no arguments are specified, the value is default-initialized.

  Returns:
  Pointer to allocated struct.
void free(T)(T* ptr);

  Free an object (struct) allocated by alloc(). Will clear the object.

void unittestSingle();

  Unittest for alloc() and free calling dtor.

T[] allocArray(T, string file = __FILE__, uint line = __LINE__)(const size_t elems);

  Allocate an array of specified type.

  Arrays allocated with alloc must NOT be resized.

  Parameters:

  elems | Number of objects to allocate space for.

  Returns:
  Allocated array. Values in the array are default-initialized.
T[] realloc(T, string file = __FILE__, uint line = __LINE__)(T[] array, const size_t elems);

  Reallocate an array allocated by alloc() .

  Contents of the array are preserved but array itself might be moved in memory, invalidating any pointers pointing to it.
  If the array is shrunk and of non-reference type (e.g. not a class), any extra elements are cleared (if they have destructors, they're called).

  Parameters:

  array | Array to reallocate.
  elems | Number of objects for the reallocated array to hold.

  Returns:
  Reallocated array.
void free(T)(T[] array);

  Free an array of objects allocated by alloc().

  If the array is of non-reference type (e.g. not a class), array elements are cleared (if they have destructors, they're called).

  Parameters:

  array | Array to free.

void unittestArray();

  Unittest for allocArray(), realloc() and free().

VFSDir gameDir;

  VFSDir to output memory log to.

bool suspendMemoryDebugRecording;

  Debug info is only recorded after main() is entered.

  There seems to be a bug with dynamic array appending before main() (e.g. in unittests). TODO revisit this when a new DMD (currently 2.060) is released

package ulong currentlyAllocated();

  Get currently allocated memory in bytes.

T* allocateSingle(T, string file, uint line, Args...)(Args args);

  Allocate and initialize a primitive value or struct.

  Parameters:

  args | Parameters for the values' constructor/initializer. If not specified, the value is default-initialized.

  Returns:
  Pointer to the allocated struct.
T[] allocate(T, string file, uint line)(const size_t elems);

  Allocate and default-initialize an array with given number of elements.

  Arrays returned by allocate() must NOT be resized.

  Parameters:

  elems | Number of objects for the array to hold.

  Returns:
  Allocated array.
T[] reallocate(T, string file, uint line)(T[] array, const size_t elems);

  Reallocate an array allocated with allocate().

  Array data might move around the memory, invalidating any pointers to it. Any added elements are default-initialized. Any removed elements are cleared.

  Parameters:

  array | Array to reallocate.
  elems | Number of elements for the reallocated array to hold.

  Returns:
  Reallocated array.
void deallocate(T)(ref T* ptr);

  Free an object allocated by allocate(). If a destructor is defined, it will be called.

void deallocate(T)(ref T[] array);

  Free an array allocated by allocate().

  If a destructor is defined for the array's type and the array doesn't hold pointers or reference types, the destructor will be called for every object in the array.

  Parameters:

  array | Array to deallocate.

void debugAllocate(T, string file, uint line)(const T* ptr, const size_t objects);

  Record data about an allocation.

  Parameters:

  ptr | Pointer to the allocated memory.
  objects | Number of objects allocated.

void debugReallocate(T, string file, uint line)(const T* newPtr, const size_t newObjects, const T* oldPtr, const size_t oldObjects);

  Record data about a reallocation.

  Parameters:

  newPtr | Pointer to the reallocated memory.
  newObjects | Number of objects in reallocated memory.
  oldPtr | Pointer to original memory.
  oldObjects | Number of objects in original memory.

void debugFree(T)(const T* ptr, const size_t objects);

  Record data about a deallocation.

  Parameters:

  ptr | Pointer to deallocated memory.
  objects | Number of objects deallocated.

Copyright © Ferdinand Majerech 2011. | Page generated by AutoDDoc and Ddoc.