Full C# API for delegate that handles initializers

csharp/src/Microsoft.ML.OnnxRuntime/CompileModel.shared.cs

@@ -175,15 +175,24 @@ public void SetOutputModelWriteBufferDelegate(WriteBufferDelegate writeBufferDel
                     _writeBufferDelegateState.GetConnectorHandleAsPointer()));
         }
 
-        // TODO: Add return value and other parameters
         /// <summary>
         /// Delegate called by ORT for every initializer when generating the compiled model.
         /// The delegate allows the user to determine whether the initializer should be stored within the compiled
         /// model or externally in a file. If the delegate chooses to store an initializer externally, the delegate
         /// implementation is responsible for writing the initializer data to a file.
         /// </summary>
         /// <param name="initializerName">The initializer's name.</param>
-        public delegate void HandleInitializerDelegate(string initializerName);
+        /// <param name="initializerValue">The readonly OrtValue instance containing the data, type, and
+        /// shape of the initializer.</param>
+        /// <param name="optionalExternalInfo">May be null. If the initializer is originally stored externally,
+        /// this contains the file path, file offset, and data size. Otherwise, this is null.</param>
+        /// <returns>A new OrtExternalInitializerInfo indicating the new location of the initializer.
+        /// Returns null if the initializer should be stored within the generated compiled model.</returns>
+        /// <remarks>The return value may be null.</remarks>
+        public delegate OrtExternalInitializerInfo HandleInitializerDelegate(
+            string initializerName,
+            IReadOnlyOrtValue initializerValue,
+            IReadOnlyExternalInitializerInfo optionalExternalInfo);
 
         /// <summary>
         /// Sets a delegate that is called by ORT for every initializer when generating the compiled model.
@@ -280,8 +289,45 @@ public static IntPtr HandleInitializerDelegateWrapper(
                 {
 
                     HandleInitializerConnector connector = (HandleInitializerConnector)GCHandle.FromIntPtr(state).Target;
-                    var utf8InitializerName = NativeOnnxValueHelper.StringFromNativeUtf8(initializerName);
-                    connector._csharpDelegate(utf8InitializerName);
+                    string utf8InitializerName = NativeOnnxValueHelper.StringFromNativeUtf8(initializerName);
+                    IReadOnlyOrtValue readOnlyInitializerValue = new OrtValue(initializerValue, owned: false);
+                    IReadOnlyExternalInitializerInfo readOnlyExternalInfo = null;
+
+                    if (externalInfo != IntPtr.Zero)
+                    {
+                        readOnlyExternalInfo = new OrtExternalInitializerInfo(externalInfo, ownsHandle: false);
+                    }
+
+                    // Call user's delegate, which may return the new location of the initializer.
+                    OrtExternalInitializerInfo optionalNewExternalInfo = connector._csharpDelegate(
+                        utf8InitializerName, readOnlyInitializerValue, readOnlyExternalInfo);
+
+                    if (optionalNewExternalInfo != null)
+                    {
+                        // Delegate returned info about a new location for the initializer.
+                        // Can't guarantee that the new external info returned by user's delegate is not referenced
+                        // by other C# code. ORT expects to own the new external info, so create a copy here and
+                        // give it to ORT.
+                        string newFilePath = optionalNewExternalInfo.GetFilePath();
+                        byte[] newFilePathBytes = NativeOnnxValueHelper.GetPlatformSerializedString(newFilePath);
+
+                        IntPtr status = NativeMethods.OrtCreateExternalInitializerInfo(
+                            newFilePathBytes,
+                            optionalNewExternalInfo.GetFileOffset(),
+                            (UIntPtr)optionalNewExternalInfo.GetByteSize(),
+                            out newExternalInfo);
+
+                        if (status != IntPtr.Zero)
+                        {
+                            return status;
+                        }
+                    }
+                    else
+                    {
+                        // User's delegate did not return a new location for the initializer. ORT will store initializer
+                        // within the generated compiled model.
+                        newExternalInfo = IntPtr.Zero;
+                    }
                 }
                 catch (Exception ex)
                 {

csharp/src/Microsoft.ML.OnnxRuntime/NativeOnnxValueHelper.shared.cs

@@ -150,6 +150,45 @@ internal static byte[] GetPlatformSerializedString(string str)
             else
                 return StringToZeroTerminatedUtf8(str);
         }
+
+        /// <summary>
+        /// Converts a null-terminated path string that is pointed to by the given IntPtr handle into
+        /// a C# UTF-16 string.
+        /// </summary>
+        /// <remarks>A path string on Windows is utf-16, but utf-8 on other operating systems.</remarks>
+        /// <param name="strPtr"></param>
+        /// <returns></returns>
+        internal static string StringFromNativePathString(IntPtr strPtr)
+        {
+            if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+            {
+                if (strPtr == IntPtr.Zero)
+                {
+                    return string.Empty;
+                }
+
+                // Get length of utf16 string by checking for two 0 bytes in a row.
+                int length = 0;
+                while (Marshal.ReadInt16(strPtr, length * 2) != 0)
+                {
+                    length += 1;
+                }
+
+                if (length == 0)
+                {
+                    return string.Empty;
+                }
+
+                unsafe
+                {
+                    return System.Text.Encoding.Unicode.GetString((byte*)strPtr, length * 2);
+                }
+            }
+            else
+            {
+                return StringFromNativeUtf8(strPtr);
+            }
+        }
     }
 
     // Guards an array of disposable objects on stack and disposes them in reverse order

