omp_target_memcpy_rect (GNU libgomp)

#### 3.8.7 `omp_target_memcpy_rect` – Copy a subvolume of data between devices ¶

Description:

  This routine copies a subvolume of data from the device identified by device number src_device_num to device dst_device_num. The array has num_dims dimensions and each array element has a size of element_size bytes. The volume array specifies how many elements per dimension are copied. The full sizes of the destination and source arrays are given by the dst_dimensions and src_dimensions arguments, respectively. The offset per dimension to the first element to be copied is given by the dst_offset and src_offset arguments. The routine returns zero on success and non-zero otherwise.

  The OpenMP specification only requires that num_dims up to three is supported. In order to find implementation-specific maximally supported number of dimensions, the routine returns this value when invoked with a null pointer to both the dst and src arguments. As GCC supports arbitrary dimensions, it returns `INT_MAX`.

  The device-number arguments must be conforming device numbers, the src and dst must be either both null pointers or all of the following must be fulfilled: element_size and num_dims must be positive and the volume, offset and dimension arrays must have at least num_dims dimensions.

  Running this routine in a `target` region is not supported except on the initial device.

C/C++

  Prototype: | `int omp_target_memcpy_rect(void *dst,`
  | `const void *src,`
  | `size_t element_size,`
  | `int num_dims,`
  | `const size_t *volume,`
  | `const size_t *dst_offset,`
  | `const size_t *src_offset,`
  | `const size_t *dst_dimensions,`
  | `const size_t *src_dimensions,`
  | `int dst_device_num,`
  | `int src_device_num)`

Fortran:

  Interface: | `integer(c_int) function omp_target_memcpy_rect( &`
  | `dst, src, element_size, num_dims, volume, &`
  | `dst_offset, src_offset, dst_dimensions, &`
  | `src_dimensions, dst_device_num, src_device_num) bind(C)`
  | `use, intrinsic :: iso_c_binding, only: c_ptr, c_size_t, c_int`
  | `type(c_ptr), value :: dst, src`
  | `integer(c_size_t), value :: element_size, dst_offset, src_offset`
  | `integer(c_size_t), value :: volume, dst_dimensions, src_dimensions`
  | `integer(c_int), value :: num_dims, dst_device_num, src_device_num`

See also:

  `omp_target_memcpy_rect_async` – Copy a subvolume of data between devices asynchronously, `omp_target_memcpy` – Copy data between devices, Offload-Target Specifics

Reference:

  OpenMP specification v5.1, Section 3.8.6