diff --git a/docs/soa-world.md b/docs/soa-world.md index e063bf9..8ba0b73 100644 --- a/docs/soa-world.md +++ b/docs/soa-world.md @@ -51,6 +51,17 @@ a torque-driven jointed body. ## Not done Contact facts for the SoA world (Begin/Hit/End), body removal with a stable ordering rule, compound bodies -and per-shape material, joint motors and springs (Lodur drives joints from torque lanes instead), and a -a typed surface in `Ymir.Core` (the SoA world is public in `Ymir.Box3D`). Windows build -and Unity consumption are unrun; cross-platform bit-identity is unclaimed. +and per-shape material, and joint motors and springs (Lodur drives joints from torque lanes instead). +`Ymir.Core` has no session-level surface over the SoA world yet; consumers use `Ymir.Box3D` directly. +Unity consumption is unrun; cross-platform bit-identity is unclaimed. + +## Build and lifetime notes + +- Native library name: `ymir_box3d.dll` on Windows (MinGW needs `PREFIX ""`, set under `if(MINGW)`; MSVC emits it + natively), `libymir_box3d.so` on Linux, `libymir_box3d.dylib` on macOS. `Ymir.Box3D.csproj` copies from + `bin\$(Configuration)\` on Windows, which is where a multi-config generator writes. +- Windows run: MinGW gcc with `CMAKE_GENERATOR="Ninja Multi-Config" CC=gcc`; `Ymir.Box3D.Soa.Tests` passes. + Linux run (Yggdrasil, default generator, gcc): the same tests pass and emit `bin/libymir_box3d.so`. macOS is unrun. +- `Box3DSoaWorld` is not thread-safe: `Dispose` must not race `Step` or a lane read. A `Box3DSoaView` refuses + lane access (ObjectDisposedException) once its world is disposed. Known limit: an undisposed world leaks its + native memory; there is no finalizer or SafeHandle. diff --git a/native/Ymir.Box3D/CMakeLists.txt b/native/Ymir.Box3D/CMakeLists.txt index a35d8a9..1ace1cd 100644 --- a/native/Ymir.Box3D/CMakeLists.txt +++ b/native/Ymir.Box3D/CMakeLists.txt @@ -23,5 +23,8 @@ set_target_properties(ymir_box3d PROPERTIES C_VISIBILITY_PRESET hidden RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin" LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin" - ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib" - PREFIX "") + ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib") +if(MINGW) + # MinGW would emit libymir_box3d.dll; the managed side loads ymir_box3d.dll. + set_property(TARGET ymir_box3d PROPERTY PREFIX "") +endif() diff --git a/src/Ymir.Box3D/Box3DSoaWorld.cs b/src/Ymir.Box3D/Box3DSoaWorld.cs index 2d1759a..fad36f7 100644 --- a/src/Ymir.Box3D/Box3DSoaWorld.cs +++ b/src/Ymir.Box3D/Box3DSoaWorld.cs @@ -151,66 +151,83 @@ internal static unsafe partial class Box3DSoaNative public readonly unsafe struct Box3DSoaView { private readonly Box3DSoaViewNative _v; + private readonly Box3DSoaWorld _world; - internal Box3DSoaView(Box3DSoaViewNative v) => _v = v; + private ReadOnlySpan Lane(T* p, int n) where T : unmanaged + { + _world.ThrowIfDisposed(); + return new(p, n); + } + + private Span Write(T* p, int n) where T : unmanaged + { + _world.ThrowIfDisposed(); + return new(p, n); + } + + internal Box3DSoaView(Box3DSoaViewNative v, Box3DSoaWorld world) + { + _v = v; + _world = world; + } /// Bodies at the moment this view was taken: take it after the last Add. Only the lane contents are live. public int Count => _v.Count; public int Capacity => _v.Capacity; - public ReadOnlySpan StableId => new(_v.StableId, Count); - public ReadOnlySpan Kind => new(_v.Kind, Count); + public ReadOnlySpan StableId => Lane(_v.StableId, Count); + public ReadOnlySpan Kind => Lane(_v.Kind, Count); /// Lane index of the body's parent in the limb tree, or -1 for a root. Set at creation, not used by Box3D. - public ReadOnlySpan Parent => new(_v.Parent, Count); + public ReadOnlySpan Parent => Lane(_v.Parent, Count); /// The caller's limb label for the body. Set at creation, not used by Box3D. - public ReadOnlySpan Limb => new(_v.Limb, Count); - public ReadOnlySpan PositionX => new(_v.PositionX, Count); - public ReadOnlySpan PositionY => new(_v.PositionY, Count); - public ReadOnlySpan PositionZ => new(_v.PositionZ, Count); + public ReadOnlySpan Limb => Lane(_v.Limb, Count); + public ReadOnlySpan PositionX => Lane(_v.PositionX, Count); + public ReadOnlySpan PositionY => Lane(_v.PositionY, Count); + public ReadOnlySpan PositionZ => Lane(_v.PositionZ, Count); /// Unit quaternion, x y z w. - public ReadOnlySpan RotationX => new(_v.RotationX, Count); - public ReadOnlySpan RotationY => new(_v.RotationY, Count); - public ReadOnlySpan RotationZ => new(_v.RotationZ, Count); - public ReadOnlySpan RotationW => new(_v.RotationW, Count); - public ReadOnlySpan VelocityX => new(_v.VelocityX, Count); - public ReadOnlySpan VelocityY => new(_v.VelocityY, Count); - public ReadOnlySpan VelocityZ => new(_v.VelocityZ, Count); - public ReadOnlySpan AngularVelocityX => new(_v.AngularVelocityX, Count); - public ReadOnlySpan AngularVelocityY => new(_v.AngularVelocityY, Count); - public ReadOnlySpan AngularVelocityZ => new(_v.AngularVelocityZ, Count); + public ReadOnlySpan RotationX => Lane(_v.RotationX, Count); + public ReadOnlySpan RotationY => Lane(_v.RotationY, Count); + public ReadOnlySpan RotationZ => Lane(_v.RotationZ, Count); + public ReadOnlySpan RotationW => Lane(_v.RotationW, Count); + public ReadOnlySpan VelocityX => Lane(_v.VelocityX, Count); + public ReadOnlySpan VelocityY => Lane(_v.VelocityY, Count); + public ReadOnlySpan VelocityZ => Lane(_v.VelocityZ, Count); + public ReadOnlySpan AngularVelocityX => Lane(_v.AngularVelocityX, Count); + public ReadOnlySpan AngularVelocityY => Lane(_v.AngularVelocityY, Count); + public ReadOnlySpan AngularVelocityZ => Lane(_v.AngularVelocityZ, Count); // Write lanes: the caller's per-body world force (N, at the centre of mass) and torque (N m), written // in place before a step. Step applies them to the dynamic bodies and clears them, so a lane holds one // step's intent. A non-finite value makes Step throw before any body is touched. - public Span ForceX => new(_v.ForceX, Count); - public Span ForceY => new(_v.ForceY, Count); - public Span ForceZ => new(_v.ForceZ, Count); - public Span TorqueX => new(_v.TorqueX, Count); - public Span TorqueY => new(_v.TorqueY, Count); - public Span TorqueZ => new(_v.TorqueZ, Count); + public Span ForceX => Write(_v.ForceX, Count); + public Span ForceY => Write(_v.ForceY, Count); + public Span ForceZ => Write(_v.ForceZ, Count); + public Span TorqueX => Write(_v.TorqueX, Count); + public Span TorqueY => Write(_v.TorqueY, Count); + public Span TorqueZ => Write(_v.TorqueZ, Count); /// Joints at the moment this view was taken: take it after the last AddJoint. public int JointCount => _v.JointCount; - public ReadOnlySpan JointKind => new(_v.JointKind, JointCount); + public ReadOnlySpan JointKind => Lane(_v.JointKind, JointCount); /// Lane indices of the joint's two bodies; the second is the child. - public ReadOnlySpan JointBodyA => new(_v.JointBodyA, JointCount); - public ReadOnlySpan JointBodyB => new(_v.JointBodyB, JointCount); + public ReadOnlySpan JointBodyA => Lane(_v.JointBodyA, JointCount); + public ReadOnlySpan JointBodyB => Lane(_v.JointBodyB, JointCount); /// Box3D's own angle: revolute angle or spherical twist angle (radians), zero for a weld. - public ReadOnlySpan JointAngle => new(_v.JointAngle, JointCount); + public ReadOnlySpan JointAngle => Lane(_v.JointAngle, JointCount); /// World orientation of the joint frame on body A (quaternion x y z w). - public ReadOnlySpan JointFrameX => new(_v.JointFrameX, JointCount); - public ReadOnlySpan JointFrameY => new(_v.JointFrameY, JointCount); - public ReadOnlySpan JointFrameZ => new(_v.JointFrameZ, JointCount); - public ReadOnlySpan JointFrameW => new(_v.JointFrameW, JointCount); + public ReadOnlySpan JointFrameX => Lane(_v.JointFrameX, JointCount); + public ReadOnlySpan JointFrameY => Lane(_v.JointFrameY, JointCount); + public ReadOnlySpan JointFrameZ => Lane(_v.JointFrameZ, JointCount); + public ReadOnlySpan JointFrameW => Lane(_v.JointFrameW, JointCount); /// Joint frame B relative to frame A (quaternion x y z w, w >= 0); identity at the creation pose. - public ReadOnlySpan JointRotationX => new(_v.JointRotationX, JointCount); - public ReadOnlySpan JointRotationY => new(_v.JointRotationY, JointCount); - public ReadOnlySpan JointRotationZ => new(_v.JointRotationZ, JointCount); - public ReadOnlySpan JointRotationW => new(_v.JointRotationW, JointCount); + public ReadOnlySpan JointRotationX => Lane(_v.JointRotationX, JointCount); + public ReadOnlySpan JointRotationY => Lane(_v.JointRotationY, JointCount); + public ReadOnlySpan JointRotationZ => Lane(_v.JointRotationZ, JointCount); + public ReadOnlySpan JointRotationW => Lane(_v.JointRotationW, JointCount); /// Body B's angular velocity minus body A's, expressed in frame A (rad/s). - public ReadOnlySpan JointAngularVelocityX => new(_v.JointAngularVelocityX, JointCount); - public ReadOnlySpan JointAngularVelocityY => new(_v.JointAngularVelocityY, JointCount); - public ReadOnlySpan JointAngularVelocityZ => new(_v.JointAngularVelocityZ, JointCount); + public ReadOnlySpan JointAngularVelocityX => Lane(_v.JointAngularVelocityX, JointCount); + public ReadOnlySpan JointAngularVelocityY => Lane(_v.JointAngularVelocityY, JointCount); + public ReadOnlySpan JointAngularVelocityZ => Lane(_v.JointAngularVelocityZ, JointCount); /// Address of a lane, for tests and interop that need to prove nothing was copied. public nint PositionYAddress => (nint)_v.PositionY; @@ -219,6 +236,8 @@ public readonly unsafe struct Box3DSoaView /// /// A headless 3D Box3D world: N bodies stepped deterministically (one worker, fixed order) with a /// structure-of-arrays state view read in place. Ymir writes no solver; Box3D decides everything. +/// Not thread-safe: Dispose must not race Step or a lane read. Dispose frees the native world; an +/// undisposed world leaks it (no finalizer by design in this cut). /// public sealed class Box3DSoaWorld : IDisposable { @@ -245,7 +264,7 @@ public sealed class Box3DSoaWorld : IDisposable { ObjectDisposedException.ThrowIf(_handle == 0, this); Check(Box3DSoaNative.ymir_box3d_soa_get_view(_handle, out var v)); - return new Box3DSoaView(v); + return new Box3DSoaView(v, this); } } @@ -346,6 +365,8 @@ public sealed class Box3DSoaWorld : IDisposable Check(Box3DSoaNative.ymir_box3d_soa_step(_handle, timeStep, subStepCount)); } + internal void ThrowIfDisposed() => ObjectDisposedException.ThrowIf(Volatile.Read(ref _handle) == 0, this); + public void Dispose() { var handle = Interlocked.Exchange(ref _handle, 0); diff --git a/tests/Ymir.Box3D.Soa.Tests/Box3DSoaWorldTests.cs b/tests/Ymir.Box3D.Soa.Tests/Box3DSoaWorldTests.cs index 462d2e8..bb537a2 100644 --- a/tests/Ymir.Box3D.Soa.Tests/Box3DSoaWorldTests.cs +++ b/tests/Ymir.Box3D.Soa.Tests/Box3DSoaWorldTests.cs @@ -147,4 +147,16 @@ public sealed unsafe class Box3DSoaWorldTests Assert.Throws(() => world.Step(Dt)); Assert.Throws(() => world.View); } + + [Fact] + public void A_view_taken_before_dispose_refuses_lane_access_after() + { + var world = Build(); + var view = world.View; + Assert.True(view.PositionY.Length > 0); + world.Dispose(); + Assert.Throws(() => view.PositionY.Length); + Assert.Throws(() => view.ForceX.Length); + Assert.Throws(() => view.JointAngle.Length); + } }