[AST] Add a new attribute @hasAsyncAlternative

This attribute marks a function has having an async alternative,
optionally providing the name of that function as a string. Intended to
be used to allow warnings when using a function with an async
alternative in an asynchronous context, to make the async refactorings
more accurate, and for documentation.

Author: bnbarham

include/swift/AST/Attr.def

@@ -624,6 +624,12 @@ SIMPLE_DECL_ATTR(reasync, AtReasync,
   ABIBreakingToAdd | ABIBreakingToRemove | APIBreakingToAdd | APIBreakingToRemove,
   110)
 
+DECL_ATTR(hasAsyncAlternative, HasAsyncAlternative,
+  OnAbstractFunction | ConcurrencyOnly |
+  ABIStableToAdd | ABIStableToRemove |
+  APIStableToAdd | APIStableToRemove,
+  111)
+
 #undef TYPE_ATTR
 #undef DECL_ATTR_ALIAS
 #undef CONTEXTUAL_DECL_ATTR_ALIAS

include/swift/AST/Attr.h

@@ -2140,6 +2140,30 @@ class TransposeAttr final
   }
 };
 
+/// The `@hasAsyncAlternative` attribute marks a function as having an async
+/// alternative, optionally providing a name (for cases when the alternative
+/// has a different name).
+class HasAsyncAlternativeAttr final : public DeclAttribute  {
+public:
+  /// An optional name of the async alternative function, where the name of the
+  /// attributed function is used otherwise.
+  const DeclNameRef Name;
+
+  HasAsyncAlternativeAttr(DeclNameRef Name, SourceLoc AtLoc, SourceRange Range)
+    : DeclAttribute(DAK_HasAsyncAlternative, AtLoc, Range, false),
+      Name(Name) {}
+
+  HasAsyncAlternativeAttr(SourceLoc AtLoc, SourceRange Range)
+    : DeclAttribute(DAK_HasAsyncAlternative, AtLoc, Range, false) {}
+
+  /// Determine whether this attribute has a name associated with it.
+  bool hasName() const { return !Name.getBaseName().empty(); }
+
+  static bool classof(const DeclAttribute *DA) {
+    return DA->getKind() == DAK_HasAsyncAlternative;
+  }
+};
+
 /// Attributes that may be applied to declarations.
 class DeclAttributes {
   /// Linked list of declaration attributes.

include/swift/AST/DiagnosticsParse.def

@@ -1672,6 +1672,15 @@ ERROR(sil_inst_autodiff_invalid_witness_generic_signature,PointsToFirstBadToken,
       "parameters as original function generic signature '%1'",
       (StringRef, StringRef))
 
+// hasAsyncAlternative
+ERROR(requires_has_async_alternative, none,
+      "'%0' support is required to be explicitly enabled using "
+      "-experimental-has-async-alternative-attribute", (StringRef))
+
+ERROR(has_async_alternative_invalid_name, none,
+      "argument of '%0' attribute must be an identifier or full function name",
+      (StringRef))
+
 //------------------------------------------------------------------------------
 // MARK: Generics parsing diagnostics
 //------------------------------------------------------------------------------

include/swift/Basic/LangOptions.h

@@ -387,6 +387,9 @@ namespace swift {
     ASTVerifierOverrideKind ASTVerifierOverride =
         ASTVerifierOverrideKind::NoOverride;
 
+    /// Allow @hasAsyncAlternative attribute
+    bool EnableExperimentalHasAsyncAlternative = false;
+
     /// Sets the target we are building for and updates platform conditions
     /// to match.
     ///

include/swift/Option/FrontendOptions.td

@@ -796,4 +796,9 @@ def disable_ast_verifier : Flag<["-"], "disable-ast-verifier">,
 def new_driver_path
   : Separate<["-"], "new-driver-path">, MetaVarName<"<path>">,
   HelpText<"Path of the new driver to be used">;
+
+def experimental_has_async_alternative_attribute:
+  Flag<["-"], "experimental-has-async-alternative-attribute">,
+  HelpText<"Allow use of @hasAsyncAlternative">;
+
 } // end let Flags = [FrontendOption, NoDriverOption, HelpHidden]

lib/AST/Attr.cpp

@@ -1223,6 +1223,8 @@ StringRef DeclAttribute::getAttrName() const {
     return "derivative";
   case DAK_Transpose:
     return "transpose";
+  case DAK_HasAsyncAlternative:
+    return "hasAsyncAlternative";
   }
   llvm_unreachable("bad DeclAttrKind");
 }

