omp_target_associate_ptr (GNU libgomp)

#### 3.7.11 `omp_target_associate_ptr` – Associate a device pointer with a host pointer ¶

Description:

  This routine associates storage on the host with storage on a device identified by device_num. The device pointer is usually obtained by calling `omp_target_alloc` or by other means (but not by using the `map` clauses or the `declare target` directive). The host pointer should point to memory that has a storage size of at least size.

  The device_offset parameter specifies the offset into device_ptr that is used as the base address for the device side of the mapping; the storage size should be at least device_offset plus size.

  After the association, the host pointer can be used in a `map` clause and in the `to` and `from` clauses of the `target update` directive to transfer data between the associated pointers. The reference count of such associated storage is infinite. The association can be removed by calling `omp_target_disassociate_ptr` which should be done before the lifetime of either storage ends.

  The routine returns nonzero (`EINVAL`) when the device_num invalid, for when the initial device or the associated device shares memory with the host. `omp_target_associate_ptr` returns zero if host_ptr points into already associated storage that is fully inside of a previously associated memory. Otherwise, if the association was successful zero is returned; if none of the cases above apply, nonzero (`EINVAL`) is returned.

  The `omp_target_is_present` routine can be used to test whether associated storage for a device pointer exists.

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

C/C++

  Prototype: | `int omp_target_associate_ptr(const void *host_ptr,`
  | `const void *device_ptr,`
  | `size_t size,`
  | `size_t device_offset,`
  | `int device_num)`

Fortran:

  Interface: | `integer(c_int) function omp_target_associate_ptr(host_ptr, &`
  | `device_ptr, size, device_offset, device_num) bind(C)`
  | `use, intrinsic :: iso_c_binding, only: c_ptr, c_int, c_size_t`
  | `type(c_ptr), value :: host_ptr, device_ptr`
  | `integer(c_size_t), value :: size, device_offset`
  | `integer(c_int), value :: device_num`

See also:

  `omp_target_disassociate_ptr` – Remove device–host pointer association, `omp_target_is_present` – Check whether storage is mapped, `omp_get_mapped_ptr` – Return device pointer to a host pointer, `omp_target_alloc` – Allocate device memory

Reference:

  OpenMP specification v5.1, Section 3.8.9