FLANG

allocatable.h
1 //===-- runtime/allocatable.h -----------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8
9 // Defines APIs for Fortran runtime library support of code generated
10 // to manipulate and query allocatable variables, dummy arguments, & components.
11 #ifndef FORTRAN_RUNTIME_ALLOCATABLE_H_
12 #define FORTRAN_RUNTIME_ALLOCATABLE_H_
13 #include "descriptor.h"
14 #include "entry-names.h"
15
16 namespace Fortran::runtime {
17 extern "C" {
18
19 // Initializes the descriptor for an allocatable of intrinsic or derived type.
20 // The incoming descriptor is treated as (and can be) uninitialized garbage.
21 // Must be called for each allocatable variable as its scope comes into being.
22 // The storage for the allocatable's descriptor must have already been
23 // allocated to a size sufficient for the rank, corank, and type.
24 // A descriptor must be initialized before being used for any purpose,
25 // but needs reinitialization in a deallocated state only when there is
26 // a change of type, rank, or corank.
27 void RTNAME(AllocatableInitIntrinsic)(
28 Descriptor &, TypeCategory, int kind, int rank = 0, int corank = 0);
29 void RTNAME(AllocatableInitCharacter)(Descriptor &, SubscriptValue length = 0,
30 int kind = 1, int rank = 0, int corank = 0);
31 void RTNAME(AllocatableInitDerived)(
32 Descriptor &, const DerivedType &, int rank = 0, int corank = 0);
33
34 // Checks that an allocatable is not already allocated in statements
35 // with STAT=. Use this on a value descriptor before setting bounds or
36 // type parameters. Not necessary on a freshly initialized descriptor.
37 // (If there's no STAT=, the error will be caught later anyway, but
38 // this API allows the error to be caught before descriptor is modified.)
39 // Return 0 on success (deallocated state), else the STAT= value.
40 int RTNAME(AllocatableCheckAllocated)(Descriptor &,
41 Descriptor *errMsg = nullptr, const char *sourceFile = nullptr,
42 int sourceLine = 0);
43
44 // For MOLD= allocation; sets bounds, cobounds, and length type
45 // parameters from another descriptor. The destination descriptor must
46 // be initialized and deallocated.
47 void RTNAME(AllocatableApplyMold)(Descriptor &, const Descriptor &mold);
48
49 // Explicitly sets the bounds and length type parameters of an initialized
50 // deallocated allocatable.
51 void RTNAME(AllocatableSetBounds)(
52 Descriptor &, int zeroBasedDim, SubscriptValue lower, SubscriptValue upper);
53
54 // The upper bound is ignored for the last codimension.
55 void RTNAME(AllocatableSetCoBounds)(Descriptor &, int zeroBasedCoDim,
56 SubscriptValue lower, SubscriptValue upper = 0);
57
58 // Length type parameters are indexed in declaration order; i.e., 0 is the
59 // first length type parameter in the deepest base type. (Not for use
60 // with CHARACTER; see above.)
61 void RTNAME(AllocatableSetDerivedLength)(
62 Descriptor &, int which, SubscriptValue);
63
64 // When an explicit type-spec appears in an ALLOCATE statement for an
65 // allocatable with an explicit (non-deferred) length type paramater for
66 // a derived type or CHARACTER value, the explicit value has to match
67 // the length type parameter's value. This API checks that requirement.
68 // Returns 0 for success, or the STAT= value on failure with hasStat==true.
69 int RTNAME(AllocatableCheckLengthParameter)(Descriptor &,
70 int which /* 0 for CHARACTER length */, SubscriptValue other,
71 bool hasStat = false, Descriptor *errMsg = nullptr,
72 const char *sourceFile = nullptr, int sourceLine = 0);
73
74 // Allocates an allocatable. The allocatable descriptor must have been
75 // initialized and its bounds and length type parameters set and must be
76 // in a deallocated state.
77 // On failure, if hasStat is true, returns a nonzero error code for
78 // STAT= and (if present) fills in errMsg; if hasStat is false, the
79 // image is terminated. On success, leaves errMsg alone and returns zero.
80 // Successfully allocated memory is initialized if the allocatable has a
81 // derived type, and is always initialized by AllocatableAllocateSource().
82 // Performs all necessary coarray synchronization and validation actions.
83 int RTNAME(AllocatableAllocate)(Descriptor &, bool hasStat = false,
84 Descriptor *errMsg = nullptr, const char *sourceFile = nullptr,
85 int sourceLine = 0);
86 int RTNAME(AllocatableAllocateSource)(Descriptor &, const Descriptor &source,
87 bool hasStat = false, Descriptor *errMsg = nullptr,
88 const char *sourceFile = nullptr, int sourceLine = 0);
89
90 // Assigns to a whole allocatable, with automatic (re)allocation when the
91 // destination is unallocated or nonconforming (Fortran 2003 semantics).
92 // The descriptor must be initialized.
93 // Recursively assigns components with (re)allocation as necessary.
94 // TODO: Consider renaming to a more general name that will work for
95 // assignments to pointers, dummy arguments, and anything else with a
96 // descriptor.
97 void RTNAME(AllocatableAssign)(Descriptor &to, const Descriptor &from);
98
99 // Implements the intrinsic subroutine MOVE_ALLOC (16.9.137 in F'2018,
100 // but note the order of first two arguments is reversed for consistency
101 // with the other APIs for allocatables.) The destination descriptor
102 // must be initialized.
103 int RTNAME(MoveAlloc)(Descriptor &to, const Descriptor &from,
104 bool hasStat = false, Descriptor *errMsg = nullptr,
105 const char *sourceFile = nullptr, int sourceLine = 0);
106
107 // Deallocates an allocatable. Finalizes elements &/or components as needed.
108 // The allocatable is left in an initialized state suitable for reallocation
109 // with the same bounds, cobounds, and length type parameters.
110 int RTNAME(AllocatableDeallocate)(Descriptor &, bool hasStat = false,
111 Descriptor *errMsg = nullptr, const char *sourceFile = nullptr,
112 int sourceLine = 0);
113 }
114 } // namespace Fortran::runtime
115 #endif // FORTRAN_RUNTIME_ALLOCATABLE_H_