Function ABI Documentation#

_gfortran_caf_init — Initialiation function#

void _gfortran_caf_init(int *argc, char ***argv)#

This function is called at startup of the program before the Fortran main program, if the latter has been compiled with -fcoarray=lib. It takes as arguments the command-line arguments of the program. It is permitted to pass two NULL pointers as argument; if non- NULL, the library is permitted to modify the arguments.

Parameters:

argc – intent(inout) An integer pointer with the number of arguments passed to the program or NULL.
argv – intent(inout) A pointer to an array of strings with the command-line arguments or NULL.

Note

The function is modelled after the initialization function of the Message Passing Interface (MPI) specification. Due to the way coarray registration works, it might not be the first call to the library. If the main program is not written in Fortran and only a library uses coarrays, it can happen that this function is never called. Therefore, it is recommended that the library does not rely on the passed arguments and whether the call has been done.

_gfortran_caf_finish — Finalization function#

void _gfortran_caf_finish(void)#: This function is called at the end of the Fortran main program, if it has been compiled with the -fcoarray=lib option.

Note

For non-Fortran programs, it is recommended to call the function at the end of the main program. To ensure that the shutdown is also performed for programs where this function is not explicitly invoked, for instance non-Fortran programs or calls to the system’s exit() function, the library can use a destructor function. Note that programs can also be terminated using the STOP and ERROR STOP statements; those use different library calls.

_gfortran_caf_this_image — Querying the image number#

int _gfortran_caf_this_image(int distance)#

This function returns the current image number, which is a positive number.

Parameters:: distance – As specified for the this_image intrinsic in TS18508. Shall be a non-negative number.

Note

If the Fortran intrinsic this_image is invoked without an argument, which is the only permitted form in Fortran 2008, GCC passes 0 as first argument.

_gfortran_caf_num_images — Querying the maximal number of images#

int _gfortran_caf_num_images(int distance, int failed)#

This function returns the number of images in the current team, if distance is 0 or the number of images in the parent team at the specified distance. If failed is -1, the function returns the number of all images at the specified distance; if it is 0, the function returns the number of nonfailed images, and if it is 1, it returns the number of failed images.

Parameters:

distance – the distance from this image to the ancestor. Shall be positive.
failed – shall be -1, 0, or 1

Note

This function follows TS18508. If the num_image intrinsic has no arguments, then the compiler passes distance=0 and failed=-1 to the function.

_gfortran_caf_image_status — Query the status of an image#

int _gfortran_caf_image_status(int image, caf_team_t *team)#

Get the status of the image given by the id image of the team given by team. Valid results are zero, for image is ok, STAT_STOPPED_IMAGE from the ISO_FORTRAN_ENV module to indicate that the image has been stopped and STAT_FAILED_IMAGE also from ISO_FORTRAN_ENV to indicate that the image has executed a FAIL IMAGE statement.

Parameters:

image – the positive scalar id of the image in the current TEAM.
team – optional; team on the which the inquiry is to be performed.

Note

This function follows TS18508. Because team-functionality is not yet implemented a null-pointer is passed for the team argument at the moment.

_gfortran_caf_failed_images — Get an array of the indexes of the failed images#

int _gfortran_caf_failed_images(caf_team_t *team, int *kind)#

Get an array of image indexes in the current team that have failed. The array is sorted ascendingly. When team is not provided the current team is to be used. When kind is provided then the resulting array is of that integer kind else it is of default integer kind. The returns an unallocated size zero array when no images have failed.

Parameters:

team – optional; team on the which the inquiry is to be performed.
image – optional; the kind of the resulting integer array.

Note

This function follows TS18508. Because team-functionality is not yet implemented a null-pointer is passed for the team argument at the moment.

_gfortran_caf_stopped_images — Get an array of the indexes of the stopped images#

int _gfortran_caf_stopped_images(caf_team_t *team, int *kind)#

Get an array of image indexes in the current team that have stopped. The array is sorted ascendingly. When team is not provided the current team is to be used. When kind is provided then the resulting array is of that integer kind else it is of default integer kind. The returns an unallocated size zero array when no images have failed.

