[API Proposal]: Provide an API to get the native module handle of the native process entry-point module

[jkoritzinsky]

Background and motivation

As mentioned in #7267, there is a strong desire for enabling using the "__Internal" name in a DllImport to point to methods in the hosting executable module of the process in both CoreCLR and Mono. Mono has had this support for many years, but CoreCLR doesn't have built-in support, and we don't have a desire to provide built-in support for this "hidden" name.

However, we understand the need for a way to resolve this name to the correct handle. We propose adding an API that gets the native module handle of the entry-point module.

API Proposal

namespace System.Runtime.InteropServices
{
     public static class NativeLibrary
     {
          public static IntPtr GetMainProgramHandle();
     }
}

Alternatively, we considered allowing null as a parameter to NativeLibrary.Load(string) to match how the implementation on non-Windows is dlopen(NULL). The interop team decided that design was an abstraction leak and undesirable since the Windows implementation doesn't follow the same model. Additionally, the other NativeLibrary.Load overloads have additional behaviors and aren't thin wrappers, which makes the null option less desirable.

API Usage

NativeLibrary.SetDllImportResolver(assembly, (name, _, paths) =>
{
     if (name == "__Internal")
     {
          return NativeLibrary.GetMainProgramHandle();
     }
     return IntPtr.Zero;
});

Risks

None

[jkoritzinsky]

cc: @AaronRobinsonMSFT @elinor-fung

[AaronRobinsonMSFT]

/cc @marek-safar @lambdageek

[GrabYourPitchforks]

Implementation question: how does this method affect the handle's reference count?

[jkoritzinsky]

This method will cache the handle after it's been called once, so it will only increase the refcount of the handle by 1. On Windows, we'll use GetModuleHandle which doesn't increase the refcount at all.

Since the module is the process's entry-point module, we don't need to worry about releasing the handle since it is valid until process tear-down (which will release the handle anyway).

[am11]

Alternatively, we considered allowing null as a parameter to NativeLibrary.Load(string) to match how the implementation on non-Windows is dlopen(NULL).

Another approach is to return (IntPtr)-1 which works on Windows and Unix alike.

runtime/src/coreclr/System.Private.CoreLib/src/System/Runtime/InteropServices/Marshal.CoreCLR.cs

Line 250 in 57bfe47

return (IntPtr)(-1);

[lambdageek]

Alternatively, we considered allowing null as a parameter to NativeLibrary.Load(string) to match how the implementation on non-Windows is dlopen(NULL).

nit: this doesn't work on every unix. In particular on Android dlopen (NULL) doesn't work, but dlsym (RTLD_DEFAULT) does.

[bartonjs]

Looks good as proposed.

namespace System.Runtime.InteropServices
{
     public static class NativeLibrary
     {
          public static IntPtr GetEntryPointModuleHandle();
     }
}

[jkotas]

GetEntryPointModuleHandle

Module is very Windows-specific name. There is nothing called Module in the existing NativeLibrary APIs. Would GetMainProgramHandle be a better cross-platform name?

I assume that the non-Windows implementation is going to return dlopen(NULL). Is that right? Note that dlopen(NULL) is a pseudo handle that does the lookup in all libraries loaded at startup, it does not correspond to a single file or module.

[jkoritzinsky]

I didn't want to use GetMainProgramHandle since that sounds like a process handle, not a library handle that's usable with dlsym

[jkoritzinsky]

And since the entrypoint of the program isn't a shared library, the name GetMainProgramLibraryHandle felt wrong as well.

[AaronRobinsonMSFT]

Would GetMainProgramHandle be a better cross-platform name?

I don't have a strong preference here. "GetMainProgramHandle" or "GetEntryProgramHandle" are fine with me.

Note that dlopen(NULL) is a pseudo handle that does the lookup in all libraries loaded at startup, it does not correspond to a single file or module.

I was not aware of that behavior. The latest doc on dlopen makes this clear. Do we want this behavior or an actual handle to the main program?

I didn't want to use GetMainProgramHandle since that sounds like a process handle, not a library handle that's usable with dlsym

That is fair but isn't a NativeLibrary scenario what we are attempting to support. After all, I believe the point of this API is to enable "__Internal" semantics. This would imply the primary use case of the returned value is for calls to NativeLibrary.GetExport(), no?

[jkoritzinsky]

I didn't want to use GetMainProgramHandle since that sounds like a process handle, not a library handle that's usable with dlsym

That is fair but isn't a NativeLibrary scenario what we are attempting to support. After all, I believe the point of this API is to enable "__Internal" semantics. This would imply the primary use case of the returned value is for calls to NativeLibrary.GetExport(), no?

Yes, we are trying to support a NativeLibrary scenario. My argument is that the new naming proposals imply a different scenario (process handle) than the scenario we are actually supporting and may cause confusion.

[AaronRobinsonMSFT]

imply a different scenario (process handle) than the scenario we are actually supporting and may cause confusion.

Understood. I don't see this as a large concern given we can document the usage clearly and this is a niche scenario so minor confusion is okay and easily remedied. Not shutting down the conversation about renaming simply saying I don't think that will be that hard of a problem to address, but I do think that @jkotas's argument is fair - "Module" is a Windows-centric term.

Perhaps @bartonjs or @lambdageek have thoughts on naming alternatives?

[lambdageek]

Perhaps @bartonjs or @lambdageek have thoughts on naming alternatives?

(I'm not great at naming) The man pages from Apple and Linux both call the value passed to dlsym a "handle" and they mention that there are some "pseudo-handles" and in particular RTLD_DEFAULT is the "default search order pseudo handle". So...

namespace System.Runtime.InteropServices
{
     public static class NativeLibrary
     {
          public static IntPtr GetDefaultSearchOrderPseudoHandle();
     }
}

[bartonjs]

Module is very Windows-specific name.

During the API review there was theorization of a companion API like IntPtr GetModuleHandle(System.Reflection.Module). Because of Assembly.Modules/Assembly.ManifestModule/etc I think that "Module" is also a .NET term. (It has much more affinity to .NET than to Windows for me, FWIW)

[jkotas]

Yes, Module is also .NET metadata term. I do not think we would want to introduce API like IntPtr GetModuleHandle(System.Reflection.Module) where the returned IntPtr would be the OS library handle. The metadata module is backed by Windows OS module only on CoreCLR, only in some cases, and it changed over time. This API would be leaking internal implementation details for no good reason.

[terrajobst]

• It was requested to rename the API from GetEntryPointModuleHandle() to GetMainProgramHandle().
• Looks good as proposed

namespace System.Runtime.InteropServices
{
     public static class NativeLibrary
     {
          public static IntPtr GetMainProgramHandle();
     }
}