Merge pull request swiftlang#63357 from tshortli/se0376-rename-backdeploy

[SE-0376] Rename `@_backDeploy(before:)` to `@backDeployed(before:)`

Author: tshortli

CHANGELOG.md

@@ -4,6 +4,33 @@ _**Note:** This is in reverse chronological order, so newer entries are added to
 
 ## Swift 5.8
 
+* [SE-0376][]:
+
+  The `@backDeployed(before:)` attribute may now be used to extend the availability of a function to OS releases prior to the introduction of that function as ABI.
+  
+  For example, suppose that `struct Temperature` was introduced in a macOS SDK framework in macOS 12. Later in macOS 13 the framework authors decided to add a `degreesFahrenheit` property as a convenience:
+  
+  ```swift
+  @available(macOS 12, *)
+  public struct Temperature {
+    public var degreesCelsius: Double
+    
+    // ...
+  }
+  
+  extension Temperature {
+    @available(macOS 12, *)
+    @backDeployed(before: macOS 13)
+    public var degreesFahrenheit: Double {
+      return (degreesCelsius * 9 / 5) + 32
+    }
+  }
+  ```
+  
+  Adding the `@backDeployed` attribute to `degreesFahrenheit` enables the framework author to make this new declaration available to apps with a minimum deployment target of macOS 12, even though the ABI entry point for `degreesFahrenheit` is only present in macOS 13 and up.
+  
+  When a function with `@backDeployed` is called, the compiler wraps the invocation of the function in a thunk. The thunk checks whether the library entry point for the declaration is available at runtime, and invokes it if it is. Otherwise, a copy of the function that was emitted into the client is called instead.
+
 * [#56139][]:
 
   Сollection downcasts in cast patterns are now supported. For example:
@@ -9611,6 +9638,7 @@ using the `.dynamicType` member to retrieve the type of an expression should mig
 [SE-0362]: <https://github.com/apple/swift-evolution/blob/main/proposals/0362-piecemeal-future-features.md>
 [SE-0365]: <https://github.com/apple/swift-evolution/blob/main/proposals/0365-implicit-self-weak-capture.md>
 [SE-0370]: <https://github.com/apple/swift-evolution/blob/main/proposals/0370-pointer-family-initialization-improvements.md>
+[SE-0376]: <https://github.com/apple/swift-evolution/blob/main/proposals/0376-function-back-deployment.md>
 
 [#42697]: <https://github.com/apple/swift/issues/42697>
 [#42728]: <https://github.com/apple/swift/issues/42728>

docs/ReferenceGuides/UnderscoredAttributes.md

@@ -53,17 +53,7 @@ Adding this attribute to a type leads to remarks being emitted for all methods.
 
 ## `@_backDeploy(before: ...)`
 
-Causes the body of a function to be emitted into the module interface to be
-available for emission into clients with deployment targets lower than the
-ABI availability of the function. When the client's deployment target is
-before the function's ABI availability, the compiler replaces calls to that
-function with a call to a thunk that checks at runtime whether the original
-library function is available. If the original is available then it is
-called. Otherwise, the fallback copy of the function that was emitted into the
-client is called instead.
-
-For more details, see the [pitch thread](https://forums.swift.org/t/pitch-function-back-deployment/55769/)
-in the forums.
+The spelling of `@backDeployed(before:)` prior to the acceptance of [SE-0376](https://github.com/apple/swift-evolution/blob/main/proposals/0376-function-back-deployment.md).
 
 ## `@_borrowed`
 

include/swift/AST/Attr.h

@@ -2219,15 +2219,12 @@ class UnavailableFromAsyncAttr : public DeclAttribute {
 
 /// The @_backDeploy(...) attribute, used to make function declarations available
 /// for back deployment to older OSes via emission into the client binary.
-class BackDeployAttr: public DeclAttribute {
+class BackDeployedAttr : public DeclAttribute {
 public:
-  BackDeployAttr(SourceLoc AtLoc, SourceRange Range,
-                 PlatformKind Platform,
-                 const llvm::VersionTuple Version,
-                 bool Implicit)
-    : DeclAttribute(DAK_BackDeploy, AtLoc, Range, Implicit),
-      Platform(Platform),
-      Version(Version) {}
+  BackDeployedAttr(SourceLoc AtLoc, SourceRange Range, PlatformKind Platform,
+                   const llvm::VersionTuple Version, bool Implicit)
+      : DeclAttribute(DAK_BackDeployed, AtLoc, Range, Implicit),
+        Platform(Platform), Version(Version) {}
 
   /// The platform the symbol is available for back deployment on.
   const PlatformKind Platform;
@@ -2239,7 +2236,7 @@ class BackDeployAttr: public DeclAttribute {
   bool isActivePlatform(const ASTContext &ctx) const;
 
   static bool classof(const DeclAttribute *DA) {
-    return DA->getKind() == DAK_BackDeploy;
+    return DA->getKind() == DAK_BackDeployed;
   }
 };
 
@@ -2419,9 +2416,9 @@ class DeclAttributes {
   /// otherwise.
   const AvailableAttr *getNoAsync(const ASTContext &ctx) const;
 
-  /// Returns the \c @_backDeploy attribute that is active for the current
+  /// Returns the `@backDeployed` attribute that is active for the current
   /// platform.
-  const BackDeployAttr *getBackDeploy(const ASTContext &ctx) const;
+  const BackDeployedAttr *getBackDeployed(const ASTContext &ctx) const;
 
   SWIFT_DEBUG_DUMPER(dump(const Decl *D = nullptr));
   void print(ASTPrinter &Printer, const PrintOptions &Options,

include/swift/AST/Decl.h

@@ -884,9 +884,9 @@ class alignas(1 << DeclAlignInBits) Decl : public ASTAllocated<Decl> {
   Optional<llvm::VersionTuple> getIntroducedOSVersion(PlatformKind Kind) const;
 
   /// Returns the OS version in which the decl became ABI as specified by the
-  /// @_backDeploy attribute.
+  /// @backDeployed attribute.
   Optional<llvm::VersionTuple>
-  getBackDeployBeforeOSVersion(ASTContext &Ctx) const;
+  getBackDeployedBeforeOSVersion(ASTContext &Ctx) const;
 
   /// Returns the starting location of the entire declaration.
   SourceLoc getStartLoc() const { return getSourceRange().Start; }
@@ -6808,8 +6808,8 @@ class AbstractFunctionDecl : public GenericContext, public ValueDecl {
   /// \return the synthesized thunk, or null if the base of the call has
   ///         diagnosed errors during type checking.
   FuncDecl *getDistributedThunk() const;
-  
-  /// Returns 'true' if the function has (or inherits) the @c @_backDeploy
+
+  /// Returns 'true' if the function has (or inherits) the `@backDeployed`
   /// attribute.
   bool isBackDeployed() const;
 

include/swift/AST/DiagnosticsParse.def

@@ -1593,11 +1593,11 @@ ERROR(originally_defined_in_need_nonempty_module_name,none,
 
 // backDeploy
 ERROR(attr_back_deploy_expected_before_label,none,
-      "expected 'before:' in '@_backDeploy' attribute", ())
+      "expected 'before:' in '@backDeployed' attribute", ())
 ERROR(attr_back_deploy_expected_colon_after_before,none,
-      "expected ':' after 'before' in '@_backDeploy' attribute", ())
+      "expected ':' after 'before' in '@backDeployed' attribute", ())
 ERROR(attr_back_deploy_missing_rparen,none,
-      "expected ')' in '@_backDeploy' argument list", ())
+      "expected ')' in '@backDeployed' argument list", ())
 
 // convention
 ERROR(convention_attribute_expected_lparen,none,

include/swift/AST/DiagnosticsSema.def

@@ -6072,7 +6072,7 @@ ERROR(usable_from_inline_attr_in_protocol,none,
   "an '@_alwaysEmitIntoClient' function|" \
   "a default argument value|" \
   "a property initializer in a '@frozen' type|" \
-  "a '@_backDeploy' function'}"
+  "a '@backDeployed' function'}"
 
 #define DECL_OR_ACCESSOR "%select{%0|%0 for}"
 

include/swift/Parse/Parser.h

@@ -1098,9 +1098,10 @@ class Parser {
   ParserResult<TransposeAttr> parseTransposeAttribute(SourceLoc AtLoc,
                                                       SourceLoc Loc);
 
-  /// Parse the @_backDeploy attribute.
-  bool parseBackDeployAttribute(DeclAttributes &Attributes, StringRef AttrName,
-                                SourceLoc AtLoc, SourceLoc Loc);
+  /// Parse the @backDeployed attribute.
+  bool parseBackDeployedAttribute(DeclAttributes &Attributes,
+                                  StringRef AttrName, SourceLoc AtLoc,
+                                  SourceLoc Loc);
 
   /// Parse the @_documentation attribute.
   ParserResult<DocumentationAttr> parseDocumentationAttribute(SourceLoc AtLoc,

include/swift/SIL/SILDeclRef.h

@@ -390,7 +390,7 @@ struct SILDeclRef {
   bool isNoinline() const;
   /// True if the function has __always inline attribute.
   bool isAlwaysInline() const;
-  /// True if the function has the @_backDeploy attribute.
+  /// True if the function has the @backDeployed attribute.
   bool isBackDeployed() const;
 
   /// Return the expected linkage for a definition of this declaration.

lib/AST/Attr.cpp

@@ -400,23 +400,24 @@ const AvailableAttr *DeclAttributes::getNoAsync(const ASTContext &ctx) const {
   return bestAttr;
 }
 
-const BackDeployAttr *
-DeclAttributes::getBackDeploy(const ASTContext &ctx) const {
-  const BackDeployAttr *bestAttr = nullptr;
+const BackDeployedAttr *
+DeclAttributes::getBackDeployed(const ASTContext &ctx) const {
+  const BackDeployedAttr *bestAttr = nullptr;
 
   for (auto attr : *this) {
-    auto *backDeployAttr = dyn_cast<BackDeployAttr>(attr);
-    if (!backDeployAttr)
+    auto *backDeployedAttr = dyn_cast<BackDeployedAttr>(attr);
+    if (!backDeployedAttr)
       continue;
 
-    if (backDeployAttr->isInvalid() || !backDeployAttr->isActivePlatform(ctx))
+    if (backDeployedAttr->isInvalid() ||
+        !backDeployedAttr->isActivePlatform(ctx))
       continue;
 
     // We have an attribute that is active for the platform, but
     // is it more specific than our current best?
-    if (!bestAttr || inheritsAvailabilityFromPlatform(backDeployAttr->Platform,
-                                                      bestAttr->Platform)) {
-      bestAttr = backDeployAttr;
+    if (!bestAttr || inheritsAvailabilityFromPlatform(
+                         backDeployedAttr->Platform, bestAttr->Platform)) {
+      bestAttr = backDeployedAttr;
     }
   }
 
@@ -547,13 +548,14 @@ static void printShortFormBackDeployed(ArrayRef<const DeclAttribute *> Attrs,
                                        ASTPrinter &Printer,
                                        const PrintOptions &Options) {
   assert(!Attrs.empty());
+  // TODO: Print `@backDeployed` in swiftinterfaces (rdar://104920183)
   Printer << "@_backDeploy(before: ";
   bool isFirst = true;
 
   for (auto *DA : Attrs) {
     if (!isFirst)
       Printer << ", ";
-    auto *attr = cast<BackDeployAttr>(DA);
+    auto *attr = cast<BackDeployedAttr>(DA);
     Printer << platformString(attr->Platform) << " "
             << attr->Version.getAsString();
     isFirst = false;
@@ -773,7 +775,7 @@ void DeclAttributes::print(ASTPrinter &Printer, const PrintOptions &Options,
   AttributeVector shortAvailableAttributes;
   const DeclAttribute *swiftVersionAvailableAttribute = nullptr;
   const DeclAttribute *packageDescriptionVersionAvailableAttribute = nullptr;
-  AttributeVector backDeployAttributes;
+  AttributeVector backDeployedAttributes;
   AttributeVector longAttributes;
   AttributeVector attributes;
   AttributeVector modifiers;
@@ -811,7 +813,7 @@ void DeclAttributes::print(ASTPrinter &Printer, const PrintOptions &Options,
     }
 
     AttributeVector &which = DA->isDeclModifier() ? modifiers :
-                             isa<BackDeployAttr>(DA) ? backDeployAttributes :
+                             isa<BackDeployedAttr>(DA) ? backDeployedAttributes :
                              isShortAvailable(DA) ? shortAvailableAttributes :
                              DA->isLongAttribute() ? longAttributes :
                              attributes;
@@ -824,8 +826,8 @@ void DeclAttributes::print(ASTPrinter &Printer, const PrintOptions &Options,
     printShortFormAvailable(packageDescriptionVersionAvailableAttribute, Printer, Options);
   if (!shortAvailableAttributes.empty())
     printShortFormAvailable(shortAvailableAttributes, Printer, Options);
-  if (!backDeployAttributes.empty())
-    printShortFormBackDeployed(backDeployAttributes, Printer, Options);
+  if (!backDeployedAttributes.empty())
+    printShortFormBackDeployed(backDeployedAttributes, Printer, Options);
 
   for (auto DA : longAttributes)
     DA->print(Printer, Options, D);
@@ -1324,10 +1326,11 @@ bool DeclAttribute::printImpl(ASTPrinter &Printer, const PrintOptions &Options,
     break;
   }
 
-  case DAK_BackDeploy: {
+  case DAK_BackDeployed: {
+    // TODO: Print `@backDeployed` in swiftinterfaces (rdar://104920183)
     Printer.printAttrName("@_backDeploy");
     Printer << "(before: ";
-    auto Attr = cast<BackDeployAttr>(this);
+    auto Attr = cast<BackDeployedAttr>(this);
     Printer << platformString(Attr->Platform) << " " <<
       Attr->Version.getAsString();
     Printer << ")";
@@ -1534,8 +1537,8 @@ StringRef DeclAttribute::getAttrName() const {
     return "transpose";
   case DAK_UnavailableFromAsync:
     return "_unavailableFromAsync";
-  case DAK_BackDeploy:
-    return "_backDeploy";
+  case DAK_BackDeployed:
+    return "backDeployed";
   case DAK_Expose:
     return "_expose";
   case DAK_Documentation:
@@ -1791,7 +1794,7 @@ bool AvailableAttr::isActivePlatform(const ASTContext &ctx) const {
   return isPlatformActive(Platform, ctx.LangOpts);
 }
 
-bool BackDeployAttr::isActivePlatform(const ASTContext &ctx) const {
+bool BackDeployedAttr::isActivePlatform(const ASTContext &ctx) const {
   return isPlatformActive(Platform, ctx.LangOpts);
 }
 

lib/AST/Decl.cpp

@@ -417,13 +417,13 @@ Decl::getIntroducedOSVersion(PlatformKind Kind) const {
 }
 
 Optional<llvm::VersionTuple>
-Decl::getBackDeployBeforeOSVersion(ASTContext &Ctx) const {
-  if (auto *attr = getAttrs().getBackDeploy(Ctx))
+Decl::getBackDeployedBeforeOSVersion(ASTContext &Ctx) const {
+  if (auto *attr = getAttrs().getBackDeployed(Ctx))
     return attr->Version;
 
-  // Accessors may inherit `@_backDeploy`.
+  // Accessors may inherit `@backDeployed`.
   if (auto *AD = dyn_cast<AccessorDecl>(this))
-    return AD->getStorage()->getBackDeployBeforeOSVersion(Ctx);
+    return AD->getStorage()->getBackDeployedBeforeOSVersion(Ctx);
 
   return None;
 }
@@ -971,8 +971,8 @@ AvailabilityContext Decl::getAvailabilityForLinkage() const {
   ASTContext &ctx = getASTContext();
 
   // When computing availability for linkage, use the "before" version from
-  // the @_backDeploy attribute, if present.
-  if (auto backDeployVersion = getBackDeployBeforeOSVersion(ctx))
+  // the @backDeployed attribute, if present.
+  if (auto backDeployVersion = getBackDeployedBeforeOSVersion(ctx))
     return AvailabilityContext{VersionRange::allGTE(*backDeployVersion)};
 
   auto containingContext =
@@ -8065,12 +8065,12 @@ bool AbstractFunctionDecl::isSendable() const {
 }
 
 bool AbstractFunctionDecl::isBackDeployed() const {
-  if (getAttrs().hasAttribute<BackDeployAttr>())
+  if (getAttrs().hasAttribute<BackDeployedAttr>())
     return true;
 
   // Property and subscript accessors inherit the attribute.
   if (auto *AD = dyn_cast<AccessorDecl>(this)) {
-    if (AD->getStorage()->getAttrs().hasAttribute<BackDeployAttr>())
+    if (AD->getStorage()->getAttrs().hasAttribute<BackDeployedAttr>())
       return true;
   }