Parameters:

team – optional; team on the which the inquiry is to be performed.
image – optional; the kind of the resulting integer array.

Note

This function follows TS18508. Because team-functionality is not yet implemented a null-pointer is passed for the team argument at the moment.

_gfortran_caf_register — Registering coarrays#

void caf_register(size_t size, caf_register_t type, caf_token_t *token, gfc_descriptor_t *desc, int *stat, char *errmsg, size_t errmsg_len)#

Registers memory for a coarray and creates a token to identify the coarray. The routine is called for both coarrays with SAVE attribute and using an explicit ALLOCATE statement. If an error occurs and STAT is a NULL pointer, the function shall abort with printing an error message and starting the error termination. If no error occurs and STAT is present, it shall be set to zero. Otherwise, it shall be set to a positive value and, if not- NULL, ERRMSG shall be set to a string describing the failure. The routine shall register the memory provided in the DATA -component of the array descriptor DESC, when that component is non- NULL, else it shall allocate sufficient memory and provide a pointer to it in the DATA -component of DESC. The array descriptor has rank zero, when a scalar object is to be registered and the array descriptor may be invalid after the call to _gfortran_caf_register. When an array is to be allocated the descriptor persists.

Parameters:

size – For normal coarrays, the byte size of the coarray to be allocated; for lock types and event types, the number of elements.
type – one of the caf_register_t types.
token – intent(out) An opaque pointer identifying the coarray.
desc – intent(inout) The (pseudo) array descriptor.
stat – intent(out) For allocatable coarrays, stores the STAT=; may be NULL
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL
errmsg_len – the buffer size of errmsg.

Note

Nonallocatable coarrays have to be registered prior use from remote images. In order to guarantee this, they have to be registered before the main program. This can be achieved by creating constructor functions. That is what GCC does such that also for nonallocatable coarrays the memory is allocated and no static memory is used. The token permits to identify the coarray; to the processor, the token is a nonaliasing pointer. The library can, for instance, store the base address of the coarray in the token, some handle or a more complicated struct. The library may also store the array descriptor DESC when its rank is non-zero.

For lock types, the value shall only be used for checking the allocation status. Note that for critical blocks, the locking is only required on one image; in the locking statement, the processor shall always pass an image index of one for critical-block lock variables (CAF_REGTYPE_CRITICAL). For lock types and critical-block variables, the initial value shall be unlocked (or, respectively, not in critical section) such as the value false; for event types, the initial state should be no event, e.g. zero.

_gfortran_caf_deregister — Deregistering coarrays#

void caf_deregister(caf_token_t *token, caf_deregister_t type, int *stat, char *errmsg, size_t errmsg_len)#

Called to free or deregister the memory of a coarray; the processor calls this function for automatic and explicit deallocation. In case of an error, this function shall fail with an error message, unless the STAT variable is not null. The library is only expected to free memory it allocated itself during a call to _gfortran_caf_register.

Parameters:

token – the token to free.
type – the type of action to take for the coarray. A CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY is allowed only for allocatable or pointer components of derived type coarrays. The action only deallocates the local memory without deleting the token.
stat – intent(out) Stores the STAT=; may be NULL
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL
errmsg_len – the buffer size of errmsg.

Note

For nonalloatable coarrays this function is never called. If a cleanup is required, it has to be handled via the finish, stop and error stop functions, and via destructors.

_gfortran_caf_is_present — Query whether an allocatable or pointer component in a derived type coarray is allocated#

void _gfortran_caf_is_present(caf_token_t token, int image_index, gfc_reference_t *ref)#

Used to query the coarray library whether an allocatable component in a derived type coarray is allocated on a remote image.

Parameters:

token – An opaque pointer identifying the coarray.
image_index – The ID of the remote image; must be a positive number.
ref – A chain of references to address the allocatable or pointer component in the derived type coarray. The object reference needs to be a scalar or a full array reference, respectively.

_gfortran_caf_send — Sending data from a local image to a remote image#

