Some Slang API additions (#1195)

* Some Slang API additions

These are additions to the public Slang API that came up while I was trying to write an example to demonstrate GPU printing. The additions aren't strictly necessary for the example, but I found these to be missing services when writing the code the way I wanted to.

The main public changes are:

* There is a new distinct `IEntryPoint` interface which inherit from `IComponentType` (much like `IModule` before). For now this doesn't expose any new functions on top of `IComponentType`, but I expect it to do so eventually.

* It is now possible to get the `IModule` for a specific translation unit in a compile request with `spCompileRequest_getModule`. Even for a compile request that had only one translation unit this is *not* the same object as gets returned by `spCompileRequest_getProgram`. The latter should probably be called `*_getLinkedProgram` because it returns a composite component type that links the module with everything it `import`s.

* An `IModule` can look up entry points declared in the module. Eventually a module should support looking up most of the declarations in the module (e.g., types) by name, but entry points are an obvious case.

* A new `link()` operation is added to `IComponentType`. It is possible to have component types that have unsatisfied dependencies, such that trying to generate kernel code from them will fail. The `link()` operation tries to produce a new composite component type that combines a component with its dependencies, to enable code generation. The implementation of end-to-end compilation was using a function like this internally, but it hadn't been exposed to the API.

Notes on the implementation:

* The list of entry points declared in a given translation unit has moved from `TranslationUnitRequest` to the `Module` inside of it.

* `EntryPoint` now has to do a song and dance much like `Module` to both inherit from `ComponentType` and support the `IEntryPoint` interface.

* The `Session* m_session` member in `Linkage` (in terms of public API, this is the `slang::ISession` holding a pointer to the `slang::IGlobalSession`) has been changed to a `RefPtr`. Without this change an application can't just hold onto a `ComPtr<slang::ISession>`; they also need to retain the `IGlobalSession` or things will crash. The new behavior seems more correct, but I worry that it might introduce a leak.

* The `asInternal` operation for `IComponentType` had to be updated to not just perform a cast. A type like `Module` has two `IComponentType` sub-objects, and only one of these is at the same address as the `ComponentType` base.

* Similarly, the `Module::getInterface` logic was changed to fall back to `Super::getInterface` for all the cases other than `IID_IModule`, so that it would be guaranteed to return the `IComponentType` at the same address as `ComponentType` in response to a `queryInterface`.

* Fixes for memory retain cycles

As part of the earlier change, I made the `Linkage` type hold a `RefPtr` to the `Session`.
The motivation there is it lets a user hang onto just a `slang::ISession` without having to also retain the `slang::IGlobalSession` for no immediately apparent reason.

There are two problems that this surfaced, one pre-existing and one new.

The new problem was that `Session` already held a `RefPtr<Linkage> m_builtinLinkage` for the linkage that holds the stdlib code.
I solved that problem by splitting the parent pointer in `Linkage` into two pointers: a raw pointer that is used to actually locate the parent session, and a ref-counted one that can be used to *optionally* retain the parent session.
The builtin linkage is then set up to explicitly not retain its parent, thus breaking the cycle.

The second problem was a pre-existing one, where every `ComponentType` was holding a retained pointer to its parent `Linkage`, but in turn the `Linkage` was holding retained pointers to many `ComponentTypes` (and subclasses thereof).
For this case I used the more expedient fix of making the parent pointer into a raw pointer, and figuring that it is a reasonable rule to expect user to retain the `Linkage` (aka `slang::ISession`) that owns a component type if they want to be able to use the component type.

I might need/want to investigate a better fix for the latter issue, but for now this seems to clean up the issues I was seeing in the tests. Fingers crossed.

1 files changed, 98 insertions, 10 deletions

diff --git a/source/slang/slang.cpp b/source/slang/slang.cpp
index fce90d612..bfc77b2e3 100644
--- a/source/slang/slang.cpp
+++ b/source/slang/slang.cpp
@@ -38,13 +38,15 @@
 namespace Slang {
 
 // Allocate static const storage for the various interface IDs that the Slang API needs to expose
-static const Guid IID_ISlangUnknown = SLANG_UUID_ISlangUnknown;
-static const Guid IID_ISlangBlob    = SLANG_UUID_ISlangBlob;
-static const Guid IID_ISession = SLANG_UUID_ISession;
-static const Guid IID_IGlobalSession = SLANG_UUID_IGlobalSession;
-static const Guid IID_IModule = SLANG_UUID_IModule;
+static const Guid IID_IComponentType    = SLANG_UUID_IComponentType;
+static const Guid IID_IEntryPoint       = SLANG_UUID_IEntryPoint;
+static const Guid IID_IGlobalSession    = SLANG_UUID_IGlobalSession;
+static const Guid IID_IModule           = SLANG_UUID_IModule;
+static const Guid IID_ISession          = SLANG_UUID_ISession;
+static const Guid IID_ISlangBlob        = SLANG_UUID_ISlangBlob;
+static const Guid IID_ISlangUnknown     = SLANG_UUID_ISlangUnknown;
 
-Session::Session()
+void Session::init()
 {
     ::memset(m_downstreamCompilerLocators, 0, sizeof(m_downstreamCompilerLocators));
     DownstreamCompilerUtil::setDefaultLocators(m_downstreamCompilerLocators);
@@ -77,6 +79,16 @@ Session::Session()
 
     m_builtinLinkage = new Linkage(this);
 
+    // Because the `Session` retains the builtin `Linkage`,
+    // we need to make sure that the parent pointer inside
+    // `Linkage` doesn't create a retain cycle.
+    //
+    // This operation ensures that the parent pointer will
+    // just be a raw pointer, so that the builtin linkage
+    // doesn't keep the parent session alive.
+    //
+    m_builtinLinkage->_stopRetainingParentSession();
+
     // Initialize representations of some very basic types:
     initializeTypes();
 
@@ -437,6 +449,7 @@ Profile getEffectiveProfile(EntryPoint* entryPoint, TargetRequest* target)
 
 Linkage::Linkage(Session* session)
     : m_session(session)
+    , m_retainedSession(session)
     , m_sourceManager(&m_defaultSourceManager)
 {
     getNamePool()->setRootNamePool(session->getRootNamePool());
@@ -1704,9 +1717,9 @@ Module::Module(Linkage* linkage)
 
 ISlangUnknown* Module::getInterface(const Guid& guid)
 {
-    if(guid == IID_ISlangUnknown || guid == IID_IModule)
+    if(guid == IID_IModule)
         return asExternal(this);
-    return nullptr;
+    return Super::getInterface(guid);
 }
 
 void Module::addModuleDependency(Module* module)
@@ -1725,14 +1738,51 @@ void Module::setModuleDecl(ModuleDecl* moduleDecl)
     m_moduleDecl = moduleDecl;
 }
 
-// ComponentType
+RefPtr<EntryPoint> Module::findEntryPointByName(UnownedStringSlice const& name)
+{
+    // TODO: We should consider having this function be expanded to be able
+    // to look up and validate possible entry-point functions in teh module
+    // even if they were not marked with `[shader(...)]` in the source code.
+    //
+    // With such a change the function would probably need to accept a stage
+    // to use and a sink to write validation errors to.
+
+    for(auto entryPoint : m_entryPoints)
+    {
+        if(entryPoint->getName()->text.getUnownedSlice() == name)
+            return entryPoint;
+    }
+
+    return nullptr;
+}
+
+void Module::_addEntryPoint(EntryPoint* entryPoint)
+{
+    m_entryPoints.add(entryPoint);
+}
 
-static const Guid IID_IComponentType = SLANG_UUID_IComponentType;
+
+// ComponentType
 
 ComponentType::ComponentType(Linkage* linkage)
     : m_linkage(linkage)
 {}
 
+ComponentType* asInternal(slang::IComponentType* inComponentType)
+{
+    // Note: we use a `queryInterface` here instead of just a `static_cast`
+    // to ensure that the `IComponentType` we get is the preferred/canonical
+    // one, which shares its address with the `ComponentType`.
+    //
+    // TODO: An alternative choice here would be to have a "magic" IID that
+    // we pass into `queryInterface` that returns the `ComponentType` directly
+    // (without even `addRef`-ing it).
+    //
+    ComPtr<slang::IComponentType> componentType;
+    inComponentType->queryInterface(IID_IComponentType, (void**) componentType.writeRef());
+    return static_cast<ComponentType*>(componentType.get());
+}
+
 ISlangUnknown* ComponentType::getInterface(Guid const& guid)
 {
     if(guid == IID_ISlangUnknown
@@ -1873,6 +1923,28 @@ SLANG_NO_THROW SlangResult SLANG_MCALL ComponentType::specialize(
     return SLANG_OK;
 }
 
+RefPtr<ComponentType> fillRequirements(
+    ComponentType* inComponentType);
+
+SLANG_NO_THROW SlangResult SLANG_MCALL ComponentType::link(
+    slang::IComponentType**         outLinkedComponentType,
+    ISlangBlob**                    outDiagnostics)
+{
+    // TODO: It should be possible for `fillRequirements` to fail,
+    // in cases where we have a dependency that can't be automatically
+    // resolved.
+    //
+    SLANG_UNUSED(outDiagnostics);
+
+    auto linked = fillRequirements(this);
+    if(!linked)
+        return SLANG_FAIL;
+
+    *outLinkedComponentType = ComPtr<slang::IComponentType>(linked).detach();
+    return SLANG_OK;
+}
+
+
     /// Visitor used by `ComponentType::enumerateModules`
 struct EnumerateModulesVisitor : ComponentTypeVisitor
 {
@@ -2488,6 +2560,7 @@ Session::~Session()
 SLANG_API SlangSession* spCreateSession(const char*)
 {
     Slang::RefPtr<Slang::Session> session(new Slang::Session());
+    session->init();
     // Will be returned with a refcount of 1
     return asExternal(session.detach());
 }
@@ -2500,6 +2573,7 @@ SLANG_API SlangResult slang_createGlobalSession(
         return SLANG_E_NOT_IMPLEMENTED;
 
     Slang::Session* globalSession = new Slang::Session();
+    globalSession->init();
     Slang::ComPtr<slang::IGlobalSession> result(Slang::asExternal(globalSession));
     *outGlobalSession = result.detach();
     return SLANG_OK;
@@ -3487,6 +3561,20 @@ SLANG_API SlangResult spCompileRequest_getProgram(
     return SLANG_OK;
 }
 
+SLANG_API SlangResult spCompileRequest_getModule(
+    SlangCompileRequest*    request,
+    SlangInt                translationUnitIndex,
+    slang::IModule**        outModule)
+{
+    if( !request ) return SLANG_ERROR_INVALID_PARAMETER;
+    auto req = Slang::asInternal(request);
+
+    auto module = req->getFrontEndReq()->getTranslationUnit(translationUnitIndex)->getModule();
+
+    *outModule = Slang::ComPtr<slang::IModule>(module).detach();
+    return SLANG_OK;
+}
+
 SLANG_API SlangResult spCompileRequest_getEntryPoint(
     SlangCompileRequest*    request,
     SlangInt                entryPointIndex,