[clang] add a `swift_async_name` attribute

[arphaman]

Summary

The swift_async_name attribute provides a name for a function/method that can be used to call the async overload of this method from Swift. This name specified in this attribute assumes that the last parameter in the function/method its applied to is removed when Swift invokes it, as the the Swift's await/async transformation implicitly constructs the callback.

[erik.pilkington]

LGTM!

clang/include/clang/Basic/AttrDocs.td

3640

function or method

[aaron.ballman]

There's no information in either the attribute definition in Attr.td or in the documentation as to what subject this attribute applies to.

clang/lib/Sema/SemaDeclAttr.cpp

5950

Do you actually need the ?: operator here, or is the conversion from bool sufficient?

6019

Please do not add an additional parameter to the handle functions -- we have a stretch goal of automating more of the switch behavior in SemaDeclAttr.cpp someday and we can only do that if the handle* functions have the same signatures.

clang/test/SemaObjC/attr-swift_name.m

184

This diagnostic is too confusing for me -- a lot of people get parameter/argument confused and so this reads a bit like the *attribute* has too many arguments to it when the real issue is that the signature specified by the attribute argument has too many parameters.

How about: too many parameters in the signature specified by the 'swift_async_name' attribute or something along those lines?

Also, missing tests for the number of arguments passed to the attribute. :-)

197

It's not clear whether we should have additional tests around other subjects - like, can I apply this attribute to a virtual class function in C++? If you can apply it to a C++ class method, does the implicit this parameter count when checking for the right parameter count?

Should also have a test that the attribute applies to a vanilla function (the only test currently fails because the function has no args, but we should show an explicitly accepted case as well).

[arphaman]

address review comments

[arphaman]

In D92355#2429117, @aaron.ballman wrote:

There's no information in either the attribute definition in Attr.td or in the documentation as to what subject this attribute applies to.

Added a subject list to the attribute.

clang/lib/Sema/SemaDeclAttr.cpp

5950

Thanks, I dropped it.

6019

Makes sense, thanks. I added a new function which should hopefully make it easier to automate in the future.

clang/test/SemaObjC/attr-swift_name.m

184

Thanks for the suggestion, I tweaked the warning text .

197

That's a good point. Added a regular function test as well. We don't need C++ support for this right now, but it might make sense to have it in the future when Swift and C++ interoperate, so added a test for C++ method as well.

[doug.gregor]

Thank you!

[aaron.ballman]

LGTM!

clang/include/clang/Basic/Attr.td

 def Regparm : TypeAttr {
   let Spellings = [GCC<"regparm">];
   let Args = [UnsignedArgument<"NumParams">];
   let Documentation = [RegparmDocs];
   // Represented as part of the enclosing function type.
   let ASTNode = 0;
 }
 