void _gfortran_caf_send(caf_token_t token, size_t offset, int image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector, gfc_descriptor_t *src, int dst_kind, int src_kind, bool may_require_tmp, int *stat)#

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

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
offset – intent(in) By which amount of bytes the actual data is shifted compared to the base address of the coarray.
image_index – intent(in) The ID of the remote image; must be a positive number.
dest – intent(in) Array descriptor for the remote image for the bounds and the size. The base_addr shall not be accessed.
dst_vector – intent(in) If not NULL, it contains the vector subscript of the destination array; the values are relative to the dimension triplet of the dest argument.
src – intent(in) Array descriptor of the local array to be transferred to the remote image
dst_kind – intent(in) Kind of the destination argument
src_kind – intent(in) Kind of the source argument
may_require_tmp – intent(in) The variable is false when it is known at compile time that the dest and src either cannot overlap or overlap (fully or partially) such that walking src and dest in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value is true.
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.

Note

It is permitted to have image_index equal the current image; the memory of the send-to and the send-from might (partially) overlap in that case. The implementation has to take care that it handles this case, e.g. using memmove which handles (partially) overlapping memory. If may_require_tmp is true, the library might additionally create a temporary variable, unless additional checks show that this is not required (e.g. because walking backward is possible or because both arrays are contiguous and memmove takes care of overlap issues).

Note that the assignment of a scalar to an array is permitted. In addition, the library has to handle numeric-type conversion and for strings, padding and different character kinds.

_gfortran_caf_get — Getting data from a remote image#

void _gfortran_caf_get(caf_token_t token, size_t offset, int image_index, gfc_descriptor_t *src, caf_vector_t *src_vector, gfc_descriptor_t *dest, int src_kind, int dst_kind, bool may_require_tmp, int *stat)#

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

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
offset – intent(in) By which amount of bytes the actual data is shifted compared to the base address of the coarray.
image_index – intent(in) The ID of the remote image; must be a positive number.
dest – intent(out) Array descriptor of the local array to store the data retrieved from the remote image
src – intent(in) Array descriptor for the remote image for the bounds and the size. The base_addr shall not be accessed.
src_vector – intent(in) If not NULL, it contains the vector subscript of the source array; the values are relative to the dimension triplet of the src argument.
dst_kind – intent(in) Kind of the destination argument
src_kind – intent(in) Kind of the source argument
may_require_tmp – intent(in) The variable is false when it is known at compile time that the dest and src either cannot overlap or overlap (fully or partially) such that walking src and dest in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value is true.
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.

Note

Note that the library has to handle numeric-type conversion and for strings, padding and different character kinds.

_gfortran_caf_sendget — Sending data between remote images#

void _gfortran_caf_sendget(caf_token_t dst_token, size_t dst_offset, int dst_image_index, gfc_descriptor_t *dest, caf_vector_t *dst_vector, caf_token_t src_token, size_t src_offset, int src_image_index, gfc_descriptor_t *src, caf_vector_t *src_vector, int dst_kind, int src_kind, bool may_require_tmp, int *stat)#

Called to send a scalar, an array section or a whole array from a remote image identified by the src_image_index to a remote image identified by the dst_image_index.

Parameters:

dst_token – intent(in) An opaque pointer identifying the destination coarray.
dst_offset – intent(in) By which amount of bytes the actual data is shifted compared to the base address of the destination coarray.
dst_image_index – intent(in) The ID of the destination remote image; must be a positive number.
dest – intent(in) Array descriptor for the destination remote image for the bounds and the size. The base_addr shall not be accessed.
dst_vector – intent(int) If not NULL, it contains the vector subscript of the destination array; the values are relative to the dimension triplet of the dest argument.
src_token – intent(in) An opaque pointer identifying the source coarray.
src_offset – intent(in) By which amount of bytes the actual data is shifted compared to the base address of the source coarray.
src_image_index – intent(in) The ID of the source remote image; must be a positive number.
src – intent(in) Array descriptor of the local array to be transferred to the remote image.
src_vector – intent(in) Array descriptor of the local array to be transferred to the remote image
dst_kind – intent(in) Kind of the destination argument
src_kind – intent(in) Kind of the source argument
may_require_tmp – intent(in) The variable is false when it is known at compile time that the dest and src either cannot overlap or overlap (fully or partially) such that walking src and dest in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value is true.
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.

