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_tokenintent(in) An opaque pointer identifying the coarray on the receiving image.
opt_dst_descintent(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_charlenintent(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_indexintent(in) The ID of the receiving/destination remote image; must be a positive number. this_image () is valid.
dst_access_indexintent(in) The index of the accessor to execute on the receiving image as returned by _gfortran_caf_get_remote_function_index ().
dst_add_dataintent(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_sizeintent(in) The size of the dst_add_data structure.
src_tokenintent(in) An opaque pointer identifying the coarray on the sending image.
opt_src_descintent(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_charlenintent(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_indexintent(in) The ID of the sending/source remote image; must be a positive number. this_image () is valid.
src_access_indexintent(in) The index of the accessor to execute on the sending image as returned by _gfortran_caf_get_remote_function_index ().
src_add_dataintent(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_sizeintent(in) The size of the src_add_data structure.
src_sizeintent(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_transferintent(in) Is set to true when the data to be transfered between the two images is not an array with a descriptor.
dst_statintent(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_statintent(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_teamintent(in) The opaque team handle as returned by FORM TEAM.
dst_team_numberintent(in) The number of the team this access is to be part of.
src_teamintent(in) The opaque team handle as returned by FORM TEAM.
src_team_numberintent(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.