1 //===-- include/flang/Runtime/pointer.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 data pointers. 11 12 #ifndef FORTRAN_RUNTIME_POINTER_H_ 13 #define FORTRAN_RUNTIME_POINTER_H_ 14 15 #include "flang/Runtime/descriptor.h" 16 #include "flang/Runtime/entry-names.h" 17 18 namespace Fortran::runtime { 19 extern "C" { 20 21 // Data pointer initialization for NULLIFY(), "p=>NULL()`, & for ALLOCATE(). 22 23 // Initializes a pointer to a disassociated state for NULLIFY() or "p=>NULL()". 24 void RTNAME(PointerNullifyIntrinsic)( 25 Descriptor &, TypeCategory, int kind, int rank = 0, int corank = 0); 26 void RTNAME(PointerNullifyCharacter)(Descriptor &, SubscriptValue length = 0, 27 int kind = 1, int rank = 0, int corank = 0); 28 void RTNAME(PointerNullifyDerived)( 29 Descriptor &, const typeInfo::DerivedType &, int rank = 0, int corank = 0); 30 31 // Explicitly sets the bounds of an initialized disassociated pointer. 32 // The upper cobound is ignored for the last codimension. 33 void RTNAME(PointerSetBounds)( 34 Descriptor &, int zeroBasedDim, SubscriptValue lower, SubscriptValue upper); 35 void RTNAME(PointerSetCoBounds)(Descriptor &, int zeroBasedCoDim, 36 SubscriptValue lower, SubscriptValue upper = 0); 37 38 // Length type parameters are indexed in declaration order; i.e., 0 is the 39 // first length type parameter in the deepest base type. (Not for use 40 // with CHARACTER; see above.) 41 void RTNAME(PointerSetDerivedLength)(Descriptor &, int which, SubscriptValue); 42 43 // For MOLD= allocation: acquires information from another descriptor 44 // to initialize a null data pointer. 45 void RTNAME(PointerApplyMold)(Descriptor &, const Descriptor &mold); 46 47 // Data pointer association for "p=>TARGET" 48 49 // Associates a scalar pointer with a simple scalar target. 50 void RTNAME(PointerAssociateScalar)(Descriptor &, void *); 51 52 // Associates a pointer with a target of the same rank, possibly with new lower 53 // bounds, which are passed in a vector whose length must equal the rank. 54 void RTNAME(PointerAssociate)(Descriptor &, const Descriptor &target); 55 void RTNAME(PointerAssociateLowerBounds)( 56 Descriptor &, const Descriptor &target, const Descriptor &lowerBounds); 57 58 // Associates a pointer with a target with bounds remapping. The target must be 59 // simply contiguous &/or of rank 1. The bounds constitute a [2,newRank] 60 // integer array whose columns are [lower bound, upper bound] on each dimension. 61 void RTNAME(PointerAssociateRemapping)(Descriptor &, const Descriptor &target, 62 const Descriptor &bounds, const char *sourceFile = nullptr, 63 int sourceLine = 0); 64 65 // Data pointer allocation and deallocation 66 67 // When an explicit type-spec appears in an ALLOCATE statement for an 68 // pointer with an explicit (non-deferred) length type paramater for 69 // a derived type or CHARACTER value, the explicit value has to match 70 // the length type parameter's value. This API checks that requirement. 71 // Returns 0 for success, or the STAT= value on failure with hasStat==true. 72 int RTNAME(PointerCheckLengthParameter)(Descriptor &, 73 int which /* 0 for CHARACTER length */, SubscriptValue other, 74 bool hasStat = false, const Descriptor *errMsg = nullptr, 75 const char *sourceFile = nullptr, int sourceLine = 0); 76 77 // Allocates a data pointer. Its descriptor must have been initialized 78 // and its bounds and length type parameters set. It need not be disassociated. 79 // On failure, if hasStat is true, returns a nonzero error code for 80 // STAT= and (if present) fills in errMsg; if hasStat is false, the 81 // image is terminated. On success, leaves errMsg alone and returns zero. 82 // Successfully allocated memory is initialized if the pointer has a 83 // derived type, and is always initialized by PointerAllocateSource(). 84 // Performs all necessary coarray synchronization and validation actions. 85 int RTNAME(PointerAllocate)(Descriptor &, bool hasStat = false, 86 const Descriptor *errMsg = nullptr, const char *sourceFile = nullptr, 87 int sourceLine = 0); 88 int RTNAME(PointerAllocateSource)(Descriptor &, const Descriptor &source, 89 bool hasStat = false, const Descriptor *errMsg = nullptr, 90 const char *sourceFile = nullptr, int sourceLine = 0); 91 92 // Deallocates a data pointer, which must have been allocated by 93 // PointerAllocate(), possibly copied with PointerAssociate(). 94 // Finalizes elements &/or components as needed. The pointer is left 95 // in an initialized disassociated state suitable for reallocation 96 // with the same bounds, cobounds, and length type parameters. 97 int RTNAME(PointerDeallocate)(Descriptor &, bool hasStat = false, 98 const Descriptor *errMsg = nullptr, const char *sourceFile = nullptr, 99 int sourceLine = 0); 100 101 // Association inquiries for ASSOCIATED() 102 103 // True when the pointer is not disassociated. 104 bool RTNAME(PointerIsAssociated)(const Descriptor &); 105 106 // True when the pointer is associated with a specific target. 107 bool RTNAME(PointerIsAssociatedWith)( 108 const Descriptor &, const Descriptor *target); 109 110 } // extern "C" 111 } // namespace Fortran::runtime 112 #endif // FORTRAN_RUNTIME_POINTER_H_ 113