Note

It is permitted to have the same image index for both src_image_index and dst_image_index ; the memory of the send-to and the send-from might (partially) overlap in that case. The implementation has to take care that it handles this case, e.g. using memmove which handles (partially) overlapping memory. If may_require_tmp is true, the library might additionally create a temporary variable, unless additional checks show that this is not required (e.g. because walking backward is possible or because both arrays are contiguous and memmove takes care of overlap issues).

Note that the assignment of a scalar to an array is permitted. In addition, the library has to handle numeric-type conversion and for strings, padding and different character kinds.

_gfortran_caf_send_by_ref — Sending data from a local image to a remote image with enhanced referencing options#

void _gfortran_caf_send_by_ref(caf_token_t token, int image_index, gfc_descriptor_t *src, caf_reference_t *refs, int dst_kind, int src_kind, bool may_require_tmp, bool dst_reallocatable, int *stat, int dst_type)#

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

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
image_index – intent(in) The ID of the remote image; must be a positive number.
src – intent(in) Array descriptor of the local array to be transferred to the remote image
refs – intent(in) The references on the remote array to store the data given by src. Guaranteed to have at least one entry.
dst_kind – intent(in) Kind of the destination argument
src_kind – intent(in) Kind of the source argument
may_require_tmp – intent(in) The variable is false when it is known at compile time that the dest and src either cannot overlap or overlap (fully or partially) such that walking src and dest in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value is true.
dst_reallocatable – intent(in) Set when the destination is of allocatable or pointer type and the refs will allow reallocation, i.e., the ref is a full array or component ref.
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.
dst_type – intent(in) Give the type of the destination. When the destination is not an array, than the precise type, e.g. of a component in a derived type, is not known, but provided here.

Note

Note that the assignment of a scalar to an array is permitted. In addition, the library has to handle numeric-type conversion and for strings, padding and different character kinds.

Because of the more complicated references possible some operations may be unsupported by certain libraries. The library is expected to issue a precise error message why the operation is not permitted.

_gfortran_caf_get_by_ref — Getting data from a remote image using enhanced references#

void _gfortran_caf_get_by_ref(caf_token_t token, int image_index, caf_reference_t *refs, gfc_descriptor_t *dst, int dst_kind, int src_kind, bool may_require_tmp, bool dst_reallocatable, int *stat, int src_type)#

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

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
image_index – intent(in) The ID of the remote image; must be a positive number.
refs – intent(in) The references to apply to the remote structure to get the data.
dst – intent(in) Array descriptor of the local array to store the data transferred from the remote image. May be reallocated where needed and when DST_REALLOCATABLE allows it.
dst_kind – intent(in) Kind of the destination argument
src_kind – intent(in) Kind of the source argument
may_require_tmp – intent(in) The variable is false when it is known at compile time that the dest and src either cannot overlap or overlap (fully or partially) such that walking src and dest in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value is true.
dst_reallocatable – intent(in) Set when DST is of allocatable or pointer type and its refs allow reallocation, i.e., the full array or a component is referenced.
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.
src_type – intent(in) Give the type of the source. When the source is not an array, than the precise type, e.g. of a component in a derived type, is not known, but provided here.

Note

Note that the library has to handle numeric-type conversion and for strings, padding and different character kinds.

_gfortran_caf_sendget_by_ref — Sending data between remote images using enhanced references on both sides#

void _gfortran_caf_sendget_by_ref(caf_token_t dst_token, int dst_image_index, caf_reference_t *dst_refs, caf_token_t src_token, int src_image_index, caf_reference_t *src_refs, int dst_kind, int src_kind, bool may_require_tmp, int *dst_stat, int *src_stat, int dst_type, int src_type)#

Called to send a scalar, an array section or a whole array from a remote image identified by the src_image_index to a remote image identified by the dst_image_index.

Parameters:

