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.
Because the interface binds directly to a C language function the function assumes C memory
ordering.
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.
The omp_target_memcpy_rect_async routine requires an explicit interface and so might not be
provided in omp_lib.h.
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.
When
called
from
within
a
target
region
the
effect
is
unspecified.