Refactor .NET bindings for OpenDAL

- Removed OpenDALMethods.cs as it is no longer needed.
- Updated OpenDALResult to simplify error handling and introduced OpenDALIntPtrResult and OpenDALByteBufferResult for better type safety.
- Refactored Operator class to utilize new result structures and improved error handling.
- Enhanced async methods to properly handle results and errors.
- Added ByteBuffer struct for FFI-safe byte buffer representation.
- Updated error handling in Rust code to align with new result structures.
- Improved utility functions for memory management and string conversion.
- Updated README to reflect changes in error semantics and usage.

Author: Fatorin

bindings/dotnet/DotOpenDAL.Tests/MemoryOperatorTest.cs

@@ -21,6 +21,36 @@ namespace DotOpenDAL.Tests;
 
 public class MemoryOperatorTest
 {
+    [Fact]
+    public async Task ReadWrite_DisposeRace_DoesNotCrashProcess()
+    {
+        var op = new Operator("memory");
+        byte[] content = [0x10, 0x20, 0x30, 0x40];
+        op.Write("seed", content);
+
+        var workers = Enumerable.Range(0, 64).Select(async i =>
+        {
+            var path = $"race-{i % 8}";
+
+            try
+            {
+                op.Write(path, content);
+                _ = op.Read(path);
+            }
+            catch (ObjectDisposedException)
+            {
+            }
+            catch (OpenDALException)
+            {
+            }
+
+            await Task.Yield();
+        });
+
+        var dispose = Task.Run(op.Dispose);
+        await Task.WhenAll(workers.Append(dispose));
+    }
+
     [Fact]
     public void ReadWrite_Utf8Bytes_RoundTripsSuccessfully()
     {
@@ -182,4 +212,49 @@ public async Task ReadWriteAsync_CancelAfterDispatch_DoesNotBreakSubsequentOpera
         var stableRead = await op.ReadAsync("seed");
         Assert.Equal("seed-content", System.Text.Encoding.UTF8.GetString(stableRead));
     }
+
+    [Fact]
+    public async Task ReadWriteAsync_DisposeRace_DoesNotCrashProcess()
+    {
+        var op = new Operator("memory");
+        byte[] content = [1, 2, 3, 4, 5, 6, 7, 8];
+        await op.WriteAsync("seed-async", content);
+
+        var workers = Enumerable.Range(0, 64).Select(async i =>
+        {
+            var path = $"race-async-{i % 8}";
+
+            try
+            {
+                await op.WriteAsync(path, content);
+                _ = await op.ReadAsync(path);
+            }
+            catch (ObjectDisposedException)
+            {
+            }
+            catch (OpenDALException)
+            {
+            }
+        });
+
+        var dispose = Task.Run(op.Dispose);
+        await Task.WhenAll(workers.Append(dispose));
+    }
+
+    [Fact]
+    public async Task ReadAsync_PathNotExists_RepeatedErrors_DoNotPoisonSubsequentCalls()
+    {
+        using var op = new Operator("memory");
+
+        for (var i = 0; i < 32; i++)
+        {
+            var ex = await Assert.ThrowsAsync<OpenDALException>(() => op.ReadAsync($"missing-{i}"));
+            Assert.Equal(ErrorCode.NotFound, ex.Code);
+        }
+
+        var content = System.Text.Encoding.UTF8.GetBytes("healthy");
+        await op.WriteAsync("healthy", content);
+        var read = await op.ReadAsync("healthy");
+        Assert.Equal("healthy", System.Text.Encoding.UTF8.GetString(read));
+    }
 }

bindings/dotnet/DotOpenDAL/AsyncState.cs

