Base

This section contains a selection of the definitions declared in the chpl namespace. The entries may not be exhaustive.

using chpl::ChplEnvMap = std::unordered_map<std::string, std::string>

class chpl::CommentID

This class represents a unique ID for a comment It is separate from ID because it does not participate in the query system

Public Functions

CommentID() = default

inline CommentID(int index)

inline int index() const

Return the index of the comment id

class chpl::Context

This Context class stores the compilation-wide context. Another name for this compilation-wide context is program database. It handles unique’d strings and also stores the results of queries (so that they are are memoized). It tracks dependencies of queries in order to update them appropriately when a dependency changes.

Please see Query Framework for more information about how to implement queries and how the query framework functions.

Public Types

enum QueryStatus

Values:

enumerator NOT_CHECKED_NOT_CHANGED

enumerator REUSED

enumerator CHANGED

using ReportErrorFnType = void (*)(Context*, const ErrorMessage&)

Public Functions

Context(std::string chplHome = "", std::unordered_map<std::string, std::string> chplEnvOverrides = {})

Create a new AST Context. Optionally, specify the value of the CHPL_HOME environment variable, which is used for determining chapel environment varaibles.

~Context()

const std::string &chplHome() const

llvm::ErrorOr<const ChplEnvMap&> getChplEnv()

Run printchplenv, or return a cached result of doing so. To get output, CHPL_HOME must have been provided via the constructor; otherwise, the resulting map will be empty.

inline void setErrorHandler(ReportErrorFnType reportError)

Set the error handling function

inline ReportErrorFnType errorHandler() const

const char *uniqueCString(const char *s, size_t len)

Get or create a unique string and return it as a C string. If the passed string is NULL, this function will return an empty string.

Unique strings are limited to 2**31 bytes.

The returned string will store len bytes, even if there are interior NULL bytes. It will be NULL terminated either way.

Strings returned by this function will always be aligned to 2 bytes.

The function UniqueString::get returns such a string with a wrapper type. It should be preferred for type safety and to reduce redundant checks.

const char *uniqueCString(const char *s)

Calls uniqueCString with len=strlen(s). This simpler call can be used for C strings that don’t contain zero bytes other than the terminator.

const char *uniqueCStringConcatLen(const char *s1, size_t len1, const char *s2, size_t len2, const char *s3 = nullptr, size_t len3 = 0, const char *s4 = nullptr, size_t len4 = 0, const char *s5 = nullptr, size_t len5 = 0, const char *s6 = nullptr, size_t len6 = 0, const char *s7 = nullptr, size_t len7 = 0, const char *s8 = nullptr, size_t len8 = 0, const char *s9 = nullptr, size_t len9 = 0)

Get or create a unique string by concatenating up to 9 strings with lengths.

const char *uniqueCStringConcat(const char *s1, const char *s2, const char *s3 = nullptr, const char *s4 = nullptr, const char *s5 = nullptr, const char *s6 = nullptr, const char *s7 = nullptr, const char *s8 = nullptr, const char *s9 = nullptr)

Get or create a unique string by concatenating up to 9 strings.

void markUniqueCString(const char *s)

When the context is configured to run with garbage collection enabled, unique strings that are reused need to be marked. This function does that for a C string stored in the map. It will cause program crashes if called on a string that is not the result of one of the uniqueCString calls.

template<typename T>
inline void markUnownedPointer(const T *ptr)

This function can be called by a mark method to perform checking on pointers and any UniqueStrings that they contain when asserts are enabled.

Pointers available to a mark method should have already been returned by previous queries as owned objects and so markOwnedPointer should have been called on them if they have been reused.

template<typename T>
inline void markOwnedPointer(const T *ptr)

This function can be called by a mark method to mark UniqueStrings within an owned pointer.

template<typename T>
inline void markPointer(const owned<T> &ptr)

markPointer can be used to mark a pointer, where it is considered owned if the type is owned.

This overload just calls markOwnedPointer.

template<typename T>
inline void markPointer(const T *ptr)

markPointer can be used to mark a pointer, where it is considered owned if the type is owned.

This overload just calls markPointer.

bool filePathForId(ID id, UniqueString &pathOut, UniqueString &parentSymbolPathOut)

Return ‘true’ if the filePathForId was found (which can only happen because setFilePathForModuleID was already called for this ID).

