kStatus kCudaUtils_PrepareDeviceArray	(	kCudaStream	stream,
		kArrayProvider *	outputArray,
		kArrayProvider	inputArray,
		kBool	copyData = kTRUE,
		kAlloc	objectAlloc = kNULL,
		kAlloc	valueAlloc = kNULL,
		kBool	inputExclusive = kTRUE,
		kCudaSync	sync = kCUDA_SYNC_DEFAULT
	)

Ensures the specified input array is device-accessible by either cloning or sharing it.

The purpose of this method is to move an input array into device-accessible memory. However, copying an array is expensive; if the array is already suitable for device use, then copying should ideally be avoided.

As such, if the source array is already device-accessible, then this method will usually just increase the source array reference count and provide the same array as its output. However, if the input array exists in serial managed memory, then ownership of the array must also be considered (the array must be attached to a stream before it can be safely accessed, but if the array is potentially in use by multiple CPU threads, then its stream affinity cannot be altered). Accordingly, for serial managed memory, the inputExclusive argument is also required. If true, then the managed memory can be attached to the stream, enabling it to be used by a Cuda device.

If the conditions described above for sharing the input array are not met, a device-accessible array is cloned from the input array and provided as the output.

Regardless of how the output array is derived, it is the caller's responsibility to destroy the array when no longer needed.

Parameters

stream	Cuda stream.
outputArray	Receives device-accessible output array.
inputArray	Input array, which may or may not already be device accessible.
copyData	If input array is not device accessible, should its data content be copied to the newly-constructed output array?
objectAlloc	Object allocator to be used, if cloning is required.
valueAlloc	Data allocator to be used, if cloning is required (must allocate device-accessible memory; if kNULL, the device allocator will be used).
inputExclusive	Is the input array exclusively owned (not shared)? If true, allows serial managed memory to be used as device memory.
sync	Synchronization mode; if unspecified, mode is determined from default stream sync mode.

Returns

Operation status.