HOME
| OPENMP API Specification: Version 5.1 November 2020

3.8.8  omp_target_memcpy_rect_async

Summary The omp_target_memcpy_rect_async routine asynchronously performs a copy between any combination of host and device pointers.

Format

SVG-Viewer needed.

 

 
int omp_target_memcpy_rect_async( 
  void *dst, 
  const void *src, 
  size_t element_size, 
  int num_dims, 
  const size_t *volume, 
  const size_t *dst_offsets, 
  const size_t *src_offsets, 
  const size_t *dst_dimensions, 
  const size_t *src_dimensions, 
  int dst_device_num, 
  int src_device_num, 
  int depobj_count, 
  omp_depend_t *depobj_list 
);  

SVG-Viewer needed.

SVG-Viewer needed.

 

 
integer(c_int) function omp_target_memcpy_rect_async(dst, src, & 
  element_size, num_dims, volume, dst_offsets, src_offsets, & 
  dst_dimensions, src_dimensions, dst_device_num, src_device_num, & 
  depobj_count, depobj_list) bind(c) 
use, intrinsic :: iso_c_binding, only : c_ptr, c_int, c_size_t 
type(c_ptr), value :: dst, src 
integer(c_size_t), value :: element_size 
integer(c_int), value :: num_dims, dst_device_num, src_device_num, & 
  depobj_count 
integer(c_size_t), intent(in) :: volume(*), dst_offsets(*), & 
  src_offsets(*), dst_dimensions(*), src_dimensions(*) 
integer(omp_depobj_kind), optional :: depobj_list(*)  

SVG-Viewer needed.

Constraints on Arguments Each device pointer specified must be valid for the device on the same side of the copy. The dst_device_num and src_device_num arguments must be greater than or equal to zero and less than or equal to the result of omp_get_num_devices().

The length of the offset and dimension arrays must be at least the value of num_dims. The value of num_dims must be between 1 and the implementation-defined limit, which must be at least three.

SVG-Viewer needed.

Because the interface binds directly to a C language function the function assumes C memory ordering.

SVG-Viewer needed.

Binding The binding task set for an omp_target_memcpy_rect_async region is the generating task, which is the target task generated by the call to the omp_target_memcpy_rect_async routine.

Effect This routine copies a rectangular subvolume of src, in the device data environment of device src_device_num, to dst, in the device data environment of device dst_device_num. The volume is specified in terms of the size of an element, number of dimensions, and constant arrays of length num_dims. The maximum number of dimensions supported is at least three; support for higher dimensionality is implementation defined. The volume array specifies the length, in number of elements, to copy in each dimension from src to dst. The dst_offsets (src_offsets) parameter specifies the number of elements from the origin of dst (src) in elements. The dst_dimensions (src_dimensions) parameter specifies the length of each dimension of dst (src).

The omp_target_memcpy_rect_async routine executes as if part of a target task that is generated by the call to the routine and for which execution may be deferred.

Task dependences are expressed with zero or more omp_depend_t objects. The dependences are specified by passing the number of omp_depend_t objects followed by an array of omp_depend_t objects. The generated target task is not a dependent task if the program passes in a count of zero for depobj_count. depobj_list is ignored if the value of depobj_count is zero.

The routine returns zero if successful. Otherwise, it returns a non-zero value. The routine contains a task scheduling point.

An application can determine the number of inclusive dimensions supported by an implementation by passing NULL pointers (or C_NULL_PTR, for Fortran) for both dst and src. The routine returns the number of dimensions supported by the implementation for the specified device numbers. No copy operation is performed.

SVG-Viewer needed.

The omp_target_memcpy_rect_async routine requires an explicit interface and so might not be provided in omp_lib.h.

SVG-Viewer needed.

Execution Model Events The target-data-op-begin event occurs before a thread initiates a data transfer.

The target-data-op-end event occurs after a thread initiated a data transfer.

Tool Callbacks A thread dispatches a registered ompt_callback_target_data_op_emi callback with ompt_scope_begin as its endpoint argument for each occurrence of a target-data-op-begin event in that thread. Similarly, a thread dispatches a registered ompt_callback_target_data_op_emi callback with ompt_scope_end as its endpoint argument for each occurrence of a target-data-op-end event in that thread. These callbacks have type signature ompt_callback_target_data_op_emi_t.

A thread dispatches a registered ompt_callback_target_data_op callback for each occurrence of a target-data-op-end event in that thread. The callback occurs in the context of the target task and has type signature ompt_callback_target_data_op_t.

Restrictions Restrictions to the omp_target_memcpy_rect_async routine are as follows.

Cross References