mcs/docs/ecma334/22.3.xml

   1 <?xml version="1.0"?>
   2 <clause number="22.3" title="Delegate invocation">
   3   <paragraph>C# provides special syntax for invoking a delegate. When a non-null delegate instance whose invocation list contains one entry, is invoked, it invokes the one method with the same arguments it was given, and returns the same value as the referred to method. (See <hyperlink>14.5.5.2</hyperlink> for detailed information on delegate invocation.) If an exception occurs during the invocation of such a delegate, and that exception is not caught within the method that was invoked, the search for an exception catch clause continues in the method that called the delegate, as if that method had directly called the method to which that delegate referred. </paragraph>
   4   <paragraph>Invocation of a delegate instance whose invocation list contains multiple entries, proceeds by invoking each of the methods in the invocation list, synchronously, in order. Each method so called is passed the same set of arguments as was given to the delegate instance. If such a delegate invocation includes reference parameters (<hyperlink>17.5.1.2</hyperlink>), each method invocation will occur with a reference to the same variable; changes to that variable by one method in the invocation list will be visible to methods further down the invocation list. If the delegate invocation includes output parameters or a return value, their final value will come from the invocation of the last delegate in the list. If an exception occurs during processing of the invocation of such a delegate, and that exception is not caught within the method that was invoked, the search for an exception catch clause continues in the method that called the delegate, and any methods further down the invocation list are not invoked. </paragraph>
   5   <paragraph>Attempting to invoke a delegate instance whose value is null results in an exception of type System.NullReferenceException. </paragraph>
   6   <paragraph>
   7     <example>[Example: The following example shows how to instantiate, combine, remove, and invoke delegates: <code_example><![CDATA[
   8 using System;
   9 delegate void D(int x);
  10 class Test
  11 {
  12    public static void M1(int i) {
  13       Console.WriteLine("Test.M1: " + i);
  14    }
  15    public static void M2(int i) {
  16       Console.WriteLine("Test.M2: " + i);
  17    }
  18    public void M3(int i) {
  19       Console.WriteLine("Test.M3: " + i);
  20    }
  21 }
  22 class Demo
  23 {
  24    static void Main() {
  25       D cd1 = new D(Test.M1);
  26       cd1(-1);  // call M1
  27       D cd2 = new D(Test.M2);
  28       cd2(-2);  // call M2
  29       D cd3 = cd1 + cd2;
  30       cd3(10);  // call M1 then M2
  31
  32       cd3 += cd1;
  33       cd3(20);  // call M1, M2, then M1
  34       Test t = new Test();
  35       D cd4 = new D(t.M3);
  36       cd3 += cd4;
  37       cd3(30);  // call M1, M2, M1, then M3
  38       cd3 -= cd1; // remove last M1
  39       cd3(40);  // call M1, M2, then M3
  40       cd3 -= cd4;
  41       cd3(50);  // call M1 then M2
  42       cd3 -= cd2;
  43       cd3(60);  // call M1
  44       cd3 -= cd2; // impossible removal is benign
  45       cd3(60);  // call M1
  46       cd3 -= cd1; // invocation list is empty
  47       //  cd3(70);  // System.NullReferenceException thrown
  48       cd3 -= cd1; // impossible removal is benign
  49    }
  50 }
  51 ]]></code_example></example>
  52   </paragraph>
  53   <paragraph>
  54     <example>As shown in the statement cd3 += cd1;, a delegate can be present in an invocation list multiple times. In this case, it is simply invoked once per occurrence. In an invocation list such as this, when that delegate is removed, the last occurrence in the invocation list is the one actually removed. </example>
  55   </paragraph>
  56   <paragraph>
  57     <example>Immediately prior to the execution of the final statement, cd3 -= cd1;, the delegate cd3 refers to an empty invocation list. Attempting to remove a delegate from an empty list (or to remove a non-existent delegate from a non-empty list) is not an error. </example>
  58   </paragraph>
  59   <paragraph>
  60     <example>The output produced is: <code_example><![CDATA[
  61 Test.M1: -1
  62 Test.M2: -2
  63 Test.M1: 10
  64 Test.M2: 10
  65 Test.M1: 20
  66 Test.M2: 20
  67 Test.M1: 20
  68 Test.M1: 30
  69 Test.M2: 30
  70 Test.M1: 30
  71 Test.M3: 30
  72 Test.M1: 40
  73 Test.M2: 40
  74 Test.M3: 40
  75 Test.M1: 50
  76 Test.M2: 50
  77 Test.M1: 60
  78 Test.M1: 60
  79 ]]></code_example>end example]</example>
  80     <table_line/>
  81   </paragraph>
  82 </clause>