]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
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 | |
3ed1b4ce | 189 | future implementation of teams. It is about to change without further notice. |