dst_token – intent(in) An opaque pointer identifying the destination coarray.
dst_image_index – intent(in) The ID of the destination remote image; must be a positive number.
dst_refs – intent(in) The references on the remote array to store the data given by the source. Guaranteed to have at least one entry.
src_token – intent(in) An opaque pointer identifying the source coarray.
src_image_index – intent(in) The ID of the source remote image; must be a positive number.
src_refs – intent(in) The references to apply to the remote structure to get the data.
dst_kind – intent(in) Kind of the destination argument
src_kind – intent(in) Kind of the source argument
may_require_tmp – intent(in) The variable is false when it is known at compile time that the dest and src either cannot overlap or overlap (fully or partially) such that walking src and dest in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value is true.
dst_stat – intent(out) when non- NULL give the result of the send-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.
src_stat – intent(out) When non- NULL give the result of the get-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.
dst_type – intent(in) Give the type of the destination. When the destination is not an array, than the precise type, e.g. of a component in a derived type, is not known, but provided here.
src_type – intent(in) Give the type of the source. When the source is not an array, than the precise type, e.g. of a component in a derived type, is not known, but provided here.

Note

Note that the assignment of a scalar to an array is permitted. In addition, the library has to handle numeric-type conversion and for strings, padding and different character kinds.

_gfortran_caf_lock — Locking a lock variable#

void _gfortran_caf_lock(caf_token_t token, size_t index, int image_index, int *acquired_lock, int *stat, char *errmsg, size_t errmsg_len)#

Acquire a lock on the given image on a scalar locking variable or for the given array element for an array-valued variable. If the acquired_lock is NULL, the function returns after having obtained the lock. If it is non- NULL, then acquired_lock is assigned the value true (one) when the lock could be obtained and false (zero) otherwise. Locking a lock variable which has already been locked by the same image is an error.

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
index – intent(in) Array index; first array index is 0. For scalars, it is always 0.
image_index – intent(in) The ID of the remote image; must be a positive number.
acquired_lock – intent(out) If not NULL, it returns whether lock could be obtained.
stat – intent(out) Stores the STAT=; may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg

Note

This function is also called for critical blocks; for those, the array index is always zero and the image index is one. Libraries are permitted to use other images for critical-block locking variables.

_gfortran_caf_lock — Unlocking a lock variable#

void _gfortran_caf_unlock(caf_token_t token, size_t index, int image_index, int *stat, char *errmsg, size_t errmsg_len)#

Release a lock on the given image on a scalar locking variable or for the given array element for an array-valued variable. Unlocking a lock variable which is unlocked or has been locked by a different image is an error.

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
index – intent(in) Array index; first array index is 0. For scalars, it is always 0.
image_index – intent(in) The ID of the remote image; must be a positive number.
stat – intent(out) For allocatable coarrays, stores the STAT=; may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg

Note

This function is also called for critical block; for those, the array index is always zero and the image index is one. Libraries are permitted to use other images for critical-block locking variables.

_gfortran_caf_event_post — Post an event#

void _gfortran_caf_event_post(caf_token_t token, size_t index, int image_index, int *stat, char *errmsg, size_t errmsg_len)#

Increment the event count of the specified event variable.

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
index – intent(in) Array index; first array index is 0. For scalars, it is always 0.
image_index – intent(in) The ID of the remote image; must be a positive number; zero indicates the current image, when accessed noncoindexed.
stat – intent(out) Stores the STAT=; may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg

Note

This acts like an atomic add of one to the remote image’s event variable. The statement is an image-control statement but does not imply sync memory. Still, all preceeding push communications of this image to the specified remote image have to be completed before event_wait on the remote image returns.

_gfortran_caf_event_wait — Wait that an event occurred#

void _gfortran_caf_event_wait(caf_token_t token, size_t index, int until_count, int *stat, char *errmsg, size_t errmsg_len)#

Wait until the event count has reached at least the specified until_count ; if so, atomically decrement the event variable by this amount and return.

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
index – intent(in) Array index; first array index is 0. For scalars, it is always 0.
until_count – intent(in) The number of events which have to be available before the function returns.
stat – intent(out) Stores the STAT=; may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg

Note

