8.2.5 _gfortran_caf_register
— Registering coarrays
- Description:
-
Allocates memory for a coarray and creates a token to identify the coarray. The function is called for both coarrays with
SAVE
attribute and using an explicitALLOCATE
statement. If an error occurs and STAT is aNULL
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 function shall return a pointer to the requested memory for the local image as a call tomalloc
would do.For
CAF_REGTYPE_COARRAY_STATIC
andCAF_REGTYPE_COARRAY_ALLOC
, the passed size is the byte size requested. ForCAF_REGTYPE_LOCK_STATIC
,CAF_REGTYPE_LOCK_ALLOC
andCAF_REGTYPE_CRITICAL
it is the array size or one for a scalar. - Syntax:
-
void *caf_register (size_t size, caf_register_t type, caf_token_t *token, int *stat, char *errmsg, int errmsg_len)
- Arguments:
-
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. 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. - NOTES
-
Nonalloatable 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 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.
For normal coarrays, the returned pointer is used for accesses on the local image. For lock types, the value shall only 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 always 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, respecitively, not in critical section) such as the value false; for event types, the initial state should be no event, e.g. zero.
© Free Software Foundation
Licensed under the GNU Free Documentation License, Version 1.3.
https://gcc.gnu.org/onlinedocs/gcc-5.4.0/gfortran/_005fgfortran_005fcaf_005fregister.html