Jon Jagger
jon@jaggersoft.com
Table of Contents 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 Notes DownloadECMA-334 C# Language Specificationpreviousnextprevious at this levelnext at this level 25 Unsafe codeprevious at this levelnext at this level 25.6 The fixed statement Paragraph 11 In an unsafe context, the embedded-statement (§15) production permits an additional construct, the fixed statement, which is used to "fix" a moveable variable such that its address remains constant for the duration of the statement. embedded-statement : ... fixed-statement fixed-statement : fixed ( pointer-type fixed-pointer-declarators ) embedded-statement fixed-pointer-declarators : fixed-pointer-declarator fixed-pointer-declarators , fixed-pointer-declarator fixed-pointer-declarator : identifier = fixed-pointer-initializer fixed-pointer-initializer : & variable-reference expression Paragraph 21 Each fixed-pointer-declarator declares a local variable of the given pointer-type and initializes that local variable with the address computed by the corresponding fixed-pointer-initializer. 2 A local variable declared in a fixed statement is accessible in any fixed-pointer-initializers occurring to the right of that variable's declaration, and in the embedded-statement of the fixed statement. 3 A local variable declared by a fixed statement is considered read-only. 4 A compile-time error occurs if the embedded statement attempts to modify this local variable (via assignment or the ++ and --operators) or pass it as a ref or out parameter. Paragraph 31 A fixed-pointer-initializer can be one of the following: Paragraph 41 For each address computed by a fixed-pointer-initializer the fixed statement ensures that the variable referenced by the address is not subject to relocation or disposal by the garbage collector for the duration of the fixed statement. 2 For example, if the address computed by a fixed-pointer-initializer references a field of an object or an element of an array instance, the fixed statement guarantees that the containing object instance is not relocated or disposed of during the lifetime of the statement. Paragraph 51 It is the programmer's responsibility to ensure that pointers created by fixed statements do not survive beyond execution of those statements. 2 For example, when pointers created by fixed statements are passed to external APIs, it is the programmer's responsibility to ensure that the APIs retain no memory of these pointers. Paragraph 61 Fixed objects may cause fragmentation of the heap (because they can't be moved). 2 For that reason, objects should be fixed only when absolutely necessary and then only for the shortest amount of time possible. [Example: The example
class Test  
{  
   static int x;  
   int y;  
   unsafe static void F(int* p) {  
      *p = 1;  
   }  
   static void Main() {  
      Test t = new Test();  
      int[] a = new int[10];  
      unsafe {  
         fixed (int* p = &x) F(p);  
         fixed (int* p = &t.y) F(p);  
         fixed (int* p = &a[0]) F(p);  
         fixed (int* p = a) F(p);  
      }  
   }  
}  
demonstrates several uses of the fixed statement. The first statement fixes and obtains the address of a static field, the second statement fixes and obtains the address of an instance field, and the third statement fixes and obtains the address of an array element. In each case it would have been an error to use the regular & operator since the variables are all classified as moveable variables.
The third and fourth fixed statements in the example above produce identical results. In general, for an array instance a, specifying &a[0] in a fixed statement is the same as simply specifying a. Here's another example of the fixed statement, this time using string:
class Test  
{  
   static string name = "xx";  
   
   unsafe static void F(char* p) {  
      for (int i = 0; p[i] != '\0'; ++i)  
      Console.WriteLine(p[i]);  
   }  
   
   static void Main() {  
      unsafe {  
         fixed (char* p = name) F(p);  
         fixed (char* p = "xx") F(p);  
      }  
   }  
}  
end example]
Paragraph 71 In an unsafe context array elements of single-dimensional arrays are stored in increasing index order, starting with index 0 and ending with index Length -1. 2 For multi-dimensional arrays, array elements are stored such that the indices of the rightmost dimension are increased first, then the next left dimension, and so on to the left. Paragraph 81 Within a fixed statement that obtains a pointer p to an array instance a, the pointer values ranging from p to p + a.Length -1 represent addresses of the elements in the array. 2 Likewise, the variables ranging from p[0] to p[a.Length -1] represent the actual array elements. 3 Given the way in which arrays are stored , we can treat an array of any dimension as though it were linear. [Example: For example.
using System;  
class Test  
{  
   static void Main() {  
      int[,,] a = new int[2,3,4];  
      unsafe {  
         fixed (int* p = a) {  
            for (int i = 0; i < a.Length; ++i)  // treat as linear  
            p[i] = i;  
         }  
      }  
      
      for (int i = 0; i < 2; ++i)  
      for (int j = 0; j < 3; ++j) {  
         for (int k = 0; k < 4; ++k)  
         Console.Write("[{0},{1},{2}] = {3,2} ", i, j, k,  
         a[i,j,k]);  
         Console.WriteLine();  
      }  
   }  
}  
which produces the output:
[0,0,0] =  0 [0,0,1] =  1 [0,0,2] =  2 [0,0,3] =  3  
[0,1,0] =  4 [0,1,1] =  5 [0,1,2] =  6 [0,1,3] =  7  
[0,2,0] =  8 [0,2,1] =  9 [0,2,2] = 10 [0,2,3] = 11  
[1,0,0] = 12 [1,0,1] = 13 [1,0,2] = 14 [1,0,3] = 15  
[1,1,0] = 16 [1,1,1] = 17 [1,1,2] = 18 [1,1,3] = 19  
[1,2,0] = 20 [1,2,1] = 21 [1,2,2] = 22 [1,2,3] = 23  
end example]
[Example: In the example
class Test  
{  
   unsafe static void Fill(int* p, int count, int value) {  
      for (; count != 0; count--) *p++ = value;  
   }  
   static void Main() {  
      int[] a = new int[100];  
      unsafe {  
         fixed (int* p = a) Fill(p, 100, -1);  
      }  
   }  
}  
a fixed statement is used to fix an array so its address can be passed to a method that takes a pointer. end example]
Paragraph 91 A char* value produced by fixing a string instance always points to a null-terminated string. 2 Within a fixed statement that obtains a pointer p to a string instance s, the pointer values ranging from p to p + s.Length -1 represent addresses of the characters in the string, and the pointer value p + s.Length always points to a null character (the character with value '\0'). Paragraph 101 Modifying objects of managed type through fixed pointers can result in undefined behavior. [Note: For example, because strings are immutable, it is the programmer's responsibility to ensure that the characters referenced by a pointer to a fixed string are not modified. end note] [Note: The automatic null-termination of strings is particularly convenient when calling external APIs that expect "C-style" strings. Note, however, that a string instance is permitted to contain null characters. If such null characters are present, the string will appear truncated when treated as a null-terminated char*. end note]
{ JSL }
Jagger Software Ltd
Company # 4070126
VAT # 762 5213 42
Valid HTML 4.01Valid CSS