gcc/fortran/doc/gfortran/type-and-enum-abi-documentation.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. _type-and-enum-abi-documentation:
   7
   8 Type and enum ABI Documentation
   9 *******************************
  10
  11 .. toctree::
  12   :maxdepth: 2
  13
  14
  15 .. _caf_token_t:
  16
  17 caf_token_t
  18 ^^^^^^^^^^^
  19
  20 Typedef of type ``void *`` on the compiler side. Can be any data
  21 type on the library side.
  22
  23 .. _caf_register_t:
  24
  25 caf_register_t
  26 ^^^^^^^^^^^^^^
  27
  28 Indicates which kind of coarray variable should be registered.
  29
  30 .. code-block:: c++
  31
  32   typedef enum caf_register_t {
  33     CAF_REGTYPE_COARRAY_STATIC,
  34     CAF_REGTYPE_COARRAY_ALLOC,
  35     CAF_REGTYPE_LOCK_STATIC,
  36     CAF_REGTYPE_LOCK_ALLOC,
  37     CAF_REGTYPE_CRITICAL,
  38     CAF_REGTYPE_EVENT_STATIC,
  39     CAF_REGTYPE_EVENT_ALLOC,
  40     CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY,
  41     CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY
  42   }
  43   caf_register_t;
  44
  45 The values ``CAF_REGTYPE_COARRAY_ALLOC_REGISTER_ONLY`` and
  46 ``CAF_REGTYPE_COARRAY_ALLOC_ALLOCATE_ONLY`` are for allocatable components
  47 in derived type coarrays only.  The first one sets up the token without
  48 allocating memory for allocatable component.  The latter one only allocates the
  49 memory for an allocatable component in a derived type coarray.  The token
  50 needs to be setup previously by the REGISTER_ONLY.  This allows to have
  51 allocatable components un-allocated on some images.  The status whether an
  52 allocatable component is allocated on a remote image can be queried by
  53 ``_caf_is_present`` which used internally by the ``ALLOCATED``
  54 intrinsic.
  55
  56 .. _caf_deregister_t:
  57
  58 caf_deregister_t
  59 ^^^^^^^^^^^^^^^^
  60
  61 .. code-block:: c++
  62
  63   typedef enum caf_deregister_t {
  64     CAF_DEREGTYPE_COARRAY_DEREGISTER,
  65     CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY
  66   }
  67   caf_deregister_t;
  68
  69 Allows to specifiy the type of deregistration of a coarray object.  The
  70 ``CAF_DEREGTYPE_COARRAY_DEALLOCATE_ONLY`` flag is only allowed for
  71 allocatable components in derived type coarrays.
  72
  73 .. _caf_reference_t:
  74
  75 caf_reference_t
  76 ^^^^^^^^^^^^^^^
  77
  78 The structure used for implementing arbitrary reference chains.
  79 A ``CAF_REFERENCE_T`` allows to specify a component reference or any kind
  80 of array reference of any rank supported by gfortran.  For array references all
  81 kinds as known by the compiler/Fortran standard are supported indicated by
  82 a ``MODE``.
  83
  84 .. code-block:: c++
  85
  86   typedef enum caf_ref_type_t {
  87     /* Reference a component of a derived type, either regular one or an
  88        allocatable or pointer type.  For regular ones idx in caf_reference_t is
  89        set to -1.  */
  90     CAF_REF_COMPONENT,
  91     /* Reference an allocatable array.  */
  92     CAF_REF_ARRAY,
  93     /* Reference a non-allocatable/non-pointer array.  I.e., the coarray object
  94        has no array descriptor associated and the addressing is done
  95        completely using the ref.  */
  96     CAF_REF_STATIC_ARRAY
  97   } caf_ref_type_t;
  98
  99 .. code-block:: c++
 100
 101   typedef enum caf_array_ref_t {
 102     /* No array ref.  This terminates the array ref.  */
 103     CAF_ARR_REF_NONE = 0,
 104     /* Reference array elements given by a vector.  Only for this mode
 105        caf_reference_t.u.a.dim[i].v is valid.  */
 106     CAF_ARR_REF_VECTOR,
 107     /* A full array ref (:).  */
 108     CAF_ARR_REF_FULL,
 109     /* Reference a range on elements given by start, end and stride.  */
 110     CAF_ARR_REF_RANGE,
 111     /* Only a single item is referenced given in the start member.  */
 112     CAF_ARR_REF_SINGLE,
 113     /* An array ref of the kind (i:), where i is an arbitrary valid index in the
 114        array.  The index i is given in the start member.  */
 115     CAF_ARR_REF_OPEN_END,
 116     /* An array ref of the kind (:i), where the lower bound of the array ref
 117        is given by the remote side.  The index i is given in the end member.  */
 118     CAF_ARR_REF_OPEN_START
 119   } caf_array_ref_t;
 120
 121 .. code-block:: c++
 122
 123   /* References to remote components of a derived type.  */
 124   typedef struct caf_reference_t {
 125     /* A pointer to the next ref or NULL.  */
 126     struct caf_reference_t *next;
 127     /* The type of the reference.  */
 128     /* caf_ref_type_t, replaced by int to allow specification in fortran FE.  */
 129     int type;
 130     /* The size of an item referenced in bytes.  I.e. in an array ref this is
 131        the factor to advance the array pointer with to get to the next item.
 132        For component refs this gives just the size of the element referenced.  */
 133     size_t item_size;
 134     union {
 135       struct {
 136         /* The offset (in bytes) of the component in the derived type.
 137            Unused for allocatable or pointer components.  */
 138         ptrdiff_t offset;
 139         /* The offset (in bytes) to the caf_token associated with this
 140            component.  NULL, when not allocatable/pointer ref.  */
 141         ptrdiff_t caf_token_offset;
 142       } c;
 143       struct {
 144         /* The mode of the array ref.  See CAF_ARR_REF_*.  */
 145         /* caf_array_ref_t, replaced by unsigend char to allow specification in
 146            fortran FE.  */
 147        unsigned char mode[GFC_MAX_DIMENSIONS];
 148         /* The type of a static array.  Unset for array's with descriptors.  */
 149         int static_array_type;
 150         /* Subscript refs (s) or vector refs (v).  */
 151         union {
 152           struct {
 153             /* The start and end boundary of the ref and the stride.  */
 154             index_type start, end, stride;
 155           } s;
 156           struct {
 157             /* nvec entries of kind giving the elements to reference.  */
 158             void *vector;
 159             /* The number of entries in vector.  */
 160             size_t nvec;
 161             /* The integer kind used for the elements in vector.  */
 162             int kind;
 163           } v;
 164         } dim[GFC_MAX_DIMENSIONS];
 165       } a;
 166     } u;
 167   } caf_reference_t;
 168
 169 The references make up a single linked list of reference operations.  The
 170 ``NEXT`` member links to the next reference or NULL to indicate the end of
 171 the chain.  Component and array refs can be arbitrarily mixed as long as they
 172 comply to the Fortran standard.
 173
 174 .. note::
 175   The member ``STATIC_ARRAY_TYPE`` is used only when the ``TYPE`` is
 176   ``CAF_REF_STATIC_ARRAY``.  The member gives the type of the data referenced.
 177   Because no array descriptor is available for a descriptor-less array and
 178   type conversion still needs to take place the type is transported here.
 179
 180   At the moment ``CAF_ARR_REF_VECTOR`` is not implemented in the front end for
 181   descriptor-less arrays.  The library caf_single has untested support for it.
 182
 183 .. _caf_team_t:
 184
 185 caf_team_t
 186 ^^^^^^^^^^
 187
 188 Opaque pointer to represent a team-handle.  This type is a stand-in for the
 189 future implementation of teams.  It is about to change without further notice.