_gfortran_caf_register (The GNU Fortran Compiler)

#### 7.2.8 `_gfortran_caf_register` — Registering coarrays ¶

Synopsis:

  `void _gfortran_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)`

Description:

  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.

  For `CAF_REGTYPE_COARRAY_STATIC` and `CAF_REGTYPE_COARRAY_ALLOC`, the passed size is the byte size requested. For `CAF_REGTYPE_LOCK_STATIC`, `CAF_REGTYPE_LOCK_ALLOC` and `CAF_REGTYPE_CRITICAL` it is the array size or one for a scalar.

  When `CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY` is used, then only a token for an allocatable or pointer component is created. The `SIZE` parameter is not used then. On the contrary when `CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY` is specified, then the token needs to be registered by a previous call with regtype `CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY` and either the memory specified in the DESC’s data-ptr is registered or allocate when the data-ptr is `NULL`.

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.
  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 is set to an error message; may be `NULL`
  errmsg_len | the buffer size of errmsg.

Notes:

  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 nonzero.

  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.