_gfortran_caf_get_from_remote (The GNU Fortran Compiler)

#### 7.2.13 `_gfortran_caf_get_from_remote` — Getting data from a remote image using a remote side accessor ¶

Synopsis:

  `void _gfortran_caf_get_from_remote (caf_token_t token, const gfc_descriptor_t *opt_src_desc, const size_t *opt_src_charlen, const int image_index, const size_t dst_size, void **dst_data, size_t *opt_dst_charlen, gfc_descriptor_t *opt_dst_desc, const bool may_realloc_dst, const int getter_index, void *get_data, const size_t get_data_size, int *stat, caf_team_t *team, int *team_number)`

Description:

  Called to get a scalar, an array section or a whole array from a remote image identified by the image_index.

Arguments:

  token | intent(in) An opaque pointer identifying the coarray.
  opt_src_desc | intent(in) A pointer to the descriptor when the object identified by token is an array with a descriptor. The parameter needs to be set to `NULL`, when token identifies a scalar.
  opt_src_charlen | intent(in) When the object to get 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`.
  image_index | intent(in) The ID of the remote image; must be a positive number. `this_image ()` is valid.
  dst_size | intent(in) The size of data expected to be transferred from the remote image. 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 returned in `opt_dst_charlen` (also for string arrays).
  dst_data | intent(inout) A pointer to the address the data is stored. To prevent copying of data into an output buffer the address to the live data is returned here. When a descriptor is provided also its data-member is set to that address. When may_realloc_dst is set, then the memory may be reallocated by the remote function, which needs to be replicated by this function.
  opt_dst_charlen | intent(inout) When a char array is returned, this parameter is set to the length where applicable. The value can also be read to prevent reallocation in the accessor.
  opt_dst_desc | intent(inout) When a descriptor array is returned, it is stored in the memory pointed to by this optional parameter. When may_realloc_dst is set, then the descriptor may be changed, i.e. its bounds, but upto now not its rank.
  may_realloc_dst | intent(in) Set when the returned data may require reallocation of the output buffer in dst_data or opt_dst_desc.
  getter_index | intent(in) The index of the accessor to execute as returned by `_gfortran_caf_get_remote_function_index ()`.
  get_data | intent(inout) Additional data needed in the accessor. 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 get_data may be changed by the accessor, but these changes are lost to the calling Fortran program.
  get_data_size | intent(in) The size of the get_data structure.
  stat | intent(out) When non-`NULL` give the result of the operation, 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.
  team | intent(in) The opaque team handle as returned by `FORM TEAM`.
  team_number | intent(in) The number of the team this access is to be part of.

Notes:

  It is permitted to have `image_index` equal the current image; the memory to get and the memory to store 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.