lib/Frontend/CompilerInvocation.cpp

@@ -715,6 +715,9 @@ static bool ParseLangArgs(LangOptions &Opts, ArgList &Args,
     }
   }
 
+  Opts.EnableExperimentalHasAsyncAlternative |=
+      Args.hasArg(OPT_experimental_has_async_alternative_attribute);
+
   return HadError || UnsupportedOS || UnsupportedArch;
 }
 

lib/Parse/ParseDecl.cpp

@@ -1570,6 +1570,44 @@ void Parser::parseAllAvailabilityMacroArguments() {
   AvailabilityMacrosComputed = true;
 }
 
+static HasAsyncAlternativeAttr *parseAsyncAlternativeAttribute(
+    Parser &P, StringRef AttrName, SourceLoc AtLoc, DeclAttrKind DK) {
+  SourceLoc Loc = P.PreviousLoc;
+
+  // Unnamed @hasAsyncAlternative attribute
+  if (P.Tok.isNot(tok::l_paren))
+    return new (P.Context) HasAsyncAlternativeAttr(AtLoc, Loc);
+
+  P.consumeToken(tok::l_paren);
+
+  if (!P.Tok.is(tok::string_literal)) {
+    P.diagnose(Loc, diag::attr_expected_string_literal, AttrName);
+    return nullptr;
+  }
+
+  auto Value = P.getStringLiteralIfNotInterpolated(
+      Loc, ("argument of '" + AttrName + "'").str());
+  P.consumeToken(tok::string_literal);
+  if (!Value)
+    return nullptr;
+
+  ParsedDeclName parsedName = parseDeclName(Value.getValue());
+  if (!parsedName || !parsedName.ContextName.empty()) {
+    P.diagnose(AtLoc, diag::has_async_alternative_invalid_name, AttrName);;
+    return nullptr;
+  }
+
+  SourceRange AttrRange = SourceRange(Loc, P.Tok.getRange().getStart());
+  if (!P.consumeIf(tok::r_paren)) {
+    P.diagnose(Loc, diag::attr_expected_rparen, AttrName,
+               DeclAttribute::isDeclModifier(DK));
+    return nullptr;
+  }
+
+  return new (P.Context) HasAsyncAlternativeAttr(
+      parsedName.formDeclNameRef(P.Context), AtLoc, AttrRange);
+}
+
 bool Parser::parseNewDeclAttribute(DeclAttributes &Attributes, SourceLoc AtLoc,
                                    DeclAttrKind DK, bool isFromClangAttribute) {
   // Ok, it is a valid attribute, eat it, and then process it.
@@ -2648,6 +2686,22 @@ bool Parser::parseNewDeclAttribute(DeclAttributes &Attributes, SourceLoc AtLoc,
         name, AtLoc, range, /*implicit*/ false));
     break;
   }
