[interop] update names and add docs for the interop C++ helper macros

Author: hyp

include/swift/AST/DiagnosticsClangImporter.def

@@ -189,8 +189,8 @@ NOTE(projection_may_return_interior_ptr, none, "C++ method '%0' may return an "
 NOTE(mark_self_contained, none, "Mark type '%0' as 'SELF_CONTAINED' in C++ to "
                                  "make methods that use it available in Swift. ",
      (StringRef))
-NOTE(mark_safe_to_import, none, "Mark method '%0' as 'SAFE_TO_IMPORT' in C++ to "
-                                "make it available in Swift. ",
+NOTE(mark_safe_to_import, none, "annotate method '%0' with 'RETURNS_INDEPENDENT_VALUE' in C++ to "
+                                "make it available in Swift",
      (StringRef))
 
 NOTE(at_to_subscript, none, "Do you want to replace it with a call "

lib/ClangImporter/CMakeLists.txt

@@ -50,6 +50,7 @@ set(SWIFTINC_DIR
 
 add_custom_command(
     OUTPUT "${SWIFTINC_DIR}/bridging"
+    DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/bridging"
     COMMAND "${CMAKE_COMMAND}" "-E" "copy" "${CMAKE_CURRENT_SOURCE_DIR}/bridging" "${SWIFTINC_DIR}")
 
 add_custom_target("copy_cxxInterop_support_header"

lib/ClangImporter/ClangImporter.cpp

@@ -4408,8 +4408,8 @@ static void diagnoseForeignReferenceTypeFixit(ClangImporter::Implementation &Imp
                                               HeaderLoc loc, Diagnostic diag) {
   auto importedLoc =
     Impl.SwiftContext.getClangModuleLoader()->importSourceLocation(loc.clangLoc);
-  Impl.diagnose(loc, diag)
-    .fixItInsert(importedLoc, "SWIFT_REFERENCE_TYPE(<#retain#>, <#release#>) ");
+  Impl.diagnose(loc, diag).fixItInsert(
+      importedLoc, "SHARED_REFERENCE(<#retain#>, <#release#>) ");
 }
 
 bool ClangImporter::Implementation::emitDiagnosticsForTarget(

lib/ClangImporter/bridging

@@ -17,18 +17,98 @@
 #ifndef SWIFT_CLANGIMPORTER_SWIFT_INTEROP_SUPPORT_H
 #define SWIFT_CLANGIMPORTER_SWIFT_INTEROP_SUPPORT_H
 
+/// Specifies that a C++ `class` or `struct` owns and controls the lifetime of all
+/// of the objects it references. Such type should not reference any objects whose
+/// lifetime is controlled externally. This annotation allows Swift to import methods
+/// that return a `class` or `struct` type that is annotated with this macro.
 #define SELF_CONTAINED __attribute__((swift_attr("import_owned")))
-#define SAFE_TO_IMPORT __attribute__((swift_attr("import_unsafe")))
+
+/// Specifies that a C++ method returns a value that is presumed to contain
+/// objects whose lifetime is not dependent on `this` or other parameters passed
+/// to the method.
+#define RETURNS_INDEPENDENT_VALUE __attribute__((swift_attr("import_unsafe")))
 
 #define _CXX_INTEROP_STRINGIFY(_x) #_x
-#define SWIFT_REFERENCE_TYPE(_retain, _release)                                \
-  __attribute__((swift_attr("import_reference")))                              \
-  __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(retain:_retain))))          \
+
+/// Specifies that a C++ `class` or `struct` is reference-counted using
+/// the given `retain` and `release` functions. This annotation lets Swift import
+/// such a type as reference counted type in Swift, taking advantage of Swift's
+/// automatic reference counting.
+///
+/// This example shows how to use this macro to let Swift know that
+/// a non-copyable reference counted C++ class can be imported as a reference counted type in Swift:
+///  ```c++
+///    class SHARED_REFERENCE(retainSharedObject, releaseSharedObject)
+///    SharedObject : NonCopyable, IntrusiveReferenceCounted<SharedObject> {
+///    public:
+///      static SharedObject* create();
+///      void doSomething();
+///    };
+///
+///    void retainSharedObject(SharedObject *);
+///    void releaseSharedObject(SharedObject *);
+///  ```
+///
+///  Then, the Swift programmer would be able to use it in the following manner:
+///
+///  ```swift
+///    let object = SharedObject.create()
+///    object.doSomething()
+///    // The Swift compiler will release object here.
+///  ```
+#define SHARED_REFERENCE(_retain, _release)                                \
+  __attribute__((swift_attr("import_reference")))                          \
+  __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(retain:_retain))))      \
   __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(release:_release))))
 
