|
| 1 | +//===--- AvailabilityContext.h - Swift Availability Structures --*- C++ -*-===// |
| 2 | +// |
| 3 | +// This source file is part of the Swift.org open source project |
| 4 | +// |
| 5 | +// Copyright (c) 2024 Apple Inc. and the Swift project authors |
| 6 | +// Licensed under Apache License v2.0 with Runtime Library Exception |
| 7 | +// |
| 8 | +// See https://swift.org/LICENSE.txt for license information |
| 9 | +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors |
| 10 | +// |
| 11 | +//===----------------------------------------------------------------------===// |
| 12 | +// |
| 13 | +// This file defines the AvailabilityContext data structure, which summarizes |
| 14 | +// availability constraints for a specific scope. |
| 15 | +// |
| 16 | +//===----------------------------------------------------------------------===// |
| 17 | + |
| 18 | +#ifndef SWIFT_AST_AVAILABILITY_CONTEXT_H |
| 19 | +#define SWIFT_AST_AVAILABILITY_CONTEXT_H |
| 20 | + |
| 21 | +#include "swift/AST/Availability.h" |
| 22 | +#include "swift/AST/PlatformKind.h" |
| 23 | +#include "swift/Basic/LLVM.h" |
| 24 | +#include "llvm/ADT/FoldingSet.h" |
| 25 | +#include <optional> |
| 26 | + |
| 27 | +namespace swift { |
| 28 | +class ASTContext; |
| 29 | +class AvailableAttr; |
| 30 | +class Decl; |
| 31 | + |
| 32 | +/// An `AvailabilityContext` summarizes the availability constraints for a |
| 33 | +/// specific scope, such as within a declaration or at a particular source |
| 34 | +/// location in a function body. This context is sufficient to determine whether |
| 35 | +/// a declaration is available or not in that scope. |
| 36 | +class AvailabilityContext : public llvm::FoldingSetNode { |
| 37 | + /// Summarizes platform specific availability constraints. |
| 38 | + struct PlatformInfo { |
| 39 | + /// The introduction version. |
| 40 | + AvailabilityRange Range; |
| 41 | + |
| 42 | + /// When `IsUnavailable` is true, this value stores the broadest platform |
| 43 | + /// kind for which the context is unavailable. |
| 44 | + PlatformKind UnavailablePlatform; |
| 45 | + |
| 46 | + /// Whether or not the context is considered unavailable on the current |
| 47 | + /// platform. |
| 48 | + unsigned IsUnavailable : 1; |
| 49 | + |
| 50 | + /// Whether or not the context is considered deprecated on the current |
| 51 | + /// platform. |
| 52 | + unsigned IsDeprecated : 1; |
| 53 | + |
| 54 | + /// Sets `Range` to `other` if `other` is more restrictive. Returns true if |
| 55 | + /// any property changed as a result of adding this constraint. |
| 56 | + bool constrainRange(const AvailabilityRange &other) { |
| 57 | + if (!other.isContainedIn(Range)) |
| 58 | + return false; |
| 59 | + |
| 60 | + Range = other; |
| 61 | + return true; |
| 62 | + } |
| 63 | + |
| 64 | + /// Sets `Range` to the platform introduction range of `decl` if that range |
| 65 | + /// is more restrictive. Returns true if |
| 66 | + /// any property changed as a result of adding this constraint. |
| 67 | + bool constrainRange(const Decl *decl); |
| 68 | + |
| 69 | + /// Updates `UnavailablePlatform` and `IsUnavailable` to reflect the status |
| 70 | + /// of `decl` if its platform unavailability is more restrictive. Returns |
| 71 | + /// true if any property changed as a result of adding this constraint. |
| 72 | + bool constrainUnavailability(const Decl *decl); |
| 73 | + |
| 74 | + /// If `decl` is deprecated, sets `IsDeprecated` to true. Returns true if |
| 75 | + /// any property changed as a result of adding this constraint. |
| 76 | + bool constrainDeprecated(const Decl *decl); |
| 77 | + |
| 78 | + /// Returns true if `other` is as available or is more available. |
| 79 | + bool isContainedIn(const PlatformInfo &other) const; |
| 80 | + |
| 81 | + void Profile(llvm::FoldingSetNodeID &ID) const { |
| 82 | + Range.getRawVersionRange().Profile(ID); |
| 83 | + ID.AddBoolean(IsUnavailable); |
| 84 | + ID.AddInteger(static_cast<uint8_t>(UnavailablePlatform)); |
| 85 | + ID.AddBoolean(IsDeprecated); |
| 86 | + } |
| 87 | + }; |
| 88 | + PlatformInfo PlatformAvailability; |
| 89 | + |
| 90 | + AvailabilityContext(const PlatformInfo &platformInfo) |
| 91 | + : PlatformAvailability(platformInfo){}; |
| 92 | + |
| 93 | + static const AvailabilityContext *get(const PlatformInfo &platformInfo, |
| 94 | + ASTContext &ctx); |
| 95 | + |
| 96 | +public: |
| 97 | + /// Retrieves the default `AvailabilityContext`, which is maximally available. |
| 98 | + /// The platform availability range will be set to the deployment target (or |
| 99 | + /// minimum inlining target when applicable). |
| 100 | + static const AvailabilityContext *getDefault(ASTContext &ctx); |
| 101 | + |
| 102 | + /// Retrieves a uniqued `AvailabilityContext` with the given platform |
| 103 | + /// availability parameters. |
| 104 | + static const AvailabilityContext * |
| 105 | + get(const AvailabilityRange &platformAvailability, |
| 106 | + std::optional<PlatformKind> unavailablePlatform, bool deprecated, |
| 107 | + ASTContext &ctx) { |
| 108 | + PlatformInfo platformInfo{platformAvailability, |
| 109 | + unavailablePlatform.has_value() |
| 110 | + ? *unavailablePlatform |
| 111 | + : PlatformKind::none, |
| 112 | + unavailablePlatform.has_value(), deprecated}; |
| 113 | + return get(platformInfo, ctx); |
| 114 | + } |
| 115 | + |
| 116 | + /// Returns the range of platform versions which may execute code in the |
| 117 | + /// availability context, starting at its introduction version. |
| 118 | + AvailabilityRange getPlatformRange() const { |
| 119 | + return PlatformAvailability.Range; |
| 120 | + } |
| 121 | + |
| 122 | + /// When the context is unavailable on the current platform this returns the |
| 123 | + /// broadest `PlatformKind` for which the context is unavailable. Otherwise, |
| 124 | + /// returns `nullopt`. |
| 125 | + std::optional<PlatformKind> getUnavailablePlatformKind() const { |
| 126 | + if (PlatformAvailability.IsUnavailable) |
| 127 | + return PlatformAvailability.UnavailablePlatform; |
| 128 | + return std::nullopt; |
| 129 | + } |
| 130 | + |
| 131 | + /// Returns true if this context is deprecated on the current platform. |
| 132 | + bool isDeprecated() const { return PlatformAvailability.IsDeprecated; } |
| 133 | + |
| 134 | + /// Returns the unique context that is the result of constraining the current |
| 135 | + /// context's platform availability range with `platformRange`. |
| 136 | + const AvailabilityContext * |
| 137 | + constrainWithPlatformRange(const AvailabilityRange &platformRange, |
| 138 | + ASTContext &ctx) const; |
| 139 | + |
| 140 | + /// Returns the unique context that is the result of constraining the current |
| 141 | + /// context both with the availability attributes of `decl` and with |
| 142 | + /// `platformRange`. |
| 143 | + const AvailabilityContext *constrainWithDeclAndPlatformRange( |
| 144 | + Decl *decl, const AvailabilityRange &platformRange) const; |
| 145 | + |
| 146 | + /// Returns true if `other` is as available or is more available. |
| 147 | + bool isContainedIn(const AvailabilityContext *other) const; |
| 148 | + |
| 149 | + void print(llvm::raw_ostream &os) const; |
| 150 | + SWIFT_DEBUG_DUMP; |
| 151 | + |
| 152 | + void Profile(llvm::FoldingSetNodeID &ID) const; |
| 153 | +}; |
| 154 | + |
| 155 | +} // end namespace swift |
| 156 | + |
| 157 | +#endif |
0 commit comments