+def SwiftAsyncName : InheritableAttr {
+  let Spellings = [GNU<"swift_async_name">];
+  let Args = [StringArgument<"Name">];
+  let Subjects = SubjectList<[ObjCMethod, Function], ErrorDiag>;
+  let Documentation = [SwiftAsyncNameDocs];
+}
+
 def SwiftAttr : InheritableAttr {
   let Spellings = [GNU<"swift_attr">];
   let Args = [StringArgument<"Attribute">];
   let Documentation = [SwiftAttrDocs];
 }
 
 def SwiftBridge : InheritableAttr {
   let Spellings = [GNU<"swift_bridge">];

clang/include/clang/Basic/AttrDocs.td

 
 def SwiftDocs : DocumentationCategory<"Customizing Swift Import"> {
   let Content = [{
 Clang supports additional attributes for customizing how APIs are imported into
 Swift.
   }];
 }
 
+def SwiftAsyncNameDocs : Documentation {
+  let Category = SwiftDocs;
+  let Heading = "swift_async_name";
+  let Content = [{
+The ``swift_async_name`` attribute provides the name of the ``async`` overload for
+the given declaration in Swift. If this attribute is absent, the name is
+transformed according to the algorithm built into the Swift compiler.
+
+The argument is a string literal that contains the Swift name of the function or
+method. The name may be a compound Swift name. The function or method with such
+an attribute must have more than zero parameters, as its last parameter is
+assumed to be a callback that's eliminated in the Swift ``async`` name.
+
+  .. code-block:: objc
+
+    @interface URL
+    + (void) loadContentsFrom:(URL *)url callback:(void (^)(NSData *))data __attribute__((__swift_async_name__("URL.loadContentsFrom(_:)")))
+    @end
+  }];
+}
+
 def SwiftAttrDocs : Documentation {
   let Category = SwiftDocs;
   let Heading = "swift_attr";
   let Content = [{
 The ``swift_attr`` provides a Swift-specific annotation for the declaration
 to which the attribute appertains to. It can be used on any declaration
 in Clang. This kind of annotation is ignored by Clang as it doesn't have any
 semantic meaning in languages supported by Clang. The Swift compiler can

clang/include/clang/Basic/DiagnosticSemaKinds.td

: Warning<"%0 attribute for 'subscript' setter must have a 'newValue:' parameter">,
     InGroup<SwiftNameAttribute>;
 def warn_attr_swift_name_subscript_setter_multiple_newValues
   : Warning<"%0 attribute for 'subscript' setter cannot have multiple 'newValue:' parameters">,
     InGroup<SwiftNameAttribute>;
 def warn_attr_swift_name_subscript_getter_newValue
   : Warning<"%0 attribute for 'subscript' getter cannot have a 'newValue:' parameter">,
     InGroup<SwiftNameAttribute>;
 def warn_attr_swift_name_num_params
-  : Warning<"too %select{few|many}0 parameters in %1 attribute (expected %2; got %3)">,
+  : Warning<"too %select{few|many}0 parameters in the signature specified by "
+            "the %1 attribute (expected %2; got %3)">,
+    InGroup<SwiftNameAttribute>;
+def warn_attr_swift_name_decl_missing_params
+  : Warning<"%0 attribute cannot be applied to a %select{function|method}1 "
+            "with no parameters">,
     InGroup<SwiftNameAttribute>;
 
 def err_attr_swift_error_no_error_parameter : Error<
   "%0 attribute can only be applied to a %select{function|method}1 with an "
   "error parameter">;
 def err_attr_swift_error_return_type : Error<
   "%0 attribute with '%1' convention can only be applied to a "
   "%select{function|method}2 returning %select{an integral type|a pointer}3">;

clang/include/clang/Sema/Sema.h

public:
   /// Do a check to make sure \p Name looks like a legal argument for the
   /// swift_name attribute applied to decl \p D.  Raise a diagnostic if the name
   /// is invalid for the given declaration.
   ///
   /// \p AL is used to provide caret diagnostics in case of a malformed name.
   ///
   /// \returns true if the name is a valid swift name for \p D, false otherwise.
   bool DiagnoseSwiftName(Decl *D, StringRef Name, SourceLocation Loc,
-                         const ParsedAttr &AL);
+                         const ParsedAttr &AL, bool IsAsync);
 
   /// A derivative of BoundTypeDiagnoser for which the diagnostic's type
   /// parameter is preceded by a 0/1 enum that is 1 if the type is sizeless.
   /// For example, a diagnostic with no other parameters would generally have
   /// the form "...%select{incomplete|sizeless}0 type %1...".
   template <typename... Ts>
   class SizelessTypeDiagnoser : public BoundTypeDiagnoser<Ts...> {
   public:

clang/lib/Sema/SemaDeclAttr.cpp

if (IsSubscript) {
       }
     }
   }
 
   return true;
 }
 
 bool Sema::DiagnoseSwiftName(Decl *D, StringRef Name, SourceLocation Loc,
-                             const ParsedAttr &AL) {
+                             const ParsedAttr &AL, bool IsAsync) {
   if (isa<ObjCMethodDecl>(D) || isa<FunctionDecl>(D)) {
     ArrayRef<ParmVarDecl*> Params;
     unsigned ParamCount;
 
     if (const auto *Method = dyn_cast<ObjCMethodDecl>(D)) {
       ParamCount = Method->getSelector().getNumArgs();
       Params = Method->parameters().slice(0, ParamCount);
     } else {
       const auto *F = cast<FunctionDecl>(D);
 
       ParamCount = F->getNumParams();
       Params = F->parameters();
 
       if (!F->hasWrittenPrototype()) {
         Diag(Loc, diag::warn_attribute_wrong_decl_type) << AL
             << ExpectedFunctionWithProtoType;
         return false;
       }
     }
 
+    // The async name drops the last callback parameter.
+    if (IsAsync) {
+      if (ParamCount == 0) {
+        Diag(Loc, diag::warn_attr_swift_name_decl_missing_params)
+            << AL << isa<ObjCMethodDecl>(D);
+        return false;
+      }
+      ParamCount -= 1;
+    }
+
     unsigned SwiftParamCount;
     bool IsSingleParamInit;
     if (!validateSwiftFunctionName(*this, AL, Loc, Name,
                                    SwiftParamCount, IsSingleParamInit))
       return false;
 
     bool ParamCountValid;
     if (SwiftParamCount == ParamCount) {
if (isa<ObjCMethodDecl>(D) || isa<FunctionDecl>(D)) {
     }
 
     if (!ParamCountValid) {
       Diag(Loc, diag::warn_attr_swift_name_num_params)
           << (SwiftParamCount > ParamCount) << AL << ParamCount
           << SwiftParamCount;
       return false;
     }
-  } else if (isa<EnumConstantDecl>(D) || isa<ObjCProtocolDecl>(D) ||
+  } else if ((isa<EnumConstantDecl>(D) || isa<ObjCProtocolDecl>(D) ||
               isa<ObjCInterfaceDecl>(D) || isa<ObjCPropertyDecl>(D) ||
               isa<VarDecl>(D) || isa<TypedefNameDecl>(D) || isa<TagDecl>(D) ||
-             isa<IndirectFieldDecl>(D) || isa<FieldDecl>(D)) {
+              isa<IndirectFieldDecl>(D) || isa<FieldDecl>(D)) &&
+             !IsAsync) {
     StringRef ContextName, BaseName;
 
     std::tie(ContextName, BaseName) = Name.split('.');
     if (BaseName.empty()) {
       BaseName = ContextName;
       ContextName = StringRef();
     } else if (!isValidIdentifier(ContextName)) {
       Diag(Loc, diag::warn_attr_swift_name_invalid_identifier) << AL
bool Sema::DiagnoseSwiftName(Decl *D, StringRef Name, SourceLocation Loc,
   } else {
     Diag(Loc, diag::warn_attr_swift_name_decl_kind) << AL;
     return false;
   }
   return true;
 }
 
 static void handleSwiftName(Sema &S, Decl *D, const ParsedAttr &AL) {
   StringRef Name;
   SourceLocation Loc;
   if (!S.checkStringLiteralArgumentAttr(AL, 0, Name, &Loc))
     return;
 
-  if (!S.DiagnoseSwiftName(D, Name, Loc, AL))
+  if (!S.DiagnoseSwiftName(D, Name, Loc, AL, /*IsAsync=*/false))
     return;
 
   D->addAttr(::new (S.Context) SwiftNameAttr(S.Context, AL, Name));
 }
 
+static void handleSwiftAsyncName(Sema &S, Decl *D, const ParsedAttr &AL) {
+  StringRef Name;
+  SourceLocation Loc;
+  if (!S.checkStringLiteralArgumentAttr(AL, 0, Name, &Loc))
+    return;
+
+  if (!S.DiagnoseSwiftName(D, Name, Loc, AL, /*IsAsync=*/true))
+    return;
+
+  D->addAttr(::new (S.Context) SwiftAsyncNameAttr(S.Context, AL, Name));
+}
+
 static void handleSwiftNewType(Sema &S, Decl *D, const ParsedAttr &AL) {
   // Make sure that there is an identifier as the annotation's single argument.
   if (!checkAttributeNumArgs(S, AL, 1))
     return;
 
   if (!AL.isArgIdent(0)) {
     S.Diag(AL.getLoc(), diag::err_attribute_argument_type)
         << AL << AANT_ArgumentIdentifier;
static void ProcessDeclAttribute(Sema &S, Scope *scope, Decl *D,
   case ParsedAttr::AT_ArgumentWithTypeTag:
     handleArgumentWithTypeTagAttr(S, D, AL);
     break;
   case ParsedAttr::AT_TypeTagForDatatype:
     handleTypeTagForDatatypeAttr(S, D, AL);
     break;
 
   // Swift attributes.
+  case ParsedAttr::AT_SwiftAsyncName:
+    handleSwiftAsyncName(S, D, AL);
+    break;
   case ParsedAttr::AT_SwiftAttr:
     handleSwiftAttrAttr(S, D, AL);
     break;
   case ParsedAttr::AT_SwiftBridge:
     handleSwiftBridge(S, D, AL);
     break;
   case ParsedAttr::AT_SwiftBridgedTypedef:
     handleSimpleAttribute<SwiftBridgedTypedefAttr>(S, D, AL);

clang/test/Misc/pragma-attribute-supported-attributes-list.test

 // CHECK-NEXT: Restrict (SubjectMatchRule_function)
 // CHECK-NEXT: ReturnTypestate (SubjectMatchRule_function, SubjectMatchRule_variable_is_parameter)
 // CHECK-NEXT: ReturnsNonNull (SubjectMatchRule_objc_method, SubjectMatchRule_function)
 // CHECK-NEXT: ReturnsTwice (SubjectMatchRule_function)
 // CHECK-NEXT: ScopedLockable (SubjectMatchRule_record)
 // CHECK-NEXT: Section (SubjectMatchRule_function, SubjectMatchRule_variable_is_global, SubjectMatchRule_objc_method, SubjectMatchRule_objc_property)
 // CHECK-NEXT: SetTypestate (SubjectMatchRule_function_is_member)
 // CHECK-NEXT: SpeculativeLoadHardening (SubjectMatchRule_function, SubjectMatchRule_objc_method)
+// CHECK-NEXT: SwiftAsyncName (SubjectMatchRule_objc_method, SubjectMatchRule_function)
 // CHECK-NEXT: SwiftBridgedTypedef (SubjectMatchRule_type_alias)
 // CHECK-NEXT: SwiftContext (SubjectMatchRule_variable_is_parameter)
 // CHECK-NEXT: SwiftError (SubjectMatchRule_function, SubjectMatchRule_objc_method)
 // CHECK-NEXT: SwiftErrorResult (SubjectMatchRule_variable_is_parameter)
 // CHECK-NEXT: SwiftIndirectResult (SubjectMatchRule_variable_is_parameter)
 // CHECK-NEXT: SwiftNewType (SubjectMatchRule_type_alias)
 // CHECK-NEXT: SwiftObjCMembers (SubjectMatchRule_objc_interface)
 // CHECK-NEXT: TLSModel (SubjectMatchRule_variable_is_thread_local)

clang/test/SemaObjC/attr-swift_name.m

-// RUN: %clang_cc1 -verify -fsyntax-only -fobjc-arc %s
+// RUN: %clang_cc1 -verify -fsyntax-only -fobjc-arc -fblocks %s
 
 #define SWIFT_NAME(name) __attribute__((__swift_name__(name)))
+#define SWIFT_ASYNC_NAME(name) __attribute__((__swift_async_name__(name)))
 
 typedef struct {
   float x, y, z;
 } Point3D;
 
 __attribute__((__swift_name__("PType")))
 @protocol P
 @end

 - (I *)iWithValue:(int)value SWIFT_NAME("i(value:)");
 - (I *)iWithValue:(int)value value:(int)value2 SWIFT_NAME("i(value:extra:)");
 - (I *)iWithValueConvertingValue:(int)value value:(int)value2 SWIFT_NAME("i(_:extra:)");
 
 + (I *)iWithOtheValue:(int)value SWIFT_NAME("init");
 // expected-warning@-1 {{'__swift_name__' attribute argument must be a string literal specifying a Swift function name}}
 
 + (I *)iWithAnotherValue:(int)value SWIFT_NAME("i()");
-// expected-warning@-1 {{too few parameters in '__swift_name__' attribute (expected 1; got 0)}}
+// expected-warning@-1 {{too few parameters in the signature specified by the '__swift_name__' attribute (expected 1; got 0)}}
 
 + (I *)iWithYetAnotherValue:(int)value SWIFT_NAME("i(value:extra:)");
-// expected-warning@-1 {{too many parameters in '__swift_name__' attribute (expected 1; got 2}}
+// expected-warning@-1 {{too many parameters in the signature specified by the '__swift_name__' attribute (expected 1; got 2}}
 
 + (I *)iAndReturnErrorCode:(int *)errorCode SWIFT_NAME("i()"); // no-warning
 + (I *)iWithValue:(int)value andReturnErrorCode:(int *)errorCode SWIFT_NAME("i(value:)"); // no-warning
 
 + (I *)iFromErrorCode:(const int *)errorCode SWIFT_NAME("i()");
-// expected-warning@-1 {{too few parameters in '__swift_name__' attribute (expected 1; got 0)}}
+// expected-warning@-1 {{too few parameters in the signature specified by the '__swift_name__' attribute (expected 1; got 0)}}
 
 + (I *)iWithPointerA:(int *)value andReturnErrorCode:(int *)errorCode SWIFT_NAME("i()"); // no-warning
 + (I *)iWithPointerB:(int *)value andReturnErrorCode:(int *)errorCode SWIFT_NAME("i(pointer:)"); // no-warning
 + (I *)iWithPointerC:(int *)value andReturnErrorCode:(int *)errorCode SWIFT_NAME("i(pointer:errorCode:)"); // no-warning
 
 + (I *)iWithOtherI:(I *)other SWIFT_NAME("i()");
-// expected-warning@-1 {{too few parameters in '__swift_name__' attribute (expected 1; got 0)}}
+// expected-warning@-1 {{too few parameters in the signature specified by the '__swift_name__' attribute (expected 1; got 0)}}
 
 + (instancetype)specialI SWIFT_NAME("init(options:)");
 + (instancetype)specialJ SWIFT_NAME("init(options:extra:)");
-// expected-warning@-1 {{too many parameters in '__swift_name__' attribute (expected 0; got 2)}}
+// expected-warning@-1 {{too many parameters in the signature specified by the '__swift_name__' attribute (expected 0; got 2)}}
 + (instancetype)specialK SWIFT_NAME("init(_:)");
-// expected-warning@-1 {{too many parameters in '__swift_name__' attribute (expected 0; got 1)}}
+// expected-warning@-1 {{too many parameters in the signature specified by the '__swift_name__' attribute (expected 0; got 1)}}
 + (instancetype)specialL SWIFT_NAME("i(options:)");
-// expected-warning@-1 {{too many parameters in '__swift_name__' attribute (expected 0; got 1)}}
+// expected-warning@-1 {{too many parameters in the signature specified by the '__swift_name__' attribute (expected 0; got 1)}}
 
 + (instancetype)trailingParen SWIFT_NAME("foo(");
 // expected-warning@-1 {{'__swift_name__' attribute argument must be a string literal specifying a Swift function name}}
 + (instancetype)trailingColon SWIFT_NAME("foo:");
 // expected-warning@-1 {{'__swift_name__' attribute argument must be a string literal specifying a Swift function name}}
 + (instancetype)initialIgnore:(int)value SWIFT_NAME("_(value:)");
 // expected-warning@-1 {{'__swift_name__' attribute has invalid identifier for the base name}}
 + (instancetype)middleOmitted:(int)value SWIFT_NAME("i(:)");

 };
 
 int i SWIFT_NAME("g_i");
 
 void f0(int i) SWIFT_NAME("f_0");
 // expected-warning@-1 {{'__swift_name__' attribute argument must be a string literal specifying a Swift function name}}
 
 void f1(int i) SWIFT_NAME("f_1()");
-// expected-warning@-1 {{too few parameters in '__swift_name__' attribute (expected 1; got 0)}}
+// expected-warning@-1 {{too few parameters in the signature specified by the '__swift_name__' attribute (expected 1; got 0)}}
 
 void f2(int i) SWIFT_NAME("f_2(a:b:)");
-// expected-warning@-1 {{too many parameters in '__swift_name__' attribute (expected 1; got 2)}}
+// expected-warning@-1 {{too many parameters in the signature specified by the '__swift_name__' attribute (expected 1; got 2)}}
 
 void f3(int x, int y) SWIFT_NAME("fWithX(_:y:)");
 void f4(int x, int *error) SWIFT_NAME("fWithX(_:)");
 
 typedef int int_t SWIFT_NAME("IntType");
 
 struct Point3D createPoint3D(float x, float y, float z) SWIFT_NAME("Point3D.init(x:y:z:)");
 struct Point3D rotatePoint3D(Point3D point, float radians) SWIFT_NAME("Point3D.rotate(self:radians:)");
 struct Point3D badRotatePoint3D(Point3D point, float radians) SWIFT_NAME("Point3D.rotate(radians:)");
-// expected-warning@-1 {{too few parameters in '__swift_name__' attribute (expected 2; got 1)}}
+// expected-warning@-1 {{too few parameters in the signature specified by the '__swift_name__' attribute (expected 2; got 1)}}
 
 extern struct Point3D identityPoint SWIFT_NAME("Point3D.identity");
 
 float Point3DGetMagnitude(Point3D point) SWIFT_NAME("getter:Point3D.magnitude(self:)");
 float Point3DGetMagnitudeAndSomethingElse(Point3D point, float f) SWIFT_NAME("getter:Point3D.magnitude(self:f:)");
 // expected-warning@-1 {{'__swift_name__' attribute for getter must not have any parameters besides 'self:'}}
 
 float Point3DGetRadius(Point3D point) SWIFT_NAME("getter:Point3D.radius(self:)");

 // expected-warning@-1 {{'__swift_name__' attribute argument must be a string literal specifying a Swift function name}}
 
 void g(int i) SWIFT_NAME("function(int:)");
 // expected-note@-1 {{conflicting attribute is here}}
 
 // expected-error@+1 {{'swift_name' and 'swift_name' attributes are not compatible}}
 void g(int i) SWIFT_NAME("function(_:)") {
 }
+
+typedef int (^CallbackTy)(void);
+
+@interface AsyncI<P>
+
+- (void)doSomethingWithCallback:(CallbackTy)callback SWIFT_ASYNC_NAME("doSomething()");
+- (void)doSomethingX:(int)x withCallback:(CallbackTy)callback SWIFT_ASYNC_NAME("doSomething(x:)");
+
+// expected-warning@+1 {{too many parameters in the signature specified by the '__swift_async_name__' attribute (expected 1; got 2)}}
+- (void)doSomethingY:(int)x withCallback:(CallbackTy)callback SWIFT_ASYNC_NAME("doSomething(x:y:)");
+
+// expected-warning@+1 {{too few parameters in the signature specified by the '__swift_async_name__' attribute (expected 1; got 0)}}
+- (void)doSomethingZ:(int)x withCallback:(CallbackTy)callback SWIFT_ASYNC_NAME("doSomething()");
+
+// expected-warning@+1 {{'__swift_async_name__' attribute cannot be applied to a method with no parameters}}
+- (void)doSomethingNone SWIFT_ASYNC_NAME("doSomething()");
+
+// expected-error@+1 {{'__swift_async_name__' attribute takes one argument}}
+- (void)brokenAttr __attribute__((__swift_async_name__("brokenAttr", 2)));
+
+@end
+
+void asyncFunc(CallbackTy callback) SWIFT_ASYNC_NAME("asyncFunc()");
+
+// expected-warning@+1 {{'__swift_async_name__' attribute cannot be applied to a function with no parameters}}
+void asyncNoParams(void) SWIFT_ASYNC_NAME("asyncNoParams()");
+
+// expected-error@+1 {{'__swift_async_name__' attribute only applies to Objective-C methods and functions}}
+SWIFT_ASYNC_NAME("NoAsync")
+@protocol NoAsync @end

clang/test/SemaObjCXX/attr-swift_name-cxx.mm

+// RUN: %clang_cc1 -verify -fsyntax-only -fobjc-arc -fblocks %s
+
+#define SWIFT_ASYNC_NAME(name) __attribute__((__swift_async_name__(name)))
+
+typedef int (^CallbackTy)(void);
+
+class CXXClass {
+public:
+  virtual void doSomethingWithCallback(CallbackTy callback) SWIFT_ASYNC_NAME("doSomething()");
+
+  // expected-warning@+1 {{too few parameters in the signature specified by the '__swift_async_name__' attribute (expected 1; got 0)}}
+  virtual void doSomethingWithCallback(int x, CallbackTy callback) SWIFT_ASYNC_NAME("doSomething()");
+};