@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+namespace DotOpenDAL;
+
+using System.Collections.Concurrent;
+using System.Diagnostics.CodeAnalysis;
+
+/// <summary>
+/// Marker interface for async operation state tracked by the callback registry.
+/// </summary>
+public interface IAsyncState;
+
+internal static class AsyncStateRegistry
+{
+    private static long nextAsyncStateId;
+    private static readonly ConcurrentDictionary<long, IAsyncState> AsyncStates = new();
+
+    public static long Register(IAsyncState state)
+    {
+        while (true)
+        {
+            var id = Interlocked.Increment(ref nextAsyncStateId);
+            if (id == 0)
+            {
+                continue;
+            }
+
+            if (AsyncStates.TryAdd(id, state))
+            {
+                return id;
+            }
+        }
+    }
+
+    public static void Unregister(long context)
+    {
+        AsyncStates.TryRemove(context, out _);
+    }
+
+    public static bool TryTake<TState>(IntPtr context, [NotNullWhen(true)] out TState? state) where TState : class
+    {
+        state = null;
+        var key = context.ToInt64();
+        if (!AsyncStates.TryRemove(key, out var value))
+        {
+            return false;
+        }
+
+        state = value as TState;
+        return state is not null;
+    }
+}
+
+/// <summary>
+/// State object for a pending asynchronous write operation.
+/// </summary>
+public sealed class WriteAsyncState : IAsyncState
+{
+    /// <summary>
+    /// Completion source that resolves when the native write callback arrives.
+    /// </summary>
+    public TaskCompletionSource Completion { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+    /// <summary>
+    /// Registration used to detach cancellation callbacks when the operation completes.
+    /// </summary>
+    public CancellationTokenRegistration CancellationRegistration { get; set; }
+}
+
+/// <summary>
+/// State object for a pending asynchronous read operation.
+/// </summary>
+public sealed class ReadAsyncState : IAsyncState
+{
+    /// <summary>
+    /// Completion source that resolves with bytes when the native read callback arrives.
+    /// </summary>
+    public TaskCompletionSource<byte[]> Completion { get; } = new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+    /// <summary>
+    /// Registration used to detach cancellation callbacks when the operation completes.
+    /// </summary>
+    public CancellationTokenRegistration CancellationRegistration { get; set; }
+}

bindings/dotnet/DotOpenDAL/ByteBuffer.cs

@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+using System.Runtime.InteropServices;
+
+namespace DotOpenDAL;
+
+[StructLayout(LayoutKind.Sequential)]
+/// <summary>
+/// FFI representation of a Rust byte buffer.
+/// </summary>
+public struct ByteBuffer
+{
+    /// <summary>
+    /// Pointer to the first byte in unmanaged memory.
+    /// </summary>
+    public IntPtr Data;
+
+    /// <summary>
+    /// Number of valid bytes in <see cref="Data"/>.
+    /// </summary>
+    public nuint Len;
+
+    /// <summary>
+    /// Total allocated capacity in bytes.
+    /// </summary>
+    public nuint Capacity;
+
+    /// <summary>
+    /// Releases the unmanaged buffer allocated by the Rust binding.
+    /// </summary>
+    public readonly void Release()
+    {
+        if (Data == IntPtr.Zero)
+        {
+            return;
+        }
+
+        if (Capacity == 0 || Capacity < Len)
+        {
+            return;
+        }
+
+        NativeMethods.buffer_free(Data, Len, Capacity);
+    }
+}

bindings/dotnet/DotOpenDAL/NativeMethods.cs

@@ -0,0 +1,74 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+using System.Runtime.InteropServices;
+using System.Runtime.CompilerServices;
+
+namespace DotOpenDAL;
+
+internal partial class NativeMethods
+{
+    const string __DllName = "opendal_dotnet";
+
+    [LibraryImport(__DllName, EntryPoint = "operator_construct", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static unsafe partial OpenDALIntPtrResult operator_construct(
+        string scheme,
+        IntPtr* keys,
+        IntPtr* values,
+        nuint len);
+
+    [LibraryImport(__DllName, EntryPoint = "operator_free")]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial void operator_free(IntPtr op);
+
+    [LibraryImport(__DllName, EntryPoint = "operator_write", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static unsafe partial OpenDALResult operator_write(Operator op, string path, byte* data, nuint len);
+
+    [LibraryImport(__DllName, EntryPoint = "operator_read", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial OpenDALByteBufferResult operator_read(Operator op, string path);
+
+    [LibraryImport(__DllName, EntryPoint = "operator_write_async", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static unsafe partial OpenDALResult operator_write_async(
+        Operator op,
+        string path,
+        byte* data,
+        nuint len,
+        delegate* unmanaged[Cdecl]<IntPtr, OpenDALResult, void> callback,
+        IntPtr context);
+
+    [LibraryImport(__DllName, EntryPoint = "operator_read_async", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static unsafe partial OpenDALResult operator_read_async(
+        Operator op,
+        string path,
+        delegate* unmanaged[Cdecl]<IntPtr, OpenDALByteBufferResult, void> callback,
+        IntPtr context);
+
+    [LibraryImport(__DllName, EntryPoint = "message_free")]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial void message_free(IntPtr message);
+
+    [LibraryImport(__DllName, EntryPoint = "buffer_free")]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+    internal static partial void buffer_free(IntPtr data, nuint len, nuint capacity);
+}