_gfortran_caf_transfer_between_remotes (The GNU Fortran Compiler)

#### 7.2.16 `_gfortran_caf_transfer_between_remotes` — Initiate data transfer between to remote images ¶

Synopsis:

  `void _gfortran_caf_transfer_between_remotes (caf_token_t dst_token, gfc_descriptor_t *opt_dst_desc, size_t *opt_dst_charlen, const int dst_image_index, const int dst_access_index, void *dst_add_data, const size_t dst_add_data_size, caf_token_t src_token, const gfc_descriptor_t *opt_src_desc, const size_t *opt_src_charlen, const int src_image_index, const int src_access_index, void *src_add_data, const size_t src_add_data_size, const size_t src_size, const bool scalar_transfer, int *dst_stat, int *src_stat, caf_team_t *dst_team, int *dst_team_number, caf_team_t *src_team, int *src_team_number)`

Description:

  Initiates a transfer of data from one remote image to another remote image. The call modifies the memory of the receiving remote image given by `dst_image_index`. The `src_image_index`’s memory is not modified. The call returns when the transfer has commenced.

Arguments:

  dst_token | intent(in) An opaque pointer identifying the coarray on the receiving image.
  opt_dst_desc | intent(inout) A pointer to the descriptor when the object identified by dst_token is an array with a descriptor. The parameter needs to be set to `NULL`, when dst_token identifies a scalar or is an array without a descriptor.
  opt_dst_charlen | intent(in) When the object to modify on the receiving image is a char array with deferred length, then this parameter needs to be set to point to its length. Else the parameter needs to be set to `NULL`.
  dst_image_index | intent(in) The ID of the receiving/destination remote image; must be a positive number. `this_image ()` is valid.
  dst_access_index | intent(in) The index of the accessor to execute on the receiving image as returned by `_gfortran_caf_get_remote_function_index ()`.
  dst_add_data | intent(inout) Additional data needed in the accessor on the receiving side. I.e., when an array reference uses a local variable v, it is transported in this structure and all references in the accessor are rewritten to access the member. The data in the structure of dst_add_data may be changed by the accessor, but these changes are lost to the calling Fortran program.
  dst_add_data_size | intent(in) The size of the dst_add_data structure.
  src_token | intent(in) An opaque pointer identifying the coarray on the sending image.
  opt_src_desc | intent(inout) A pointer to the descriptor when the object identified by src_token is an array with a descriptor. The parameter needs to be set to `NULL`, when src_token identifies a scalar or is an array without a descriptor.
  opt_src_charlen | intent(in) When the object to get from the source image is a char array with deferred length, then this parameter needs to be set to point to its length. Else the parameter needs to be set to `NULL`.
  src_image_index | intent(in) The ID of the sending/source remote image; must be a positive number. `this_image ()` is valid.
  src_access_index | intent(in) The index of the accessor to execute on the sending image as returned by `_gfortran_caf_get_remote_function_index ()`.
  src_add_data | intent(inout) Additional data needed in the accessor on the sending side. I.e., when an array reference uses a local variable v, it is transported in this structure and all references in the accessor are rewritten to access the member. The data in the structure of src_add_data may be changed by the accessor, but these changes are lost to the calling Fortran program.
  src_add_data_size | intent(in) The size of the src_add_data structure.
  src_size | intent(in) The size of data expected to be transferred between the images. If the data type to get is a string or string array, then this needs to be set to the byte size of each character, i.e. `4` for a `CHARACTER (KIND=4)` string. The length of the string is then given in `opt_src_charlen` and `opt_dst_charlen` (also for string arrays).
  scalar_transfer | intent(in) Is set to true when the data to be transferred between the two images is not an array with a descriptor.
  dst_stat | intent(out) When non-`NULL` give the result of the operation on the receiving side, i.e., zero on success and non-zero on error. When `NULL` and an error occurs, then an error message is printed and the program is terminated.
  src_stat | intent(out) When non-`NULL` give the result of the operation on the sending side, i.e., zero on success and non-zero on error. When `NULL` and an error occurs, then an error message is printed and the program is terminated.
  dst_team | intent(in) The opaque team handle as returned by `FORM TEAM`.
  dst_team_number | intent(in) The number of the team this access is to be part of.
  src_team | intent(in) The opaque team handle as returned by `FORM TEAM`.
  src_team_number | intent(in) The number of the team this access is to be part of.

Notes:

  It is permitted to have both `dst_image_index` and `src_image_index` equal the current image; the memory to send the data to and the memory to read for the data may (partially) overlap. The implementation has to take care that it handles this case, e.g. using `memmove` which handles (partially) overlapping memory.