This function only operates on a local coarray. It acts like a loop checking atomically the value of the event variable, breaking if the value is greater or equal the requested number of counts. Before the function returns, the event variable has to be decremented by the requested until_count value. A possible implementation would be a busy loop for a certain number of spins (possibly depending on the number of threads relative to the number of available cores) followed by another waiting strategy such as a sleeping wait (possibly with an increasing number of sleep time) or, if possible, a futex wait.

The statement is an image-control statement but does not imply sync memory. Still, all preceeding push communications of this image to the specified remote image have to be completed before event_wait on the remote image returns.

_gfortran_caf_event_query — Query event count#

void _gfortran_caf_event_query(caf_token_t token, size_t index, int image_index, int *count, int *stat)#

Return the event count of the specified event variable.

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
index – intent(in) Array index; first array index is 0. For scalars, it is always 0.
image_index – intent(in) The ID of the remote image; must be a positive number; zero indicates the current image when accessed noncoindexed.
count – intent(out) The number of events currently posted to the event variable.
stat – intent(out) Stores the STAT=; may be NULL.

Note

The typical use is to check the local event variable to only call event_wait when the data is available. However, a coindexed variable is permitted; there is no ordering or synchronization implied. It acts like an atomic fetch of the value of the event variable.

_gfortran_caf_sync_all — All-image barrier#

void _gfortran_caf_sync_all(int *stat, char *errmsg, size_t errmsg_len)#

Synchronization of all images in the current team; the program only continues on a given image after this function has been called on all images of the current team. Additionally, it ensures that all pending data transfers of previous segment have completed.

Parameters:

stat – intent(out) Stores the status STAT= and may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg

_gfortran_caf_sync_images — Barrier for selected images#

void _gfortran_caf_sync_images(int count, int images[], int *stat, char *errmsg, size_t errmsg_len)#

Synchronization between the specified images; the program only continues on a given image after this function has been called on all images specified for that image. Note that one image can wait for all other images in the current team (e.g. via sync images(*)) while those only wait for that specific image. Additionally, sync images ensures that all pending data transfers of previous segments have completed.

Parameters:

count – intent(in) The number of images which are provided in the next argument. For a zero-sized array, the value is zero. For sync images (*), the value is -1.
images – intent(in) An array with the images provided by the user. If count is zero, a NULL pointer is passed.
stat – intent(out) Stores the status STAT= and may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg

_gfortran_caf_sync_memory — Wait for completion of segment-memory operations#

void _gfortran_caf_sync_memory(int *stat, char *errmsg, size_t errmsg_len)#

Acts as optimization barrier between different segments. It also ensures that all pending memory operations of this image have been completed.

Parameters:

stat – intent(out) Stores the status STAT= and may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg

Note

A simple implementation could be __asm__ __volatile__ ("":::"memory") to prevent code movements.

_gfortran_caf_error_stop — Error termination with exit code#

void _gfortran_caf_error_stop(int error)#

Invoked for an ERROR STOP statement which has an integer argument. The function should terminate the program with the specified exit code.

Parameters:: error – intent(in) The exit status to be used.

_gfortran_caf_error_stop_str — Error termination with string#

void _gfortran_caf_error_stop(const char *string, size_t len)#

Invoked for an ERROR STOP statement which has a string as argument. The function should terminate the program with a nonzero-exit code.

Parameters:

string – intent(in) the error message (not zero terminated)
len – intent(in) the length of the string

_gfortran_caf_fail_image — Mark the image failed and end its execution#

void _gfortran_caf_fail_image()#: Invoked for an FAIL IMAGE statement. The function should terminate the current image.

Note

This function follows TS18508.

_gfortran_caf_atomic_define — Atomic variable assignment#

void _gfortran_caf_atomic_define(caf_token_t token, size_t offset, int image_index, void *value, int *stat, int type, int kind)#

Assign atomically a value to an integer or logical variable.

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
offset – intent(in) By which amount of bytes the actual data is shifted compared to the base address of the coarray.
image_index – intent(in) The ID of the remote image; must be a positive number; zero indicates the current image when used noncoindexed.
value – intent(in) the value to be assigned, passed by reference
stat – intent(out) Stores the status STAT= and may be NULL.
type – intent(in) The data type, i.e. BT_INTEGER (1) or BT_LOGICAL (2).
kind – intent(in) The kind value (only 4; always int)

