[5.1 04-24-2019] Opaque result types, SE-244

CHANGELOG.md

@@ -25,6 +25,20 @@ CHANGELOG
 Swift 5.1
 ---------
 
+* [SE-0244][]:
+
+  Functions can now hide their concrete return type by declaring what protocols
+  it conforms to instead of specifying the exact return type:
+
+  ```
+  func makeMeACollection() -> some Collection {
+    return [1, 2, 3]
+  }
+  ```
+
+  Code that calls the function can use the interface of the protocol, but
+  does not have visibility into the underlying type.
+
 * [SE-0254][]:
 
   Subscripts can now be declared `static` or (inside classes) `class`.

docs/ABI/Mangling.rst

@@ -78,8 +78,13 @@ The following symbolic reference kinds are currently implemented:
 
 ::
 
-   {any-generic-type, protocol} ::= '\x01' .{4}              // Reference points directly to context descriptor
-   {any-generic-type, protocol} ::= '\x02' .{4}              // Reference points indirectly to context descriptor
+   #if SWIFT_RUNTIME_VERSION < 5.1
+     {any-generic-type, protocol} ::= '\x01' .{4} // Reference points directly to context descriptor
+     {any-generic-type, protocol} ::= '\x02' .{4} // Reference points indirectly to context descriptor
+   #else
+     {any-generic-type, protocol, opaque-type-decl-name} ::= '\x01' .{4} // Reference points directly to context descriptor
+     {any-generic-type, protocol, opaque-type-decl-name} ::= '\x02' .{4} // Reference points indirectly to context descriptor
+   #endif
    // The grammatical role of the symbolic reference is determined by the
    // kind of context descriptor referenced
 
@@ -91,7 +96,15 @@ The following symbolic reference kinds are currently implemented:
 
    associated-conformance-access-function ::= '\x07' .{4}  // Reference points directly to associated conformance access function relative to the protocol
    associated-conformance-access-function ::= '\x08' .{4}  // Reference points directly to associated conformance access function relative to the conforming type
-   keypath-metadata-access-function ::= '\x09' {.4}  // Reference points directly to keypath conformance access function
+
+   // keypaths only in Swift 5.0, generalized in Swift 5.1
+   #if SWIFT_RUNTIME_VERSION >= 5.1
+     metadata-access-function ::= '\x09' .{4}  // Reference points directly to metadata access function that can be invoked to produce referenced object
+   #endif
+
+A mangled name may also include ``\xFF`` bytes, which are only used for
+alignment padding. They do not affect what the mangled name references and can
+be skipped over and ignored.
 
 Globals
 ~~~~~~~
@@ -110,6 +123,9 @@ Globals
   global ::= nominal-type 'Ml'           // in-place type initialization cache
   global ::= nominal-type 'Mm'           // class metaclass
   global ::= nominal-type 'Mn'           // nominal type descriptor
+  #if SWIFT_RUNTIME_VERSION >= 5.1
+    global ::= opaque-type-decl-name 'MQ'  // opaque type descriptor -- added in Swift 5.1
+  #endif
   global ::= nominal-type 'Mu'           // class method lookup function
   global ::= nominal-type 'MU'           // ObjC metadata update callback function
   global ::= nominal-type 'Ms'           // ObjC resilient class stub
@@ -600,6 +616,20 @@ For the most part, manglings follow the structure of formal language
 types.  However, in some cases it is more useful to encode the exact
 implementation details of a function type.
 
+::
+
+  #if SWIFT_VERSION >= 5.1
+    type ::= 'Qr'                         // opaque result type (of current decl)
+    type ::= opaque-type-decl-name bound-generic-args 'Qo' INDEX // opaque type
+
+    opaque-type-decl-name ::= entity 'QO' // opaque result type of specified decl
+  #endif
+
+Opaque return types have a special short representation in the mangling of
+their defining entity. In structural position, opaque types are fully qualified
+by mangling the defining entity for the opaque declaration and the substitutions
+into the defining entity's generic environment.
+
 The ``type*`` list contains parameter and return types (including the error
 result), in that order.
 The number of parameters and results must match with the number of

