Handling callbacks with the LibraryImport source generator

[f2bo]

I'm looking for guidance on how to handle callbacks from native code when using the LibraryImport source generator. I may have missed it but I didn't see this particular usage covered in the documentation.

Whenever the parameters to a callback are not blittable, it becomes necessary to intercept it, marshal the parameters back to their managed representation, and then invoke the managed callback with the appropriate parameters. As far as I can tell, this is not something currently handled by the source generator.

For example, given a hypothetical native API that opens a connection and takes a callback to be notified of connection state changes.

typedef struct ConnectionState
{
    int status_code;
    char* error_message;
} ConnectionState;

typedef void (*ConnectionStateChange)(ConnectionState* state);

ConnectionHandle OpenConnection(ConnectionStateChange callback);

This could be handled by the following managed code.

class ConnectionHandle : SafeHandle
{
   ...
}

public struct ConnectionState
{
    public int status_code { get; set; }
    public string error_message { get; set; }

    internal unsafe struct Native
    {
        public int status_code;
        public sbyte* error_message;
    }
}

delegate void ConnectionStateChange(ConnectionState connectionState);

[LibraryImport("some_lib")]
static partial ConnectionHandle OpenConnection([MarshalUsing(typeof(ConnectionStateChangeMarshaller))] ConnectionStateChange callback);

where the callback parameter of the OpenConnection function is marshalled with the following custom marshaller. By the way, the marshaller below generates warning SYSLIB1057 about not having a Free method that doesn't seem right as there's nothing to be freed in this case. Nevertheless, the code compiles and works as expected when the warning is suppressed.

[CustomMarshaller(typeof(ConnectionStateChange), MarshalMode.ManagedToUnmanagedIn, typeof(ConnectionStateChangeMarshaller))]
internal unsafe struct ConnectionStateChangeMarshaller
{
    private ConnectionStateChange _callback;

    // intercepts the callback with a native representation of the connectionState parameter,
    // converts it to its managed representation, and invokes the original callback
    private unsafe void Interceptor(ConnectionState.Native* connectionState)
    {
        ConnectionState marshaller = new();
        try
        {
            marshaller.FromUnmanaged(connectionState);
            _callback(marshaller.ToManaged());
        }
        finally
        {
            marshaller.Free();
        }
    }

    public void FromManaged(ConnectionStateChange managed) => _callback = managed;

    public delegate* managed<ConnectionState.Native*, void> ToUnmanaged()
    {
        Delegate nativeCallback = Interceptor;
        GCHandle.Alloc(nativeCallback);		// HACK: to keep delegate alive
        return (delegate* managed<ConnectionState.Native*, void>) Marshal.GetFunctionPointerForDelegate(nativeCallback);
    }
}

Note the need to keep a reference to the original _callback so that the interceptor can invoke it once it has unmarshalled the parameters, which basically rules out using a static method for the interceptor and requires using a delegate instead. Moreover, given that the callback can be invoked at any time, the lifetime of the delegate cannot be tied to that of the marshaller. For my quick test, and to prevent the delegate from being garbage collected, I allocated a GCHandle that is basically leaked, but this was only a temporary solution.

Prior to the LibraryImport generator, I used code similar in structure to that generated by the source generator where I also intercepted the callback using a delegate. However, in that case, the code had visibility of all the parameters involved in the call and of its return value, so I could store a reference to the delegate in a member of the ConnectionHandle returned by the call to ensure that the delegate was kept alive for as long the connection was open.

However, it seems a custom marshaller designed for the LibraryImport generator has no context and is not aware of other parameters or of the return value of the call where it is being used. Is there a way to associate the delegate reference to the lifetime of some other object?

[cyraid]

