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 twoNULL
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 passes0
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
andfailed=-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 byteam
. 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 andSTAT_FAILED_IMAGE
also from ISO_FORTRAN_ENV to indicate that the image has executed aFAIL 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. Whenteam
is not provided the current team is to be used. Whenkind
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. Whenteam
is not provided the current team is to be used. Whenkind
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 explicitALLOCATE
statement. If an error occurs andSTAT
is aNULL
pointer, the function shall abort with printing an error message and starting the error termination. If no error occurs andSTAT
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 theDATA
-component of the array descriptorDESC
, when that component is non-NULL
, else it shall allocate sufficient memory and provide a pointer to it in theDATA
-component ofDESC
. 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 thedest
andsrc
either cannot overlap or overlap (fully or partially) such that walkingsrc
anddest
in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value istrue
.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. usingmemmove
which handles (partially) overlapping memory. Ifmay_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 andmemmove
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 thedest
andsrc
either cannot overlap or overlap (fully or partially) such that walkingsrc
anddest
in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value istrue
.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. usingmemmove
which handles (partially) overlapping memory. Ifmay_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 andmemmove
takes care of overlap issues).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 thedst_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 thedest
andsrc
either cannot overlap or overlap (fully or partially) such that walkingsrc
anddest
in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value istrue
.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
anddst_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. usingmemmove
which handles (partially) overlapping memory. Ifmay_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 andmemmove
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 thedest
andsrc
either cannot overlap or overlap (fully or partially) such that walkingsrc
anddest
in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value istrue
.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. WhenNULL
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
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. usingmemmove
which handles (partially) overlapping memory. Ifmay_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 andmemmove
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.
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 thedest
andsrc
either cannot overlap or overlap (fully or partially) such that walkingsrc
anddest
in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value istrue
.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. WhenNULL
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
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. usingmemmove
which handles (partially) overlapping memory. Ifmay_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 andmemmove
takes care of overlap issues).Note that 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_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 thedst_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 thedest
andsrc
either cannot overlap or overlap (fully or partially) such that walkingsrc
anddest
in element wise element order (honoring the stride value) will not lead to wrong results. Otherwise, the value istrue
.dst_stat – intent(out) when non-
NULL
give the result of the send-operation, i.e., zero on success and non-zero on error. WhenNULL
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. WhenNULL
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
It is permitted to have the same image index for both
src_image_index
anddst_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. usingmemmove
which handles (partially) overlapping memory. Ifmay_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 andmemmove
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.
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_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
isNULL
, the function returns after having obtained the lock. If it is non-NULL
, thenacquired_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) orBT_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) orBT_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) orBT_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 thevalue
to the atomic integer variable or does a bitwise AND, OR or exclusive OR between the atomic variable andvalue
; 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) orBT_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; ifresult_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 descriptora
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; ifresult_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 descriptora
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; ifresult_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 descriptora
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; ifresult_image
has the value 0, the result shall be stored on all images, otherwise, only on the specified image. Theopr
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 descriptora
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.