Returns the path by setting ‘pathOut’. Returns the parent symbol path (relevant for ‘module include’ by setting ‘parentSymbolPathOut’.

void setFilePathForModuleId(ID moduleID, UniqueString path)

Sets the file path for the given module ID. This is suitable to call from a parse query.

void advanceToNextRevision(bool prepareToGC)

This function increments the current revision number stored in the context. After it is called, the setters below can be used to provide the input at that revision.

If the prepareToGC argument is true, when processing queries in that revision, will prepare to garbage collect UniqueStrings (by marking elements appropriately).

inline int numQueriesRunThisRevision() const

Returns the number of query bodies executed in this revision.

void collectGarbage()

This function runs garbage collection. It will collect UniqueStrings if the last call to advanceToNextRevision passed prepareToGC=true.

It is an implementation error to call this function while a query is running.

void report(ErrorMessage error)

Note an error for the currently running query and report it with the error handler set by setErrorHandler.

If no query is currently running, it just reports the error.

void error(Location loc, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in a Location and a printf-style format string.

void error(ID id, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in an ID and a printf-style format string. The ID is used to compute a Location using parsing::locateId.

void error(const uast::AstNode *ast, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in an AST node and a printf-style format string. The AST node is used to compute a Location by using a parsing::locateAst.

void error(const resolution::TypedFnSignature *inFn, const uast::AstNode *ast, const char *fmt, ...)

Note an error for the currently running query. This is a convenience overload. This version takes in a TypedFnSignature and an AST node and a printf-style format string. The AST node is used to compute a Location by using a parsing::locateAst. The TypedFnSignature is used to print out instantiation information.

void setDebugTraceFlag(const bool enable)

Sets the enableDebugTrace flag. This was needed because the context in main gets created before the arguments to the compiler are parsed.

void setBreakOnHash(const size_t hashVal)

inline void setQueryTimingFlag(bool enable)

Enables/disables timing each query execution

void beginQueryTimingTrace(const std::string &outname)

Begin query timing trace, sending the trace to outname

void endQueryTimingTrace()

End query timing trace, closes out stream

template<typename ResultType, typename ...ArgTs>
QueryStatus queryStatus(const ResultType &(*queryFunction)(Context *context, ArgTs...), const std::tuple<ArgTs...> &tupleOfArgs)

Returns: 0 if the query was not checked or changed in this revision 1 if the query was checked but not changed in this revision 2 if the query was changed in this revision

This is intended only as a debugging aid.

template<typename ResultType, typename ...ArgTs>
bool hasCurrentResultForQuery(const ResultType &(*queryFunction)(Context *context, ArgTs...), const std::tuple<ArgTs...> &tupleOfArgs)

Returns ‘true’ if the system already has a result for the passed query in the current revision. This can be useful for certain input queries - e.g. one reading a file that can both have the contents set and can also read the data from the filesystem.

template<typename ResultType, typename ...ArgTs>
bool isQueryRunning(const ResultType &(*queryFunction)(Context *context, ArgTs...), const std::tuple<ArgTs...> &tupleOfArgs)

Returns ‘true’ if the query in question is currently running. This can be useful for avoiding recursion in certain cases.

Public Static Functions

static inline ReportErrorFnType defaultErrorHandler()

static size_t lengthForUniqueString(const char *s)

For a unique string, return the length of the string when it was created. It will cause program crashes if called on a string that is not the result of one of the uniqueCString calls.

class chpl::ErrorMessage

This class represents an error/warning message. The message is saved (in the event it needs to be reported again).

Public Types

enum Kind

Values:

enumerator NOTE

enumerator WARNING

enumerator SYNTAX

enumerator ERROR

Public Functions

ErrorMessage()

ErrorMessage(Kind kind, Location location, std::string message)

ErrorMessage(Kind kind, Location location, const char *message)

ErrorMessage(Kind kind, ID id, std::string message)

ErrorMessage(Kind kind, ID id, const char *message)

void addDetail(ErrorMessage err)

Add an ErrorMessage as detail information to this ErrorMessage.

inline bool isEmpty() const

Returns true is this error message has no message and no details. Even if the error is empty, it may still be meaningful in the case of e.g., a syntax error (where the location offers useful info).

inline bool isDefaultConstructed() const

Returns true if this error message was default constructed, in which case its contents are not meaningful.

Location location(Context *context) const

Return the location in the source code where this error occurred.

inline const std::string &message() const

inline const std::vector<ErrorMessage> &details() const

inline Kind kind() const

inline ID id() const

inline bool operator==(const ErrorMessage &other) const

inline bool operator!=(const ErrorMessage &other) const

void swap(ErrorMessage &other)

void mark(Context *context) const

Public Static Functions

static ErrorMessage vbuild(Kind kind, ID id, const char *fmt, va_list vl)

Build an ErrorMessage within another varargs function

static ErrorMessage vbuild(Kind kind, Location location, const char *fmt, va_list vl)

Build an ErrorMessage within another varargs function

static ErrorMessage note(ID id, const char *fmt, ...)

Build a note ErrorMessage from an ID and a printf-style format

static ErrorMessage note(const uast::AstNode *ast, const char *fmt, ...)

Build a note ErrorMessage from an AstNode* and a printf-style format

static ErrorMessage note(Location loc, const char *fmt, ...)

Build a note ErrorMessage from a Location and a printf-style format

static ErrorMessage warning(ID id, const char *fmt, ...)

Build a warning ErrorMessage from an ID and a printf-style format

static ErrorMessage warning(const uast::AstNode*, const char *fmt, ...)

Build a warning ErrorMessage from an AstNode* and a printf-style format

static ErrorMessage warning(Location loc, const char *fmt, ...)

Build a warning ErrorMessage from a Location and a printf-style format

static ErrorMessage error(ID id, const char *fmt, ...)

Build an error ErrorMessage from an ID and a printf-style format

static ErrorMessage error(const uast::AstNode*, const char *fmt, ...)

Build an error ErrorMessage from an AstNode* and a printf-style format

static ErrorMessage error(Location loc, const char *fmt, ...)

Build an error ErrorMessage from a Location and a printf-style format

class chpl::ID

This class represents an ID for an AST node. AST element IDs can be helpful for creating maps with AST elements as keys. All AST nodes have IDs.

Public Functions

ID() = default

Construct an empty ID

inline ID(UniqueString symbolPath, int postOrderId, int numChildIds)

Construct an ID with a symbol path and postorder traversal number

inline UniqueString symbolPath() const

Return a path to the ID symbol scope. For example, a function ‘foo’ declared in a module M would have symbolPath M.foo.

Functions, class/record/union/enum declarations, and modules create new ID symbol scopes.

inline int postOrderId() const

Returns the numbering of this node in a postorder traversal of a symbol’s nodes. When the AST node defines a new ID symbol scope, (as with Function or Module) this will return -1.

inline int numContainedChildren() const

Return the number of ids contained in this node, not including itself. In the postorder traversal numbering, the ids contained appear before the node.

The node with postorder traversal ID postOrderId() - numChildIds() is the first node contained within this node.

E.g. in this notional AST: Node(LeafA LeafB)

LeafA has id 0 and numContainedIds 0 LeafB has id 1 and numContainedIds 0 Node has id 2 and numContainedIds 2

Note that the number of contained children does not include contained IDs with a different symbol scope. So, for example, a module consisting only of a function declaration would have numContainedChildren() == 0.

ID parentSymbolId(Context *context) const

Returns a new ID for the parent symbol ID.

if postOrderId is >= 0, returns the id with postOrderId == -1 if postOrderId is -1, returns the id from removing the last ‘.bla’ part from the symbolPath.

If this ID has no parent, returns an empty ID.

The returned ID always has numContainedChildren() of 0 and it cannot be used with contains(). However it is suitable for use in looking up an ID in a map.

UniqueString symbolName(Context *context) const

If the ID represents a symbol, return the name of that symbol. Otherwise, return the name of the symbol that contains the ID.

bool contains(const ID &other) const

returns ‘true’ if the AST node with this ID contains the AST node with the other ID, including if they refer to the same AST node.

int compare(const ID &other) const

compare this ID with another ID result < 0 if this < other result == 0 if this == other result > 0 if this > other

inline bool operator==(const ID &other) const

inline bool operator!=(const ID &other) const

inline bool operator<(const ID &other) const

inline bool operator<=(const ID &other) const

inline bool operator>(const ID &other) const

inline bool operator>=(const ID &other) const

inline bool isEmpty() const

inline size_t hash() const

inline void swap(ID &other)

inline void mark(Context *context) const

void stringify(std::ostream &ss, chpl::StringifyKind stringKind) const

std::string str() const

Public Static Functions

static UniqueString parentSymbolPath(Context *context, UniqueString symbolPath)

Given a symbol path, return the parent symbol path. Returns an empty string if the symbol path was empty string.

static UniqueString innermostSymbolName(Context *context, UniqueString symbolPath)

Given a symbol path, return the name of the innermost symbol

static std::vector<std::pair<UniqueString, int>> expandSymbolPath(Context *context, UniqueString symbolPath)

Given a symbol path, expand it into a vector of pairs, containing the path component and the repeat number.

static bool update(chpl::ID &keep, chpl::ID &addin)

class chpl::Location

This class represents a source location.

Public Functions

Location() = default

inline explicit Location(UniqueString path, int firstLine = -1, int firstColumn = -1, int lastLine = -1, int lastColumn = -1)

inline bool isEmpty() const

inline UniqueString path() const

inline int firstLine() const

inline int firstColumn() const

inline int lastLine() const

inline int lastColumn() const

inline int line() const

inline bool operator==(const Location &other) const

inline bool operator!=(const Location &other) const

inline void swap(Location &other)

inline void mark(Context *context) const

inline size_t hash() const

Public Static Functions

static bool update(Location &keep, Location &addin)

class chpl::UniqueString

This class represents a unique’d string. Unique’d strings allow: fast == and != not worrying about freeing them

Public Functions

inline UniqueString()

create a UniqueString storing the empty string

inline UniqueString(detail::PODUniqueString s)

create a UniqueString from a PODUniqueString. this constructor intentionally allows implicit conversion.

inline const char *c_str() const

Return the null-terminated string. The returned pointer may refer to invalid memory if the UniqueString goes out of scope.

inline size_t length() const

Return the length of the unique string.

inline const char *astr(Context *context) const

Return the null-terminated string as a pointer to an entry in Context’s string table. This pointer is safe to use after this UniqueString goes out of scope.

inline std::string str() const

return a std::string containing the string

void stringify(std::ostream &ss, chpl::StringifyKind stringKind) const

inline bool isEmpty() const

inline detail::PODUniqueString podUniqueString() const

inline bool startsWith(const char *prefix) const

Checks to see if the string starts with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool startsWith(const UniqueString prefix) const

Checks to see if the string starts with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool startsWith(const std::string &prefix) const

Checks to see if the string starts with another string.

Note

will not handle prefix strings with embedded '\0' bytes

inline bool operator==(const UniqueString other) const

inline bool operator==(const char *other) const

Checks to see if the string contents match a C string.

Note

will only compare up to the first null byte.

inline bool operator!=(const UniqueString other) const

inline bool operator!=(const char *other) const

inline int compare(const UniqueString other) const

Returns: -1 if this string is less than the passed string 0 if they are the same 1 if this string is greater

Note

will only compare up to the first null byte.

inline int compare(const char *other) const

inline size_t hash() const

inline void swap(UniqueString &other)

inline void mark(Context *context) const

Public Static Functions

static inline UniqueString get(Context *context, const char *s)

Get or create a unique string for a NULL-terminated C string. If NULL is provided, this function will return the UniqueString representing “”.

static inline UniqueString getConcat(Context *context, const char *s1, const char *s2, const char *s3 = nullptr, const char *s4 = nullptr, const char *s5 = nullptr, const char *s6 = nullptr, const char *s7 = nullptr, const char *s8 = nullptr, const char *s9 = nullptr)

Get or create a unique string by concatenating up to 9 input C strings. These input strings cannot contain null bytes other than the null terminator.

static UniqueString get(Context *context, const char *s, size_t len)

Get or create a unique string for a string from a pointer and a length. If the length is 0, this function will return the UniqueString representing “”. The length can be passed to truncate a string. The string can contain zero bytes.

static inline UniqueString get(Context *context, const std::string &s)

Get or create a unique string for a C++ string.

static bool update(UniqueString &keep, UniqueString &addin)

template<typename C>
class chpl::Iterable

Defines a read-only iterator over elements of a container type C

Public Functions

inline Iterable(const C &c)

inline C::const_iterator begin() const

inline C::const_iterator end() const

class chpl::Bitmap

Bitmap just stores a bunch of bits. It’s more or less like vector<bool> but we have a different type to make using it less confusing.

Public Functions

inline Bitmap()

Construct a Bitmap storing no bits

inline void resize(size_t n)

Resizes this Bitmap to store n bits

inline size_t size() const

Returns the number of bits stored in this Bitmap

inline bool operator[](size_t i) const

Returns the value of bit index i

inline void setBit(size_t i, bool value)

Set the value of bit index i

inline bool operator==(const Bitmap &other) const

inline bool operator!=(const Bitmap &other) const

inline void swap(Bitmap &other)

inline void mark(Context *context) const

size_t hash() const

void stringify(std::ostream &s, StringifyKind stringKind) const

Public Static Functions

static inline bool update(Bitmap &keep, Bitmap &addin)

template<typename T>
using chpl::owned = std::unique_ptr<T>

owned<T> is just a synonym for ‘std::unique_ptr<T>’. It is shorter and uses the Chapel term for it.

enum chpl::StringifyKind

Values:

enumerator DEBUG_SUMMARY

enumerator DEBUG_DETAIL

enumerator CHPL_SYNTAX