I was able to solve my case with:

  [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
  public delegate void SomeCallback(int a, int b);

and

  [LibraryImport(LIB, EntryPoint = "set_somecallback")]
  [UnmanagedCallConv(CallConvs = new Type[] { typeof(CallConvCdecl) })]
  internal static partial void SetSomeCallback(SomeCallback callback);

[f2bo]

Hi @cyraid.

I'm not sure if I misunderstand, but the parameters to the callback you show are blittable and do not require unmarshalling.

public delegate void SomeCallback(int a, int b);

The scenario I'm interested in is when the callback has parameters that need to be unmarshalled. When calling in the managed to native direction and runtime marshalling is disabled, you typically define a custom marshaller for the non-blittable parameter and the LibraryImport generates a stub that marshals the parameter to its native representation before calling the P/Invoke. Callers do not need to be aware of any of these details and simply invoke the method with the managed parameter. Moreover, the native data types and custom marshaller can remain internal to a wrapper library.

For example:

[LibraryImport("mylib")]
public void SomeMethod([MarshalUsing(typeof(SomeNonBlittableTypeMarshaller))] SomeNonBlittableType arg1);

I would like to know if the source generator has any mechanism for doing the same in the opposite direction, when the callback parameters need to be unmarshalled before invoking the callback provided by the user, for example, for the following delegate.

public delegate void SomeCallback(SomeNonBlittableType arg1);

It would seem that this still needs to be handled manually and that the callback method needs to be defined in terms of native data types and then has to handle the unmarshalling, which not only requires additional knowledge on the part of callers providing the callback, unlike the case of calls in the managed to native direction, but also means that native data types and custom marshallers might need to be made public by the wrapper library. I have workarounds for callbacks that include some form of void* state parameter, which is frequent, but I would still be interested in a "built-in" mechanism.

public void SomeCallback(SomeNonBlittableTypeNative arg1)
{
   // convert the argument the native argument to its managed representation
   SomeNonBlittableType arg = SomeNonBlittableTypeMarshaller.ConvertToManaged(arg1);

   // code that uses the managed value
   ... 
}

Currently, MarshalMode defines UnmanagedToManagedIn, UnmanagedToManagedRef, and UnmanagedToManagedOut modes, but I don't see under what circumstances the source generator outputs code that uses these marshal modes. Can anyone clarify whether this scenario should be handled by LibraryImport or manually?

Tagging subscribers to this area: @dotnet/interop-contrib
See info in area-owners.md if you want to be subscribed.

Issue Details

---

I'm looking for guidance on how to handle callbacks from native code when using the LibraryImport source generator. I may have missed it but I didn't see this particular usage covered in the documentation.

Whenever the parameters to a callback are not blittable, it becomes necessary to intercept it, marshal the parameters back to their managed representation, and then invoke the managed callback with the appropriate parameters. As far as I can tell, this is not something currently handled by the source generator.

For example, given a hypothetical native API that opens a connection and takes a callback to be notified of connection state changes.

typedef struct ConnectionState
{
    int status_code;
    char* error_message;
} ConnectionState;

typedef void (*ConnectionStateChange)(ConnectionState* state);

ConnectionHandle OpenConnection(ConnectionStateChange callback);

This could be handled by the following managed code.

class ConnectionHandle : SafeHandle
{
   ...
}

public struct ConnectionState
{
    public int status_code { get; set; }
    public string error_message { get; set; }

    internal unsafe struct Native
    {
        public int status_code;
        public sbyte* error_message;
    }
}

delegate void ConnectionStateChange(ConnectionState connectionState);

[LibraryImport("some_lib")]
static partial ConnectionHandle OpenConnection([MarshalUsing(typeof(ConnectionStateChangeMarshaller))] ConnectionStateChange callback);

where the callback parameter of the OpenConnection function is marshalled with the following custom marshaller. By the way, the marshaller below generates warning SYSLIB1057 about not having a Free method that doesn't seem right as there's nothing to be freed in this case. Nevertheless, the code compiles and works as expected when the warning is suppressed.

[CustomMarshaller(typeof(ConnectionStateChange), MarshalMode.ManagedToUnmanagedIn, typeof(ConnectionStateChangeMarshaller))]
internal unsafe struct ConnectionStateChangeMarshaller
{
    private ConnectionStateChange _callback;

    // intercepts the callback with a native representation of the connectionState parameter,
    // converts it to its managed representation, and invokes the original callback
    private unsafe void Interceptor(ConnectionState.Native* connectionState)
    {
        ConnectionState marshaller = new();
        try
        {
            marshaller.FromUnmanaged(connectionState);
            _callback(marshaller.ToManaged());
        }
        finally
        {
            marshaller.Free();
        }
    }

    public void FromManaged(ConnectionStateChange managed) => _callback = managed;

    public delegate* managed<ConnectionState.Native*, void> ToUnmanaged()
    {
        Delegate nativeCallback = Interceptor;
        GCHandle.Alloc(nativeCallback);		// HACK: to keep delegate alive
        return (delegate* managed<ConnectionState.Native*, void>) Marshal.GetFunctionPointerForDelegate(nativeCallback);
    }
}

Note the need to keep a reference to the original _callback so that the interceptor can invoke it once it has unmarshalled the parameters, which basically rules out using a static method for the interceptor and requires using a delegate instead. Moreover, given that the callback can be invoked at any time, the lifetime of the delegate cannot be tied to that of the marshaller. For my quick test, and to prevent the delegate from being garbage collected, I allocated a GCHandle that is basically leaked, but this was only a temporary solution.

Prior to the LibraryImport generator, I used code similar in structure to that generated by the source generator where I also intercepted the callback using a delegate. However, in that case, the code had visibility of all the parameters involved in the call and of its return value, so I could store a reference to the delegate in a member of the ConnectionHandle returned by the call to ensure that the delegate was kept alive for as long the connection was open.

However, it seems a custom marshaller designed for the LibraryImport generator has no context and is not aware of other parameters or of the return value of the call where it is being used. Is there a way to associate the delegate reference to the lifetime of some other object?

Author:	f2bo
Assignees:	-
Labels:	area-System.Runtime.InteropServices, untriaged
Milestone:	-

[AaronRobinsonMSFT]

By the way, the marshaller below generates warning SYSLIB1057 about not having a Free method that doesn't seem right as there's nothing to be freed in this case. Nevertheless, the code compiles and works as expected when the warning is suppressed.

Yep. This is by-design. Interop is complicated enough that we are simply enforcing patterns so they are consistent because it is most common to need a free. It is much harder to determine if it is needed so simply forcing the pattern ensures there won't be a missing call.

I'm looking for guidance on how to handle callbacks from native code when using the LibraryImport source generator. I may have missed it but I didn't see this particular usage covered in the documentation.

This isn't supported yet. It is currently tracked in #63590.

[AaronRobinsonMSFT]

I'm looking for guidance on how to handle callbacks from native code when using the LibraryImport source generator. I may have missed it but I didn't see this particular usage covered in the documentation.

This isn't supported yet. It is currently tracked in #63590.

I'm going to close this since it is a duplicate. If you think there is something unique compared to #63590 please let us know. If the example here has something that is missing please add it there.

[f2bo]

@AaronRobinsonMSFT The issue you mention above does not appear to be the same, as stated by the thread's author here.

[jkoritzinsky]

I think this issue is more of a duplicate of #79786 as that focuses more on the Reverse P/Invoke experience.

[AaronRobinsonMSFT]

@f2bo You're absolutely right. The issue I meant to tag was #79786.