docs/ecma334/25.8.xml

   1 <?xml version="1.0"?>
   2 <clause number="25.8" title="Dynamic memory allocation">
   3   <paragraph>Except for the stackalloc operator, C# provides no predefined constructs for managing non-garbage collected memory. Such services are typically provided by supporting class libraries or imported directly from the underlying operating system. <example>[Example: For example, the Memory class below illustrates how the heap functions of an underlying operating system might be accessed from C#: <code_example><![CDATA[
   4 using System;
   5 using System.Runtime.InteropServices;
   6 public unsafe class Memory
   7 {
   8    // Handle for the process heap. This handle is used in all calls to
   9    the
  10    // HeapXXX APIs in the methods below.
  11    static int ph = GetProcessHeap();
  12    // Private instance constructor to prevent instantiation.
  13    private Memory() {}
  14    // Allocates a memory block of the given size. The allocated memory is
  15    // automatically initialized to zero.
  16    public static void* Alloc(int size) {
  17       void* result = HeapAlloc(ph, HEAP_ZERO_MEMORY, size);
  18       if (result == null) throw new OutOfMemoryException();
  19       return result;
  20    }
  21    // Copies count bytes from src to dst. The source and destination
  22    // blocks are permitted to overlap.
  23    public static void Copy(void* src, void* dst, int count) {
  24       byte* ps = (byte*)src;
  25       byte* pd = (byte*)dst;
  26       if (ps > pd) {
  27          for (; count != 0; count--) *pd++ = *ps++;
  28       }
  29       else if (ps < pd) {
  30          for (ps += count, pd += count; count != 0; count--) *--pd = *--
  31          ps;
  32       }
  33    }
  34    // Frees a memory block.
  35    public static void Free(void* block) {
  36       if (!HeapFree(ph, 0, block)) throw new InvalidOperationException();
  37    }
  38    // Re-allocates a memory block. If the reallocation request is for a
  39    // larger size, the additional region of memory is automatically
  40    // initialized to zero.
  41    public static void* ReAlloc(void* block, int size) {
  42       void* result = HeapReAlloc(ph, HEAP_ZERO_MEMORY, block, size);
  43       if (result == null) throw new OutOfMemoryException();
  44       return result;
  45    }
  46    // Returns the size of a memory block.
  47    public static int SizeOf(void* block) {
  48       int result = HeapSize(ph, 0, block);
  49       if (result == -1) throw new InvalidOperationException();
  50       return result;
  51    }
  52    // Heap API flags
  53    const int HEAP_ZERO_MEMORY = 0x00000008;
  54    // Heap API functions
  55    [DllImport("kernel32")]
  56    static extern int GetProcessHeap();
  57    [DllImport("kernel32")]
  58    static extern void* HeapAlloc(int hHeap, int flags, int size);
  59    [DllImport("kernel32")]
  60    static extern bool HeapFree(int hHeap, int flags, void* block);
  61    [DllImport("kernel32")]
  62    static extern void* HeapReAlloc(int hHeap, int flags,
  63    void* block, int size);
  64    [DllImport("kernel32")]
  65    static extern int HeapSize(int hHeap, int flags, void* block);
  66 }
  67 ]]></code_example></example></paragraph>
  68   <paragraph>
  69     <example>An example that uses the Memory class is given below: <code_example><![CDATA[
  70 class Test
  71 {
  72    static void Main() {
  73       unsafe {
  74          byte* buffer = (byte*)Memory.Alloc(256);
  75          for (int i = 0; i < 256; i++) buffer[i] = (byte)i;
  76          byte[] array = new byte[256];
  77          fixed (byte* p = array) Memory.Copy(buffer, p, 256);
  78          Memory.Free(buffer);
  79          for (int i = 0; i < 256; i++) Console.WriteLine(array[i]);
  80       }
  81    }
  82 }
  83 ]]></code_example></example>
  84   </paragraph>
  85   <paragraph>
  86     <example>The example allocates 256 bytes of memory through Memory.Alloc and initializes the memory block with values increasing from 0 to 255. It then allocates a 256-element <keyword>byte</keyword> array and uses Memory.Copy to copy the contents of the memory block into the <keyword>byte</keyword> array. Finally, the memory block is freed using Memory.Free and the contents of the <keyword>byte</keyword> array are output on the console. end example]</example>
  87   </paragraph>
  88   <paragraph>End of conditionally normative text. </paragraph>
  89 </clause>