csharp/src/Microsoft.ML.OnnxRuntime/OrtExternalInitializerInfo.shared.cs

@@ -11,10 +11,10 @@ namespace Microsoft.ML.OnnxRuntime
     /// Class to that stores information about the file location where an "external" initializer is stored.
     /// </summary>
     /// <see cref="OrtModelCompilationOptions.HandleInitializerDelegate"/>
-    public class OrtExternalInitializerInfo : SafeHandle
+    public class OrtExternalInitializerInfo : SafeHandle, IReadOnlyExternalInitializerInfo
     {
         // Set to true when constructed with an externally managed constant handle owned by ORT.
-        private readonly bool _isConst;
+        private readonly bool _ownsHandle = true;
 
         /// <summary>
         /// Create a new OrtExternalInitializerInfo instance. 
@@ -28,26 +28,25 @@ public OrtExternalInitializerInfo(string filePath, long fileOffset, long byteSiz
             var platformFilePath = NativeOnnxValueHelper.GetPlatformSerializedString(filePath);
             NativeApiStatus.VerifySuccess(
                 NativeMethods.OrtCreateExternalInitializerInfo(platformFilePath, fileOffset, (UIntPtr)byteSize, out handle));
-            _isConst = false;
+            _ownsHandle = true;
         }
 
         /// <summary>
         /// Create a new OrtExternalInitializerInfo instance from an existing native OrtExternalInitializerInfo handle.
         /// </summary>
         /// <param name="constHandle">Native OrtExternalInitializerInfo handle.</param>
-        /// <remarks>
-        /// The instance is read-only.
-        /// </remarks>
+        /// <param name="ownsHandle">True if the OrtExternalInitializerInfo instance owns the native handle.
+        /// Defaults to false.</param>
         /// <exception cref="InvalidOperationException"></exception>
-        internal OrtExternalInitializerInfo(IntPtr constHandle)
-            : base(IntPtr.Zero, ownsHandle: false)
+        internal OrtExternalInitializerInfo(IntPtr constHandle, bool ownsHandle = false)
+            : base(IntPtr.Zero, ownsHandle)
         {
             if (constHandle == IntPtr.Zero)
             {
                 throw new InvalidOperationException($"{nameof(OrtExternalInitializerInfo)}: Invalid instance.");
             }
             SetHandle(constHandle);
-            _isConst = true;
+            _ownsHandle = ownsHandle;
         }
 
         /// <summary>
@@ -65,7 +64,7 @@ public string GetFilePath()
                 return string.Empty;
             }
 
-            return NativeOnnxValueHelper.StringFromNativeUtf8(filePathPtr);
+            return NativeOnnxValueHelper.StringFromNativePathString(filePathPtr);
         }
 
         /// <summary>
@@ -98,7 +97,7 @@ public long GetByteSize()
         /// <returns>true on success and false on error.</returns>
         protected override bool ReleaseHandle()
         {
-            if (_isConst)
+            if (!_ownsHandle)
             {
                 // Return false to indicate an error.
                 // ReleaseHandle() should not be called on a const handle that this class does not own.
@@ -110,4 +109,31 @@ protected override bool ReleaseHandle()
             return true;
         }
     }
+
+    /// <summary>
+    /// Interface for all readonly methods implemented by OrtExternalInitializerInfo.
+    /// </summary>
+    public interface IReadOnlyExternalInitializerInfo
+    {
+        /// <summary>
+        /// Get the file path to the file that store's the initializer's data.
+        /// </summary>
+        /// <remarks>
+        /// The path is relative to the filesystem directory where the ONNX model was stored.
+        /// </remarks>
+        /// <returns>The file path.</returns>
+        string GetFilePath();
+
+        /// <summary>
+        /// Get the byte offset within the file where the initializer's data is stored.
+        /// </summary>
+        /// <returns>The file offset location.</returns>
+        long GetFileOffset();
+
+        /// <summary>
+        /// Get the size in bytes of the initializer's data within the file.
+        /// </summary>
+        /// <returns>The size in bytes of the initializer data.</returns>
+        long GetByteSize();
+    }
 }