+/// Specifies that a C++ `class` or `struct` is a reference type whose lifetime
+/// is presumed to be immortal, i.e. the reference to such object is presumed to
+/// always be valid. This annotation lets Swift import such a type as a reference
+/// type in Swift.
+////
+/// This example shows how to use this macro to let Swift know that
+/// a non-copyable singleton C++ class can be imported as a reference type in Swift:
+///  ```c++
+///    class IMMORTAL_REFERENCE
+///    LoggerSingleton : NonCopyable {
+///    public:
+///      static LoggerSingleton &getInstance();
+///      void log(int x);
+///    };
+///  ```
+///
+///  Then, the Swift programmer would be able to use it in the following manner:
+///
+///  ```swift
+///    let logger = LoggerSingleton.getInstance()
+///    logger.log(123)
+///  ```
+#define IMMORTAL_REFERENCE                                                \
+  __attribute__((swift_attr("import_reference")))                         \
+  __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(retain:immortal))))    \
+  __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(release:immortal))))
+
+/// Specifies that a C++ `class` or `struct` is a reference type whose lifetime
+/// is not managed automatically. The programmer must validate that any reference
+/// to such object is valid themselves. This annotation lets Swift import such a type as a reference type in Swift.
+#define UNSAFE_REFERENCE                                                  \
+  __attribute__((swift_attr("import_reference")))                         \
+  __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(retain:immortal))))    \
+  __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(release:immortal))))
+
+/// Specifies a name that will be used in Swift for this declaration instead of its original name.
 #define SWIFT_NAME(_name) __attribute__((swift_name(#_name)))
 
-#define CONFORMS_TO(_name) \
-  __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(conforms_to:_name))))
+/// Specifies that a specific C++ `class` or `struct` conforms to a
+/// a specific Swift protocol.
+///
+/// This example shows how to use this macro to conform a class template to a Swift protocol:
+///  ```
+///    template<class T>
+///    class CONFORMS_TO_PROTOCOL(SwiftModule.ProtocolName)
+///    CustomClass {};
+///  ```
+#define CONFORMS_TO_PROTOCOL(_moduleName_protocolName) \
+  __attribute__((swift_attr(_CXX_INTEROP_STRINGIFY(conforms_to:_moduleName_protocolName))))
 
 #endif // SWIFT_CLANGIMPORTER_SWIFT_INTEROP_SUPPORT_H

lib/Sema/CSDiagnostics.cpp