include/swift/ABI/Metadata.h

@@ -3005,6 +3005,58 @@ struct TargetProtocolDescriptor final
     return cd->getKind() == ContextDescriptorKind::Protocol;
   }
 };
+
+/// The descriptor for an opaque type.
+template <typename Runtime>
+struct TargetOpaqueTypeDescriptor final
+  : TargetContextDescriptor<Runtime>,
+    TrailingGenericContextObjects<TargetOpaqueTypeDescriptor<Runtime>,
+                                  TargetGenericContextDescriptorHeader,
+                                  RelativeDirectPointer<const char>>
+{
+private:
+  using TrailingGenericContextObjects
+    = TrailingGenericContextObjects<TargetOpaqueTypeDescriptor<Runtime>,
+                                    TargetGenericContextDescriptorHeader,
+                                    RelativeDirectPointer<const char>>;
+  using TrailingObjects =
+    typename TrailingGenericContextObjects::TrailingObjects;
+  friend TrailingObjects;
+
+  template<typename T>
+  using OverloadToken = typename TrailingObjects::template OverloadToken<T>;
+
+public:
+  using TrailingGenericContextObjects::getGenericContext;
+  using TrailingGenericContextObjects::getGenericContextHeader;
+  using TrailingGenericContextObjects::getFullGenericContextHeader;
+  using TrailingGenericContextObjects::getGenericParams;
+
+  // The kind-specific flags area is used to store the count of the generic
+  // arguments for underlying type(s) encoded in the descriptor.
+  unsigned getNumUnderlyingTypeArguments() const {
+    return this->Flags.getKindSpecificFlags();
+  }
+
+  using TrailingGenericContextObjects::numTrailingObjects;
+  size_t numTrailingObjects(OverloadToken<RelativeDirectPointer<const char>>) const {
+    return getNumUnderlyingTypeArguments();
+  }
+
+  StringRef getUnderlyingTypeArgument(unsigned i) const {
+    assert(i < getNumUnderlyingTypeArguments());
+    const char *ptr =
+    (this->template getTrailingObjects<RelativeDirectPointer<const char>>())[i];
+
+    return Demangle::makeSymbolicMangledNameStringRef(ptr);
+  }
+
+  static bool classof(const TargetContextDescriptor<Runtime> *cd) {
+    return cd->getKind() == ContextDescriptorKind::OpaqueType;
+  }
+};
+
+using OpaqueTypeDescriptor = TargetOpaqueTypeDescriptor<InProcess>;
 
 /// The instantiation cache for generic metadata.  This must be guaranteed
 /// to zero-initialized before it is first accessed.  Its contents are private
