mcs/docs/ecma334/17.12.xml

   1 <?xml version="1.0"?>
   2 <clause number="17.12" title="Destructors">
   3   <paragraph>A destructor is a member that implements the actions required to destruct an instance of a class. A destructor is declared using a destructor-declaration: <grammar_production><name><non_terminal where="17.12">destructor-declaration</non_terminal></name> : <rhs><non_terminal where="24.2">attributes</non_terminal><opt/><keyword>extern</keyword><opt/><terminal>~</terminal><non_terminal where="9.4.2">identifier</non_terminal><terminal>(</terminal><terminal>)</terminal><non_terminal where="17.12">destructor-body</non_terminal></rhs></grammar_production><grammar_production><name><non_terminal where="17.12">destructor-body</non_terminal></name> : <rhs><non_terminal where="15.2">block</non_terminal></rhs><rhs><terminal>;</terminal></rhs></grammar_production></paragraph>
   4   <paragraph>A <non_terminal where="17.12">destructor-declaration</non_terminal> may include a set of attributes (<hyperlink>24</hyperlink>). </paragraph>
   5   <paragraph>The identifier of a destructor-declarator must name the class in which the destructor is declared. If any other name is specified, a compile-time error occurs. </paragraph>
   6   <paragraph>When a destructor declaration includes an extern modifier, the destructor is said to be an external destructor. Because an external destructor declaration provides no actual implementation, its  <non_terminal where="17.12">destructor-body</non_terminal> consists of a semicolon. For all other destructors, the <non_terminal where="17.12">destructor-body</non_terminal> consists of a block, which specifies the statements to execute in order to destruct an instance of the class. A <non_terminal where="17.12">destructor-body</non_terminal> corresponds exactly to the <non_terminal where="17.5">method-body</non_terminal> of an instance method with a <keyword>void</keyword> return type (<hyperlink>17.5.8</hyperlink>). </paragraph>
   7   <paragraph>Destructors are not inherited. Thus, a class has no destructors other than the one which may be declared in that class. </paragraph>
   8   <paragraph>
   9     <note>[Note: Since a destructor is required to have no parameters, it cannot be overloaded, so a class can have, at most, one destructor. end note]</note>
  10   </paragraph>
  11   <paragraph>Destructors are invoked automatically, and cannot be invoked explicitly. An instance becomes eligible for destruction when it is no longer possible for any code to use that instance. Execution of the destructor for the instance may occur at any time after the instance becomes eligible for destruction. When an instance is destructed, the destructors in that instance's inheritance chain are called, in order, from most derived to least derived <example>[Example: The output of the example <code_example><![CDATA[
  12 using System;
  13 class A
  14 {
  15    ~A() {
  16       Console.WriteLine("A's destructor");
  17    }
  18 }
  19 class B: A
  20 {
  21    ~B() {
  22       Console.WriteLine("B's destructor");
  23    }
  24 }
  25 class Test
  26 {
  27    static void Main() {
  28       B b = new B();
  29       b = null;
  30       GC.Collect();
  31       GC.WaitForPendingFinalizers();
  32    }
  33 }
  34 ]]></code_example>is <code_example><![CDATA[
  35 B's destructor
  36 A's destructor
  37 ]]></code_example>since destructors in an inheritance chain are called in order, from most derived to least derived. end example]</example> </paragraph>
  38   <paragraph>Destructors may be implemented by overriding the virtual method Finalize on System.Object. In any event, C# programs are not permitted to override this method or call it (or overrides of it) directly. </paragraph>
  39   <paragraph>
  40     <example>[Example: For instance, the program <code_example><![CDATA[
  41 class A
  42 {
  43    override protected void Finalize() {}  // error
  44    public void F() {
  45       this.Finalize();   // error
  46    }
  47 }
  48 ]]></code_example>contains two errors. end example]</example>
  49   </paragraph>
  50   <paragraph>The compiler behaves as if this method, and overrides of it, does not exist at all. <example>[Example: Thus, this program: <code_example><![CDATA[
  51 class A
  52 {
  53    void Finalize() {}   // permitted
  54 }
  55 ]]></code_example>is valid and the method shown hides System.Object's Finalize method. end example]</example> </paragraph>
  56   <paragraph>For a discussion of the behavior when an exception is thrown from a destructor, see <hyperlink>23.3</hyperlink>. <table_line/>
  57 </paragraph>
  58 </clause>