@@ -3910,8 +3910,7 @@ void MissingMemberFailure::diagnoseUnsafeCxxMethod(SourceLoc loc,
       ctx.Diags
           .diagnose(methodSwiftLoc, diag::mark_safe_to_import,
                     name.getBaseIdentifier().str())
-          .fixItInsert(methodSwiftLoc,
-                       " SAFE_TO_IMPORT ");
+          .fixItInsert(methodSwiftLoc, " RETURNS_INDEPENDENT_VALUE ");
     } else if (cxxMethod->getReturnType()->isReferenceType()) {
       // Rewrite a call to .at(42) as a subscript.
       if (name.getBaseIdentifier().is("at") &&
@@ -3941,8 +3940,7 @@ void MissingMemberFailure::diagnoseUnsafeCxxMethod(SourceLoc loc,
         ctx.Diags
             .diagnose(methodSwiftLoc, diag::mark_safe_to_import,
                       name.getBaseIdentifier().str())
-            .fixItInsert(methodSwiftLoc,
-                         " SAFE_TO_IMPORT ");
+            .fixItInsert(methodSwiftLoc, " RETURNS_INDEPENDENT_VALUE ");
       }
     } else if (cxxMethod->getReturnType()->isRecordType()) {
       if (auto cxxRecord = dyn_cast<clang::CXXRecordDecl>(
@@ -3967,8 +3965,7 @@ void MissingMemberFailure::diagnoseUnsafeCxxMethod(SourceLoc loc,
           ctx.Diags
               .diagnose(methodSwiftLoc, diag::mark_safe_to_import,
                         name.getBaseIdentifier().str())
-              .fixItInsert(methodSwiftLoc,
-                           " SAFE_TO_IMPORT ");
+              .fixItInsert(methodSwiftLoc, " RETURNS_INDEPENDENT_VALUE ");
           ctx.Diags
               .diagnose(baseSwiftLoc, diag::mark_self_contained, returnTypeStr)
               .fixItInsert(baseSwiftLoc,

test/Interop/Cxx/class/fixit-add-safe-to-import-self-contained.swift

@@ -21,17 +21,17 @@ struct X {
 import Test
 
 public func test(x: X) {
-  // CHECK: note: Mark method 'test' as 'SAFE_TO_IMPORT' in C++ to make it available in Swift.
+  // CHECK: note: annotate method 'test' with 'RETURNS_INDEPENDENT_VALUE' in C++ to make it available in Swift
   // CHECK: int *test() { }
   // CHECK: ^
-  // CHECK: SAFE_TO_IMPORT
+  // CHECK: RETURNS_INDEPENDENT_VALUE
 
   x.test()
 
-  // CHECK: note: Mark method 'other' as 'SAFE_TO_IMPORT' in C++ to make it available in Swift.
+  // CHECK: note: annotate method 'other' with 'RETURNS_INDEPENDENT_VALUE' in C++ to make it available in Swift
   // CHECK: Ptr other() { }
   // CHECK: ^
-  // CHECK: SAFE_TO_IMPORT
+  // CHECK: RETURNS_INDEPENDENT_VALUE
 
   // CHECK: note: Mark type 'Ptr' as 'SELF_CONTAINED' in C++ to make methods that use it available in Swift.
   // CHECK: struct Ptr {

test/Interop/Cxx/class/invalid-class-errors.swift

@@ -30,15 +30,15 @@ import Test
 // CHECK: note: record 'A' is not automatically available: does not have a copy constructor or destructor. Does this type have reference semantics?
 // CHECK: struct A {
 // CHECK: ^
-// CHECK: SWIFT_REFERENCE_TYPE(<#retain#>, <#release#>)
+// CHECK: SHARED_REFERENCE(<#retain#>, <#release#>)
 public func test(x: A) { }
 // CHECK: note: record 'B' is not automatically available: does not have a copy constructor or destructor. Does this type have reference semantics?
 // CHECK: struct {{.*}}B {
 // CHECK: ^
-// CHECK: SWIFT_REFERENCE_TYPE(<#retain#>, <#release#>)
+// CHECK: SHARED_REFERENCE(<#retain#>, <#release#>)
 public func test(x: B) { }
 // CHECK: note: record 'Nested' is not automatically available: does not have a copy constructor or destructor. Does this type have reference semantics?
 // CHECK: struct Nested {
 // CHECK: ^
-// CHECK: SWIFT_REFERENCE_TYPE(<#retain#>, <#release#>)
+// CHECK: SHARED_REFERENCE(<#retain#>, <#release#>)
 public func test(x: Namespace.Nested) { }

test/Interop/Cxx/class/invalid-unsafe-projection-errors.swift

@@ -29,15 +29,15 @@ import Test
 public func test(x: M) {
   // CHECK: note: C++ method 'test1' that returns a pointer of type 'UnsafeMutablePointer' is unavailable.
   // CHECK: note: C++ method 'test1' may return an interior pointer.
-  // CHECK: note: Mark method 'test1' as 'SAFE_TO_IMPORT' in C++ to make it available in Swift.
+  // CHECK: note: annotate method 'test1' with 'RETURNS_INDEPENDENT_VALUE' in C++ to make it available in Swift
   x.test1()
   // CHECK: note: C++ method 'test2' that returns a reference of type 'UnsafeMutablePointer' is unavailable.
   // CHECK: note: C++ method 'test2' may return an interior pointer.
-  // CHECK: note: Mark method 'test2' as 'SAFE_TO_IMPORT' in C++ to make it available in Swift.
+  // CHECK: note: annotate method 'test2' with 'RETURNS_INDEPENDENT_VALUE' in C++ to make it available in Swift
   x.test2()
   // CHECK: note: C++ method 'test3' that returns a value of type 'Ptr' is unavailable.
   // CHECK: note: C++ method 'test3' may return an interior pointer.
-  // CHECK: note: Mark method 'test3' as 'SAFE_TO_IMPORT' in C++ to make it available in Swift.
+  // CHECK: note: annotate method 'test3' with 'RETURNS_INDEPENDENT_VALUE' in C++ to make it available in Swift
   // CHECK: note: Mark type 'Ptr' as 'SELF_CONTAINED' in C++ to make methods that use it available in Swift.
   x.test3()
   // CHECK: note: C++ method 'begin' that returns an iterator is unavailable

test/Interop/Cxx/ergonomics/swift-bridging-annotations.swift

@@ -0,0 +1,82 @@
+// RUN: rm -rf %t
+// RUN: split-file %s %t
+
+// RUN: %target-swift-frontend %t/SwiftMod.swift -module-name SwiftMod -emit-module -o %t/SwiftMod.swiftmodule -I %t -enable-experimental-cxx-interop -Xcc -DFIRSTPASS
+
+// RUN: %target-swift-ide-test -print-module -module-to-print=SwiftMod -module-to-print=CxxModule -I %t -I %t/Inputs -I %swift_src_root/lib/ClangImporter -source-filename=x -enable-experimental-cxx-interop | %FileCheck %s
+
+//--- SwiftMod.swift
+
+public protocol Proto {
+}
+
+//--- Inputs/module.modulemap
+module CxxModule {
+    header "header.h"
+    requires cplusplus
+}
+
+//--- Inputs/header.h
+
+// Note: in actuality, this will be included
+// as <swift/bridging>, but in this test we include
+// it directly.
+#include "bridging"
+
+class SELF_CONTAINED SelfContained {
+public:
+    int *pointer;
+
+    SelfContained();
+
+    const int *returnsIndependent() const RETURNS_INDEPENDENT_VALUE;
+};
+
+class SHARED_REFERENCE(retainSharedObject, releaseSharedObject)
+SharedObject {
+public:
+    static SharedObject *create();
+};
+
+void retainSharedObject(SharedObject *);
+void releaseSharedObject(SharedObject *);
+
+class IMMORTAL_REFERENCE LoggerSingleton {
+public:
+    LoggerSingleton(const LoggerSingleton &) = delete;
+    static LoggerSingleton *getInstance();
+};
+
+class UNSAFE_REFERENCE UnsafeNonCopyable {
+public:
+    UnsafeNonCopyable(UnsafeNonCopyable &) = delete;
+};
+
+UnsafeNonCopyable *returnsPointerToUnsafeReference();
+void takesPointerToUnsafeNonCopyable(UnsafeNonCopyable *);
+
+class CONFORMS_TO_PROTOCOL(SwiftMod.Proto) ConformsTo {
+public:
+};
+
+
+// CHECK: struct SelfContained {
+
+// CHECK:   func returnsIndependent() -> UnsafePointer<Int32>!
+
+// CHECK: class SharedObject {
+// CHECK:   class func create() -> SharedObject!
+// CHECK: func retainSharedObject(_: SharedObject!)
+// CHECK: func releaseSharedObject(_: SharedObject!)
+
+// CHECK: class LoggerSingleton {
+// CHECK:   class func getInstance() -> LoggerSingleton!
+// CHECK: }
+
+// CHECK: class UnsafeNonCopyable {
+// CHECK: }
+// CHECK: func returnsPointerToUnsafeReference() -> UnsafeNonCopyable!
+// CHECK: func takesPointerToUnsafeNonCopyable(_: UnsafeNonCopyable!)
+
+// CHECK: struct ConformsTo : Proto {
+