ILNumerics Ultimate VS

ArrayTGetHostPointerForWrite Method

ILNumerics Ultimate VS Documentation
ILNumerics - Technical Application Development
[Expert API - UNSAFE!] Acquire a writable pointer to the memory storing the first element of this array.

[ILNumerics Core Module]

Namespace:  ILNumerics
Assembly:  ILNumerics.Core (in ILNumerics.Core.dll) Version: 5.4.0.0 (5.4.7431.3055)
Syntax

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

Parameters

order (Optional)
Type: SystemNullableStorageOrders

Return Value

Type: IntPtr
Pointer to the first element of this array.
Exceptions

ExceptionCondition
InvalidOperationException if called on a return type array or if the elements are not of a ValueType.
Remarks

This function returns a pointer to the first element stored in this array. Any base offset configured for the array is taken into account. The pointer points to the memory used by this array directly - not to a copy of this memory!

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]

Examples

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!
See Also

Reference