LoadImage's returned HANDLE must be released in ONE of THREE ways

[AArnott]

LoadImageW/LoadImageA in the metadata currently return a HANDLE type, which would be closed with CloseHandle.
However the docs state that one of DeleteObject, DeleteCursor or DeleteIcon should be used to release the handle, and only if the LR_SHARED flag was not passed in. The metadata returning HANDLE means CloseHandle will always be called, which is the wrong method and the wrong conditions.

How can we model this in the metadata?

[marler8997]

Create a "LoadImageHandle" type with an attribute like "FreeFuncCandidates"?

[riverar]

This seems to be a problem specific to C# bindings and its use of SafeHandle. I don't think everyone else should shoulder the burden of a new type here.

Perhaps on the bindings side, functions with HANDLE return types should be generated with a non-SafeHandle overload?

[AArnott]

How is this C#-specific? Any projection that wants to help the user clean up resources (I think Rust is among these) will need to know how to do so. SafeHandle is just how .NET encapsulates this functionality.

[kennykerr]

Rust doesn't make use of RAIIFree at all. It would have to be absolutely perfect in terms of coverage and attribution for developers to feel confident in its use and even then its not necessarily applicable to all languages. But its an attribute, so it can be easily ignored. I would rather not introduce even more pseudo handle types as it muddies up the projection for languages that don't care about such things. If you must add more metadata for this, please just use an attribute that code generators can ignore if so desired.

[riverar]

How is this C#-specific? Any projection that wants to help the user clean up resources (I think Rust is among these) will need to know how to do so. SafeHandle is just how .NET encapsulates this functionality.

My concern was regarding the suggestion to mutate the API signature to accommodate SafeHandle. You are right, the overall request is not C# specific, apologies for any confusion introduced.

We need to consider projections that may not want to do anything here.

I'm not pushing back on the idea of annotating these APIs though. That will be great for bindings that wish to exert more control over object lifetime.

[mikebattista]

Perhaps on the bindings side, functions with HANDLE return types should be generated with a non-SafeHandle overload?

Actually LoadImage already has this HANDLE-returning overload so I believe we're already doing this in C#/Win32. @AArnott is this correct?

[mikebattista]

So discussing with Andrew, he pointed out that we do always have an overload that matches the metadata, but HANDLE is wrong for this API since it implies CloseHandle which is wrong in all cases here. It should be changed to IntPtr at least to fix the crash that happens on disposal currently.

We could try to model this specific case in attributes, but it's a nontrivial conditional and I'd rather not go down that path for this one API. I'll tag this as a "special case" for tracking purposes but for now I think the change here is to change the return type in the metadata from HANDLE to IntPtr and expect developers to follow the documentation for the API.

[riverar]

but HANDLE is wrong for this API since it implies CloseHandle which is wrong in all cases here.

I'm not aware of any Win32 guarantees or requirements that HANDLE objects be freeable via CloseHandle. So it's not clear why this is being viewed as wrong and not just a faulty assumption on the part of C#/Win32.

[kennykerr]

This comes from the win32 metadata. But yes, I agree that this isn't terribly reliable as HANDLE is used for all kinds of things that don't map to CloseHandle. That's why Rust ignores the RAIIFree attribute.

[marler8997]

I would have expected the RAIIFree attribute to be applied to return types and out parameters rather than the types themselves.

[mikebattista]

Yes it's encoded in the metadata as Kenny pointed out with the RAIIFree attribute. We have more specific HANDLE structs for scenarios that require a more domain-specific Close/Free function.

In this case with LoadImage, you need to use 1 of 3 different "Free" functions based on the combination of parameters supplied, and CloseHandle isn't one of them.