@@ -4213,6 +4265,9 @@ TargetContextDescriptor<Runtime>::getGenericContext() const {
   case ContextDescriptorKind::Struct:
     return llvm::cast<TargetStructDescriptor<Runtime>>(this)
         ->getGenericContext();
+  case ContextDescriptorKind::OpaqueType:
+    return llvm::cast<TargetOpaqueTypeDescriptor<Runtime>>(this)
+        ->getGenericContext();
   default:    
     // We don't know about this kind of descriptor.
     return nullptr;
@@ -4264,6 +4319,8 @@ TargetTypeContextDescriptor<Runtime>::getGenericParams() const {
     return llvm::cast<TargetEnumDescriptor<Runtime>>(this)->getGenericParams();
   case ContextDescriptorKind::Struct:
     return llvm::cast<TargetStructDescriptor<Runtime>>(this)->getGenericParams();
+  case ContextDescriptorKind::OpaqueType:
+    return llvm::cast<TargetOpaqueTypeDescriptor<Runtime>>(this)->getGenericParams();
   default:
     swift_runtime_unreachable("Not a type context descriptor.");
   }

include/swift/ABI/MetadataValues.h

@@ -1102,6 +1102,9 @@ enum class ContextDescriptorKind : uint8_t {
 
   /// This context descriptor represents a protocol context.
   Protocol = 3,
+
+  /// This context descriptor represents an opaque type alias.
+  OpaqueType = 4,
 
   /// First kind that represents a type of any sort.
   Type_First = 16,

include/swift/AST/ASTContext.h

@@ -84,6 +84,7 @@ namespace swift {
   class ModuleLoader;
   class NominalTypeDecl;
   class NormalProtocolConformance;
+  class OpaqueTypeDecl;
   class InheritedProtocolConformance;
   class SelfProtocolConformance;
   class SpecializedProtocolConformance;
@@ -952,6 +953,7 @@ class ASTContext final {
 
   friend TypeBase;
   friend ArchetypeType;
+  friend OpaqueTypeDecl;
 
   /// Provide context-level uniquing for SIL lowered type layouts and boxes.
   friend SILLayout;

include/swift/AST/ASTDemangler.h

@@ -58,6 +58,9 @@ class ASTBuilder {
   using BuiltTypeDecl = swift::GenericTypeDecl *; // nominal or type alias
   using BuiltProtocolDecl = swift::ProtocolDecl *;
   explicit ASTBuilder(ASTContext &ctx) : Ctx(ctx) {}
+
+  /// The resolver to use for type checking, if necessary.
+  LazyResolver *Resolver = nullptr;
 
   ASTContext &getASTContext() { return Ctx; }
   DeclContext *getNotionalDC();
@@ -82,6 +85,10 @@ class ASTBuilder {
   Type createTypeAliasType(GenericTypeDecl *decl, Type parent);
 
   Type createBoundGenericType(GenericTypeDecl *decl, ArrayRef<Type> args);
+
+  Type resolveOpaqueType(NodePointer opaqueDescriptor,
+                         ArrayRef<Type> args,
+                         unsigned ordinal);
 
   Type createBoundGenericType(GenericTypeDecl *decl, ArrayRef<Type> args,
                               Type parent);

include/swift/AST/ASTMangler.h

@@ -59,12 +59,18 @@ class ASTMangler : public Mangler {
 
 public:
   using SymbolicReferent = llvm::PointerUnion<const NominalTypeDecl *,
-                                              const ProtocolConformance *>;
+                                              const OpaqueTypeDecl *>;
 protected:
 
   /// If set, the mangler calls this function to determine whether to symbolic
-  /// reference a given entity. Defaults to always returning true.
+  /// reference a given entity. If null, the mangler acts as if it's set to
+  /// always return true.
   std::function<bool (SymbolicReferent)> CanSymbolicReference;
+
+  bool canSymbolicReference(SymbolicReferent referent) {
+    return AllowSymbolicReferences
+      && (!CanSymbolicReference || CanSymbolicReference(referent));
+  }
 
   std::vector<std::pair<SymbolicReferent, unsigned>> SymbolicReferences;
 
@@ -201,7 +207,7 @@ class ASTMangler : public Mangler {
 
   void appendSymbolKind(SymbolKind SKind);
 
-  void appendType(Type type);
+  void appendType(Type type, const ValueDecl *forDecl = nullptr);
 
   void appendDeclName(const ValueDecl *decl);
 
@@ -215,6 +221,15 @@ class ASTMangler : public Mangler {
 
   void bindGenericParameters(CanGenericSignature sig);
 
+  /// Mangles a sugared type iff we are mangling for the debugger.
+  template <class T> void appendSugaredType(Type type,
+                                            const ValueDecl *forDecl) {
+    assert(DWARFMangling &&
+           "sugared types are only legal when mangling for the debugger");
+    auto *BlandTy = cast<T>(type.getPointer())->getSinglyDesugaredType();
+    appendType(BlandTy, forDecl);
+  }
+
   void appendBoundGenericArgs(Type type, bool &isFirstArgList);
 
   /// Append the bound generics arguments for the given declaration context
@@ -228,7 +243,8 @@ class ASTMangler : public Mangler {
 
   /// Append any retroactive conformances.
   void appendRetroactiveConformances(Type type);
-
+  void appendRetroactiveConformances(SubstitutionMap subMap,
+                                     ModuleDecl *fromModule);
   void appendImplFunctionType(SILFunctionType *fn);
 
   void appendContextOf(const ValueDecl *decl);
@@ -242,17 +258,23 @@ class ASTMangler : public Mangler {
 
   void appendAnyGenericType(const GenericTypeDecl *decl);
 
-  void appendFunction(AnyFunctionType *fn, bool isFunctionMangling = false);
-  void appendFunctionType(AnyFunctionType *fn, bool isAutoClosure = false);
+  void appendFunction(AnyFunctionType *fn, bool isFunctionMangling = false,
+                      const ValueDecl *forDecl = nullptr);
+  void appendFunctionType(AnyFunctionType *fn, bool isAutoClosure = false,
+                          const ValueDecl *forDecl = nullptr);
 
-  void appendFunctionSignature(AnyFunctionType *fn);
+  void appendFunctionSignature(AnyFunctionType *fn,
+                               const ValueDecl *forDecl = nullptr);
 
-  void appendFunctionInputType(ArrayRef<AnyFunctionType::Param> params);
-  void appendFunctionResultType(Type resultType);
+  void appendFunctionInputType(ArrayRef<AnyFunctionType::Param> params,
+                               const ValueDecl *forDecl = nullptr);
+  void appendFunctionResultType(Type resultType,
+                                const ValueDecl *forDecl = nullptr);
 
-  void appendTypeList(Type listTy);
+  void appendTypeList(Type listTy, const ValueDecl *forDecl = nullptr);
   void appendTypeListElement(Identifier name, Type elementType,
-                             ParameterTypeFlags flags);
+                             ParameterTypeFlags flags,
+                             const ValueDecl *forDecl = nullptr);
 
   /// Append a generic signature to the mangling.
   ///
@@ -319,6 +341,8 @@ class ASTMangler : public Mangler {
   void appendOpParamForLayoutConstraint(LayoutConstraint Layout);
 
   void appendSymbolicReference(SymbolicReferent referent);
+
+  void appendOpaqueDeclName(const OpaqueTypeDecl *opaqueDecl);
 };
 
 } // end namespace Mangle

include/swift/AST/Attr.def

@@ -82,6 +82,9 @@ TYPE_ATTR(yield_many)
 TYPE_ATTR(thin)
 TYPE_ATTR(thick)
 
+// Generated interface attributes
+TYPE_ATTR(_opaqueReturnTypeOf)
+
 // Schema for DECL_ATTR:
 //
 // - Attribute name.

include/swift/AST/Attr.h

@@ -65,6 +65,14 @@ class TypeAttributes {
 
   // For an opened existential type, the known ID.
   Optional<UUID> OpenedID;
+
+  // For a reference to an opaque return type, the mangled name and argument
+  // index into the generic signature.
+  struct OpaqueReturnTypeRef {
+    StringRef mangledName;
+    unsigned index;
+  };
+  Optional<OpaqueReturnTypeRef> OpaqueReturnTypeOf;
 
   TypeAttributes() {}
 
@@ -82,6 +90,10 @@ class TypeAttributes {
     return AttrLocs[A];
   }
 
+  void setOpaqueReturnTypeOf(StringRef mangling, unsigned index) {
+    OpaqueReturnTypeOf = OpaqueReturnTypeRef{mangling, index};
+  }
+
   void setAttr(TypeAttrKind A, SourceLoc L) {
     assert(!L.isInvalid() && "Cannot clear attribute with this method");
     AttrLocs[A] = L;