_gfortran_caf_atomic_ref — Atomic variable reference#

void _gfortran_caf_atomic_ref(caf_token_t token, size_t offset, int image_index, void *value, int *stat, int type, int kind)#

Reference atomically a value of a kind-4 integer or logical variable.

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
offset – intent(in) By which amount of bytes the actual data is shifted compared to the base address of the coarray.
image_index – intent(in) The ID of the remote image; must be a positive number; zero indicates the current image when used noncoindexed.
value – intent(out) The variable assigned the atomically referenced variable.
stat – intent(out) Stores the status STAT= and may be NULL.
type – the data type, i.e. BT_INTEGER (1) or BT_LOGICAL (2).
kind – The kind value (only 4; always int)

_gfortran_caf_atomic_cas — Atomic compare and swap#

void _gfortran_caf_atomic_cas(caf_token_t token, size_t offset, int image_index, void *old, void *compare, void *new_val, int *stat, int type, int kind)#

Atomic compare and swap of a kind-4 integer or logical variable. Assigns atomically the specified value to the atomic variable, if the latter has the value specified by the passed condition value.

Parameters:

token – intent(in) An opaque pointer identifying the coarray.
offset – intent(in) By which amount of bytes the actual data is shifted compared to the base address of the coarray.
image_index – intent(in) The ID of the remote image; must be a positive number; zero indicates the current image when used noncoindexed.
old – intent(out) The value which the atomic variable had just before the cas operation.
compare – intent(in) The value used for comparision.
new_val – intent(in) The new value for the atomic variable, assigned to the atomic variable, if compare equals the value of the atomic variable.
stat – intent(out) Stores the status STAT= and may be NULL.
type – intent(in) the data type, i.e. BT_INTEGER (1) or BT_LOGICAL (2).
kind – intent(in) The kind value (only 4; always int)

_gfortran_caf_atomic_op — Atomic operation#

void _gfortran_caf_atomic_op(int op, caf_token_t token, size_t offset, int image_index, void *value, void *old, int *stat, int type, int kind)#

Apply an operation atomically to an atomic integer or logical variable. After the operation, old contains the value just before the operation, which, respectively, adds (GFC_CAF_ATOMIC_ADD) atomically the value to the atomic integer variable or does a bitwise AND, OR or exclusive OR between the atomic variable and value ; the result is then stored in the atomic variable.

Parameters:

op – intent(in) the operation to be performed; possible values GFC_CAF_ATOMIC_ADD (1), GFC_CAF_ATOMIC_AND (2), GFC_CAF_ATOMIC_OR (3), GFC_CAF_ATOMIC_XOR (4).
token – intent(in) An opaque pointer identifying the coarray.
offset – intent(in) By which amount of bytes the actual data is shifted compared to the base address of the coarray.
image_index – intent(in) The ID of the remote image; must be a positive number; zero indicates the current image when used noncoindexed.
old – intent(out) The value which the atomic variable had just before the atomic operation.
val – intent(in) The new value for the atomic variable, assigned to the atomic variable, if compare equals the value of the atomic variable.
stat – intent(out) Stores the status STAT= and may be NULL.
type – intent(in) the data type, i.e. BT_INTEGER (1) or BT_LOGICAL (2)
kind – intent(in) the kind value (only 4; always int)

_gfortran_caf_co_broadcast — Sending data to all images#

void _gfortran_caf_co_broadcast(gfc_descriptor_t *a, int source_image, int *stat, char *errmsg, size_t errmsg_len)#

Distribute a value from a given image to all other images in the team. Has to be called collectively.

Parameters:

a – intent(inout) An array descriptor with the data to be broadcasted (on source_image) or to be received (other images).
source_image – intent(in) The ID of the image from which the data should be broadcasted.
stat – intent(out) Stores the status STAT= and may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg.

_gfortran_caf_co_max — Collective maximum reduction#

void _gfortran_caf_co_max(gfc_descriptor_t *a, int result_image, int *stat, char *errmsg, int a_len, size_t errmsg_len)#

