docs/ecma334/10.9.xml

   1 <?xml version="1.0"?>
   2 <clause number="10.9" title="Automatic memory management">
   3   <paragraph>C# employs automatic memory management, which frees developers from manually allocating and freeing the memory occupied by objects. Automatic memory management policies are implemented by a garbage collector. The memory management life cycle of an object is as follows: </paragraph>
   4   <paragraph>1 When the object is created, memory is allocated for it, the constructor is run, and the object is considered live. </paragraph>
   5   <paragraph>2 If the object, or any part of it, cannot be accessed by any possible continuation of execution, other than the running of destructors, the object is considered no longer in use, and it becomes eligible for destruction. <note>[Note: Implementations may choose to analyze code to determine which references to an object may be used in the future. For instance, if a local variable that is in scope is the only existing reference to an object, but that local variable is never referred to in any possible continuation of execution from the current execution point in the procedure, an implementation may (but is not required to) treat the object as no longer in use. end note]</note> </paragraph>
   6   <paragraph>3 Once the object is eligible for destruction, at some unspecified later time the destructor (<hyperlink>17.12</hyperlink>) (if any) for the object is run. Unless overridden by explicit calls, the destructor for the object is run once only. </paragraph>
   7   <paragraph>4 Once the destructor for an object is run, if that object, or any part of it, cannot be accessed by any possible continuation of execution, including the running of destructors, the object is considered inaccessible and the object becomes eligible for collection. </paragraph>
   8   <paragraph>5 Finally, at some time after the object becomes eligible for collection, the garbage collector frees the memory associated with that object. </paragraph>
   9   <paragraph>The garbage collector maintains information about object usage, and uses this information to make memory management decisions, such as where in memory to locate a newly created object, when to relocate an object, and when an object is no longer in use or inaccessible. </paragraph>
  10   <paragraph>Like other languages that assume the existence of a garbage collector, C# is designed so that the garbage collector may implement a wide range of memory management policies. For instance, C# does not require that destructors be run or that objects be collected as soon as they are eligible, or that destructors be run in any particular order, or on any particular thread. </paragraph>
  11   <paragraph>The behavior of the garbage collector can be controlled, to some degree, via static methods on the class System.GC. This class can be used to request a collection to occur, destructors to be run (or not run), and so forth. </paragraph>
  12   <paragraph>
  13     <example>[Example: Since the garbage collector is allowed wide latitude in deciding when to collect objects and run destructors, a conforming implementation may produce output that differs from that shown by the following code. The program <code_example><![CDATA[
  14 using System;
  15 class A
  16 {
  17    ~A() {
  18       Console.WriteLine("Destruct instance of A");
  19    }
  20 }
  21 class B
  22 {
  23    object Ref;
  24    public B(object o) {
  25       Ref = o;
  26    }
  27    ~B() {
  28       Console.WriteLine("Destruct instance of B");
  29    }
  30 }
  31 class Test
  32 {
  33    static void Main() {
  34       B b = new B(new A());
  35       b = null;
  36       GC.Collect();
  37       GC.WaitForPendingFinalizers();
  38    }
  39 }
  40 ]]></code_example>creates an instance of class A and an instance of class B. These objects become eligible for garbage collection when the variable b is assigned the value null, since after this time it is impossible for any  user-written code to access them. The output could be either <code_example><![CDATA[
  41 Destruct instance of A
  42 Destruct instance of B
  43 ]]></code_example>or <code_example><![CDATA[
  44 Destruct instance of B
  45 Destruct instance of A
  46 ]]></code_example>because the language imposes no constraints on the order in which objects are garbage collected. </example>
  47   </paragraph>
  48   <paragraph>
  49     <example>In subtle cases, the distinction between &quot;eligible for destruction&quot; and &quot;eligible for collection&quot; can be important. For example, <code_example><![CDATA[
  50 using System;
  51 class A
  52 {
  53    ~A() {
  54       Console.WriteLine("Destruct instance of A");
  55    }
  56    public void F() {
  57       Console.WriteLine("A.F");
  58       Test.RefA = this;
  59    }
  60 }
  61 class B
  62 {
  63    public A Ref;
  64    ~B() {
  65       Console.WriteLine("Destruct instance of B");
  66       Ref.F();
  67    }
  68 }
  69 class Test
  70 {
  71    public static A RefA;
  72    public static B RefB;
  73    static void Main() {
  74       RefB = new B();
  75       RefA = new A();
  76       RefB.Ref = RefA;
  77       RefB = null;
  78       RefA = null;
  79       // A and B now eligible for destruction
  80       GC.Collect();
  81       GC.WaitForPendingFinalizers();
  82       // B now eligible for collection, but A is not
  83       if (RefA != null)
  84       Console.WriteLine("RefA is not null");
  85    }
  86 }
  87 ]]></code_example></example>
  88   </paragraph>
  89   <paragraph>
  90     <example>In the above program, if the garbage collector chooses to run the destructor of A before the destructor of B, then the output of this program might be: <code_example><![CDATA[
  91 Destruct instance of A
  92 Destruct instance of B
  93 A.F
  94 RefA is not null
  95 ]]></code_example></example>
  96   </paragraph>
  97   <paragraph>
  98     <example>Note that although the instance of A was not in use and A's destructor was run, it is still possible for methods of A (in this case, F) to be called from another destructor. Also, note that running of a destructor may cause an object to become usable from the mainline program again. In this case, the running of B's destructor caused an instance of A that was previously not in use to become accessible from the live reference RefA. After the call to WaitForPendingFinalizers, the instance of B is eligible for collection, but the instance of A is not, because of the reference RefA. </example>
  99   </paragraph>
 100   <paragraph>
 101     <example>To avoid confusion and unexpected behavior, it is generally a good idea for destructors to only perform cleanup on data stored in their object's own fields, and not to perform any actions on referenced objects or static fields. end example]</example>
 102   </paragraph>
 103 </clause>