ArrayTGetHostPointerForWrite Method

public IntPtr GetHostPointerForWrite(
	Nullable<StorageOrders> order = null
)

Public Function GetHostPointerForWrite ( 
	Optional order As Nullable(Of StorageOrders) = Nothing
) As IntPtr

Dim instance As Array
Dim order As Nullable(Of StorageOrders)
Dim returnValue As IntPtr

returnValue = instance.GetHostPointerForWrite(order)

Parameters

order (Optional)

Type: SystemNullableStorageOrders

Return Value

For empty arrays (IsEmpty is true) the value of the pointer returned is undefined.

This pointer is valid only as long as this array is not modified or released! Do not attempt to use this pointer after the array has been released, ran out of scope, was reassigned or is modified!

The order of elements in this array is determined by the size descriptor Size. Use the strides, dimension lengths and the size of the T elements SizeOfT in order to compute the byte offset to individual elements relative to this pointer.

The memory region addressed by the pointer returned exists on the unmanaged heap. Hence, it does not need to be pinned and will not be moved by the GC. However, this memory is subject of deterministic disposal, pooling and frequent reuse by other arrays. Do not use the pointer returned after this array left the current function scope, was modified, reassigned or released!

Since ILNumerics' memory management does transparently perform 'lazy copies on write' calling this function may cause the underlying memory to be copied - transparently as well. Therefore, do not call this function unless you really want to change the memory addressed. For reading purposes it is cheaper to acquire a pointer via: GetHostPointerForRead(NullableStorageOrders). Latter option is available not only for ArrayT (as [!:GetHostPointerForWrite()]), but on any non-volatile array.

This functions works for element types T of ValueType (structs in C#) only. The bahavior for reference types ('class' elements) is undefined.

[ILNumerics Core Module]

using (Scope.Enter()) {    
       // create a local array: 
       Array<double> A = new double[,] {
           { 1, 2, 3 },
           { 4, 5, 6 }
       };
       // or use any other way of creating the array: 
       // Array<double> A = ILMath.zeros<double>(100,200); 
       // or from another array: 
       // Array<double> A = otherArray.C;  

       // get a pointer to the first element
       unsafe
       {
           double* pA = (double*)A.GetHostPointerForWrite();
           // the pointer can be used for reading AND writing
           pA[0] = -99;

           // A
           // [2 x 3] <double>
           // -99   2   3
           //   4   5   6

           // Watch the storage order 'A.S.StorageOrder'! To find specific elements: 
           double el12 = pA[A.S.GetSeqIndex(1, 2)];
           // el12: 6
           Assert.IsTrue(el12 == 6);
           Assert.IsTrue(A.GetValue(0) == -99);
       }
       // work with A commonly...
}
// don't use the pointer outside this scope block!

Reference