+  case DAK_HasAsyncAlternative: {
+    auto *attr = parseAsyncAlternativeAttribute(*this, AttrName, AtLoc, DK);
+    if (!attr) {
+      skipUntilDeclStmtRBrace(tok::r_paren);
+      consumeIf(tok::r_paren);
+      return false;
+    }
+
+    if (!DiscardAttribute) {
+      if (Context.LangOpts.EnableExperimentalHasAsyncAlternative)
+        Attributes.add(attr);
+      else
+        diagnose(Loc, diag::requires_has_async_alternative, AttrName);
+    }
+    break;
+  }
   }
 
   if (DuplicateAttribute) {

lib/Sema/TypeCheckAttr.cpp

@@ -105,6 +105,7 @@ class AttributeChecker : public AttributeVisitor<AttributeChecker> {
   IGNORED_ATTR(Effects)
   IGNORED_ATTR(Exported)
   IGNORED_ATTR(ForbidSerializingReference)
+  IGNORED_ATTR(HasAsyncAlternative)
   IGNORED_ATTR(HasStorage)
   IGNORED_ATTR(HasMissingDesignatedInitializers)
   IGNORED_ATTR(InheritsConvenienceInitializers)

lib/Sema/TypeCheckDeclOverride.cpp

@@ -1446,6 +1446,7 @@ namespace  {
     UNINTERESTING_ATTR(Exported)
     UNINTERESTING_ATTR(ForbidSerializingReference)
     UNINTERESTING_ATTR(GKInspectable)
+    UNINTERESTING_ATTR(HasAsyncAlternative)
     UNINTERESTING_ATTR(HasMissingDesignatedInitializers)
     UNINTERESTING_ATTR(IBAction)
     UNINTERESTING_ATTR(IBDesignable)

lib/Serialization/Deserialization.cpp

@@ -4529,6 +4529,27 @@ llvm::Error DeclDeserializer::deserializeDeclAttributes() {
         break;
       }
 
+      case decls_block::HasAsyncAlternative_DECL_ATTR: {
+        bool isCompound;
+        ArrayRef<uint64_t> rawPieces;
+        serialization::decls_block::HasAsyncAlternativeDeclAttrLayout::readRecord(
+            scratch, isCompound, rawPieces);
+
+        DeclNameRef name;
+        if (!rawPieces.empty()) {
+          auto baseName = MF.getDeclBaseName(rawPieces[0]);
+          SmallVector<Identifier, 4> pieces;
+          for (auto rawPiece : rawPieces.drop_front())
+            pieces.push_back(MF.getIdentifier(rawPiece));
+          name = !isCompound ? DeclNameRef({baseName})
+                             : DeclNameRef({ctx, baseName, pieces});
+        }
+
+        Attr = new (ctx) HasAsyncAlternativeAttr(name, SourceLoc(),
+                                                 SourceRange());
+        break;
+      }
+
 #define SIMPLE_DECL_ATTR(NAME, CLASS, ...) \
       case decls_block::CLASS##_DECL_ATTR: { \
         bool isImplicit; \

lib/Serialization/ModuleFormat.h

@@ -56,7 +56,7 @@ const uint16_t SWIFTMODULE_VERSION_MAJOR = 0;
 /// describe what change you made. The content of this comment isn't important;
 /// it just ensures a conflict if two people change the module format.
 /// Don't worry about adhering to the 80-column limit for this line.
-const uint16_t SWIFTMODULE_VERSION_MINOR = 598; // reasync
+const uint16_t SWIFTMODULE_VERSION_MINOR = 599; // has-async-alternative
 
 /// A standard hash seed used for all string hashes in a serialized module.
 ///
@@ -1913,6 +1913,12 @@ namespace decls_block {
     BCArray<BCFixed<1>> // Transposed parameter indices' bitvector.
   >;
 
+  using HasAsyncAlternativeDeclAttrLayout = BCRecordLayout<
+    HasAsyncAlternative_DECL_ATTR,
+    BCFixed<1>,                // True if compound name
+    BCArray<IdentifierIDField> // Name and parameters
+  >;
+
 #define SIMPLE_DECL_ATTR(X, CLASS, ...)         \
   using CLASS##DeclAttrLayout = BCRecordLayout< \
     CLASS##_DECL_ATTR, \

lib/Serialization/Serialization.cpp

@@ -2614,6 +2614,24 @@ class Serializer::DeclSerializer : public DeclVisitor<DeclSerializer> {
           origDeclID, paramIndicesVector);
       return;
     }
+
+    case DAK_HasAsyncAlternative: {
+      auto *attr = cast<HasAsyncAlternativeAttr>(DA);
+      auto abbrCode =
+          S.DeclTypeAbbrCodes[HasAsyncAlternativeDeclAttrLayout::Code];
+
+      SmallVector<IdentifierID, 4> pieces;
+      if (attr->hasName()) {
+        pieces.push_back(S.addDeclBaseNameRef(attr->Name.getBaseName()));
+        for (auto argName : attr->Name.getArgumentNames())
+          pieces.push_back(S.addDeclBaseNameRef(argName));
+      }
+
+      HasAsyncAlternativeDeclAttrLayout::emitRecord(
+          S.Out, S.ScratchRecord, abbrCode, attr->Name.isCompoundName(),
+          pieces);
+      return;
+    }
     }
   }
 

test/attr/attr_hasasyncalternative.swift

@@ -0,0 +1,56 @@
+// REQUIRES: concurrency
+
+// RUN: %target-typecheck-verify-swift -enable-experimental-concurrency -experimental-has-async-alternative-attribute
+
+@hasAsyncAlternative
+func func1() {}
+
+@hasAsyncAlternative("betterFunc")
+func func2() {}
+
+@hasAsyncAlternative("betterFunc(param:)")
+func func3() {}
+
+@hasAsyncAlternative("not+identifier") // expected-error {{argument of 'hasAsyncAlternative' attribute must be an identifier or full function name}}
+func func4() {}
+
+@hasAsyncAlternative("$dollarname") // expected-error {{argument of 'hasAsyncAlternative' attribute must be an identifier or full function name}}
+func func5() {}
+
+@hasAsyncAlternative("TypePrefix.func") // expected-error {{argument of 'hasAsyncAlternative' attribute must be an identifier or full function name}}
+func func6() {}
+
+@hasAsyncAlternative("interpreted \()") // expected-error {{argument of 'hasAsyncAlternative' cannot be an interpolated string literal}}
+func func7() {}
+
+@hasAsyncAlternative("missingRParen" // expected-error {{expected ')' in 'hasAsyncAlternative' attribute}}
+func func8() {}
+
+@hasAsyncAlternative // expected-note {{attribute already specified here}}
+@hasAsyncAlternative("other") // expected-error {{duplicate attribute}}
+func duplicate() {}
+
+@hasAsyncAlternative // expected-error {{'@hasAsyncAlternative' attribute cannot be applied to this declaration}}
+protocol SomeProto {
+  @hasAsyncAlternative
+  func protoFunc()
+}
+
+@hasAsyncAlternative // expected-error {{'@hasAsyncAlternative' attribute cannot be applied to this declaration}}
+struct SomeStruct: SomeProto {
+  func protoFunc() { }
+
+  @hasAsyncAlternative
+  func structFunc() { }
+
+  @hasAsyncAlternative
+  static func staticStructFunc() { }
+}
+
+@hasAsyncAlternative // expected-error {{'@hasAsyncAlternative' attribute cannot be applied to this declaration}}
+class SomeClass: SomeProto {
+  func protoFunc() { }
+
+  @hasAsyncAlternative
+  func classFunc() { }
+}

test/attr/attr_hasasyncalternative_conc_disabled.swift

@@ -0,0 +1,4 @@
+// RUN: %target-typecheck-verify-swift
+
+@hasAsyncAlternative // expected-error {{'hasAsyncAlternative' attribute is only valid when experimental concurrency is enabled}}
+func func1() {}

test/attr/attr_hasasyncalternative_disabled.swift

@@ -0,0 +1,6 @@
+// REQUIRES: concurrency
+
+// RUN: %target-typecheck-verify-swift -enable-experimental-concurrency
+
+@hasAsyncAlternative // expected-error {{'hasAsyncAlternative' support is required to be explicitly enabled using -experimental-has-async-alternative-attribute}}
+func func1() {}