Scope PREFIX to MinGW; views refuse lane access after dispose; document lifetime limits

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-11-19 20:51:04 +01:00
commit e6a1e4ad02
4 changed files with 92 additions and 45 deletions

View file

@ -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.

View file

@ -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()

View file

@ -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<T> Lane<T>(T* p, int n) where T : unmanaged
{
_world.ThrowIfDisposed();
return new(p, n);
}
private Span<T> Write<T>(T* p, int n) where T : unmanaged
{
_world.ThrowIfDisposed();
return new(p, n);
}
internal Box3DSoaView(Box3DSoaViewNative v, Box3DSoaWorld world)
{
_v = v;
_world = world;
}
/// <summary>Bodies at the moment this view was taken: take it after the last Add. Only the lane contents are live.</summary>
public int Count => _v.Count;
public int Capacity => _v.Capacity;
public ReadOnlySpan<ulong> StableId => new(_v.StableId, Count);
public ReadOnlySpan<uint> Kind => new(_v.Kind, Count);
public ReadOnlySpan<ulong> StableId => Lane(_v.StableId, Count);
public ReadOnlySpan<uint> Kind => Lane(_v.Kind, Count);
/// <summary>Lane index of the body's parent in the limb tree, or -1 for a root. Set at creation, not used by Box3D.</summary>
public ReadOnlySpan<int> Parent => new(_v.Parent, Count);
public ReadOnlySpan<int> Parent => Lane(_v.Parent, Count);
/// <summary>The caller's limb label for the body. Set at creation, not used by Box3D.</summary>
public ReadOnlySpan<int> Limb => new(_v.Limb, Count);
public ReadOnlySpan<float> PositionX => new(_v.PositionX, Count);
public ReadOnlySpan<float> PositionY => new(_v.PositionY, Count);
public ReadOnlySpan<float> PositionZ => new(_v.PositionZ, Count);
public ReadOnlySpan<int> Limb => Lane(_v.Limb, Count);
public ReadOnlySpan<float> PositionX => Lane(_v.PositionX, Count);
public ReadOnlySpan<float> PositionY => Lane(_v.PositionY, Count);
public ReadOnlySpan<float> PositionZ => Lane(_v.PositionZ, Count);
/// <summary>Unit quaternion, x y z w.</summary>
public ReadOnlySpan<float> RotationX => new(_v.RotationX, Count);
public ReadOnlySpan<float> RotationY => new(_v.RotationY, Count);
public ReadOnlySpan<float> RotationZ => new(_v.RotationZ, Count);
public ReadOnlySpan<float> RotationW => new(_v.RotationW, Count);
public ReadOnlySpan<float> VelocityX => new(_v.VelocityX, Count);
public ReadOnlySpan<float> VelocityY => new(_v.VelocityY, Count);
public ReadOnlySpan<float> VelocityZ => new(_v.VelocityZ, Count);
public ReadOnlySpan<float> AngularVelocityX => new(_v.AngularVelocityX, Count);
public ReadOnlySpan<float> AngularVelocityY => new(_v.AngularVelocityY, Count);
public ReadOnlySpan<float> AngularVelocityZ => new(_v.AngularVelocityZ, Count);
public ReadOnlySpan<float> RotationX => Lane(_v.RotationX, Count);
public ReadOnlySpan<float> RotationY => Lane(_v.RotationY, Count);
public ReadOnlySpan<float> RotationZ => Lane(_v.RotationZ, Count);
public ReadOnlySpan<float> RotationW => Lane(_v.RotationW, Count);
public ReadOnlySpan<float> VelocityX => Lane(_v.VelocityX, Count);
public ReadOnlySpan<float> VelocityY => Lane(_v.VelocityY, Count);
public ReadOnlySpan<float> VelocityZ => Lane(_v.VelocityZ, Count);
public ReadOnlySpan<float> AngularVelocityX => Lane(_v.AngularVelocityX, Count);
public ReadOnlySpan<float> AngularVelocityY => Lane(_v.AngularVelocityY, Count);
public ReadOnlySpan<float> 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<float> ForceX => new(_v.ForceX, Count);
public Span<float> ForceY => new(_v.ForceY, Count);
public Span<float> ForceZ => new(_v.ForceZ, Count);
public Span<float> TorqueX => new(_v.TorqueX, Count);
public Span<float> TorqueY => new(_v.TorqueY, Count);
public Span<float> TorqueZ => new(_v.TorqueZ, Count);
public Span<float> ForceX => Write(_v.ForceX, Count);
public Span<float> ForceY => Write(_v.ForceY, Count);
public Span<float> ForceZ => Write(_v.ForceZ, Count);
public Span<float> TorqueX => Write(_v.TorqueX, Count);
public Span<float> TorqueY => Write(_v.TorqueY, Count);
public Span<float> TorqueZ => Write(_v.TorqueZ, Count);
/// <summary>Joints at the moment this view was taken: take it after the last AddJoint.</summary>
public int JointCount => _v.JointCount;
public ReadOnlySpan<uint> JointKind => new(_v.JointKind, JointCount);
public ReadOnlySpan<uint> JointKind => Lane(_v.JointKind, JointCount);
/// <summary>Lane indices of the joint's two bodies; the second is the child.</summary>
public ReadOnlySpan<int> JointBodyA => new(_v.JointBodyA, JointCount);
public ReadOnlySpan<int> JointBodyB => new(_v.JointBodyB, JointCount);
public ReadOnlySpan<int> JointBodyA => Lane(_v.JointBodyA, JointCount);
public ReadOnlySpan<int> JointBodyB => Lane(_v.JointBodyB, JointCount);
/// <summary>Box3D's own angle: revolute angle or spherical twist angle (radians), zero for a weld.</summary>
public ReadOnlySpan<float> JointAngle => new(_v.JointAngle, JointCount);
public ReadOnlySpan<float> JointAngle => Lane(_v.JointAngle, JointCount);
/// <summary>World orientation of the joint frame on body A (quaternion x y z w).</summary>
public ReadOnlySpan<float> JointFrameX => new(_v.JointFrameX, JointCount);
public ReadOnlySpan<float> JointFrameY => new(_v.JointFrameY, JointCount);
public ReadOnlySpan<float> JointFrameZ => new(_v.JointFrameZ, JointCount);
public ReadOnlySpan<float> JointFrameW => new(_v.JointFrameW, JointCount);
public ReadOnlySpan<float> JointFrameX => Lane(_v.JointFrameX, JointCount);
public ReadOnlySpan<float> JointFrameY => Lane(_v.JointFrameY, JointCount);
public ReadOnlySpan<float> JointFrameZ => Lane(_v.JointFrameZ, JointCount);
public ReadOnlySpan<float> JointFrameW => Lane(_v.JointFrameW, JointCount);
/// <summary>Joint frame B relative to frame A (quaternion x y z w, w >= 0); identity at the creation pose.</summary>
public ReadOnlySpan<float> JointRotationX => new(_v.JointRotationX, JointCount);
public ReadOnlySpan<float> JointRotationY => new(_v.JointRotationY, JointCount);
public ReadOnlySpan<float> JointRotationZ => new(_v.JointRotationZ, JointCount);
public ReadOnlySpan<float> JointRotationW => new(_v.JointRotationW, JointCount);
public ReadOnlySpan<float> JointRotationX => Lane(_v.JointRotationX, JointCount);
public ReadOnlySpan<float> JointRotationY => Lane(_v.JointRotationY, JointCount);
public ReadOnlySpan<float> JointRotationZ => Lane(_v.JointRotationZ, JointCount);
public ReadOnlySpan<float> JointRotationW => Lane(_v.JointRotationW, JointCount);
/// <summary>Body B's angular velocity minus body A's, expressed in frame A (rad/s).</summary>
public ReadOnlySpan<float> JointAngularVelocityX => new(_v.JointAngularVelocityX, JointCount);
public ReadOnlySpan<float> JointAngularVelocityY => new(_v.JointAngularVelocityY, JointCount);
public ReadOnlySpan<float> JointAngularVelocityZ => new(_v.JointAngularVelocityZ, JointCount);
public ReadOnlySpan<float> JointAngularVelocityX => Lane(_v.JointAngularVelocityX, JointCount);
public ReadOnlySpan<float> JointAngularVelocityY => Lane(_v.JointAngularVelocityY, JointCount);
public ReadOnlySpan<float> JointAngularVelocityZ => Lane(_v.JointAngularVelocityZ, JointCount);
/// <summary>Address of a lane, for tests and interop that need to prove nothing was copied.</summary>
public nint PositionYAddress => (nint)_v.PositionY;
@ -219,6 +236,8 @@ public readonly unsafe struct Box3DSoaView
/// <summary>
/// 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).
/// </summary>
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);

View file

@ -147,4 +147,16 @@ public sealed unsafe class Box3DSoaWorldTests
Assert.Throws<ObjectDisposedException>(() => world.Step(Dt));
Assert.Throws<ObjectDisposedException>(() => 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<ObjectDisposedException>(() => view.PositionY.Length);
Assert.Throws<ObjectDisposedException>(() => view.ForceX.Length);
Assert.Throws<ObjectDisposedException>(() => view.JointAngle.Length);
}
}