Calculates for each array element of the variable a the maximum value for that element in the current team; if result_image has the value 0, the result shall be stored on all images, otherwise, only on the specified image. This function operates on numeric values and character strings.

Parameters:

a – intent(inout) An array descriptor for the data to be processed. On the destination image(s) the result overwrites the old content.
result_image – intent(in) The ID of the image to which the reduced value should be copied to; if zero, it has to be copied to all images.
stat – intent(out) Stores the status STAT= and may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
a_len – intent(in) the string length of argument a
errmsg_len – intent(in) the buffer size of errmsg

Note

If result_image is nonzero, the data in the array descriptor a on all images except of the specified one become undefined; hence, the library may make use of this.

_gfortran_caf_co_min — Collective minimum reduction#

void _gfortran_caf_co_min(gfc_descriptor_t *a, int result_image, int *stat, char *errmsg, int a_len, size_t errmsg_len)#

Calculates for each array element of the variable a the minimum value for that element in the current team; if result_image has the value 0, the result shall be stored on all images, otherwise, only on the specified image. This function operates on numeric values and character strings.

Parameters:

a – intent(inout) An array descriptor for the data to be processed. On the destination image(s) the result overwrites the old content.
result_image – intent(in) The ID of the image to which the reduced value should be copied to; if zero, it has to be copied to all images.
stat – intent(out) Stores the status STAT= and may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
a_len – intent(in) the string length of argument a
errmsg_len – intent(in) the buffer size of errmsg

Note

If result_image is nonzero, the data in the array descriptor a on all images except of the specified one become undefined; hence, the library may make use of this.

_gfortran_caf_co_sum — Collective summing reduction#

void _gfortran_caf_co_sum(gfc_descriptor_t *a, int result_image, int *stat, char *errmsg, size_t errmsg_len)#

Calculates for each array element of the variable a the sum of all values for that element in the current team; if result_image has the value 0, the result shall be stored on all images, otherwise, only on the specified image. This function operates on numeric values only.

Parameters:

a – intent(inout) An array descriptor with the data to be processed. On the destination image(s) the result overwrites the old content.
result_image – intent(in) The ID of the image to which the reduced value should be copied to; if zero, it has to be copied to all images.
stat – intent(out) Stores the status STAT= and may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
errmsg_len – intent(in) the buffer size of errmsg

Note

If result_image is nonzero, the data in the array descriptor a on all images except of the specified one become undefined; hence, the library may make use of this.

_gfortran_caf_co_reduce — Generic collective reduction#

void _gfortran_caf_co_reduce(gfc_descriptor_t *a, void *(*opr)(void*, void*), int opr_flags, int result_image, int *stat, char *errmsg, int a_len, size_t errmsg_len)#

Calculates for each array element of the variable a the reduction value for that element in the current team; if result_image has the value 0, the result shall be stored on all images, otherwise, only on the specified image. The opr is a pure function doing a mathematically commutative and associative operation.

Parameters:

a – intent(inout) An array descriptor with the data to be processed. On the destination image(s) the result overwrites the old content.
opr – intent(in) Function pointer to the reduction function
opr_flags – intent(in) Flags regarding the reduction function
result_image – intent(in) The ID of the image to which the reduced value should be copied to; if zero, it has to be copied to all images.
stat – intent(out) Stores the status STAT= and may be NULL.
errmsg – intent(out) When an error occurs, this will be set to an error message; may be NULL.
a_len – intent(in) the string length of argument a
errmsg_len – intent(in) the buffer size of errmsg

Note

If result_image is nonzero, the data in the array descriptor a on all images except of the specified one become undefined; hence, the library may make use of this.

For character arguments, the result is passed as first argument, followed by the result string length, next come the two string arguments, followed by the two hidden string length arguments. With C binding, there are no hidden arguments and by-reference passing and either only a single character is passed or an array descriptor.

Some basic guidelines for editing this document:

The intrinsic procedures are to be listed in alphabetical order.
The generic name is to be used.
The specific names are included in the function index and in a table at the end of the node (See ABS entry).
Try to maintain the same style for each entry.