[upstream] Threading cleanup (erincatto/box2d#1049)

- Added internal scheduler so users don't need one.
- Simplified b2EnqueueTaskCallback. Users are no longer responsible for
providing parallel-for.
- Simplified b2TaskCallback. Users no longer need to provide a
thread/worker index.
- Removed usage of enkiTS from the samples app. It was very useful, but
I needed more control over threading. Users can now refer to scheduler.h
for example task scheduler hook up.
- Cleaned up and documented the solver tasking system
- Added b2World_SetWorkerCount and b2World_GetWorkerCount so the worker
count can be modified on an existing world
- Added `B2_MAX_TASKS` so users can pre-allocate task arrays with stable
pointers.

Author: ikpil

docs/porting-ddfd9df-threading-cleanup.md

@@ -0,0 +1,51 @@
+# Porting Review: box2d ddfd9df727a06940af34b5bc2ef79bcaba287d50
+
+Original commit: `ddfd9df727a06940af34b5bc2ef79bcaba287d50` (`Threading cleanup (#1049)`)
+
+## Summary
+
+This port applies the runtime meaning of the threading cleanup to Box2D.NET:
+
+- `b2TaskCallback` and `b2EnqueueTaskCallback` no longer expose parallel-for ranges to user task systems.
+- Box2D.NET now owns range partitioning through `B2ParallelFors.b2ParallelFor`.
+- A built-in managed scheduler with long-lived worker threads is used when `workerCount > 1` and no external task callbacks are supplied.
+- `B2_MAX_WORKERS` is reduced to 32 and `B2_MAX_TASKS` is added.
+- Worker contexts can be recreated through `b2World_SetWorkerCount` / `b2World_GetWorkerCount`.
+- Solver task block initialization and comments were updated to preserve the original cleanup/documentation intent.
+
+## File Mapping
+
+| Original file | C# counterpart | Status | Meaning difference / notes | Remaining risk |
+|---|---|---:|---|---|
+| `include/box2d/types.h` | `src/Box2D.NET/B2Delegates.cs`, `src/Box2D.NET/B2WorldDef.cs` | Ported | Task delegates simplified to one task context; worker-count documentation updated. | Public API break matches upstream. |
+| `include/box2d/constants.h` | `src/Box2D.NET/B2Constants.cs` | Ported | `B2_MAX_WORKERS = 32`, `B2_MAX_TASKS = 256`. XML/doc-comment style remains C# style. | Existing users expecting 64 workers will be clamped to 32. |
+| `include/box2d/box2d.h` | `src/Box2D.NET/B2Worlds.cs` | Ported | Added `b2World_SetWorkerCount` and `b2World_GetWorkerCount`. | External task callbacks keep ownership of their own scheduler. |
+| `src/parallel_for.c`, `src/parallel_for.h` | `src/Box2D.NET/B2ParallelFor.cs` | Ported | Same atomic block-claiming algorithm; C# class contexts preserve stable worker index. | Managed task scheduling can differ in physical thread affinity. |
+| `src/scheduler.c`, `src/scheduler.h`, `src/core.h`, `src/timer.c` thread primitives | `src/Box2D.NET/B2Scheduler.cs`, .NET `Thread`/`SemaphoreSlim` infrastructure | Ported with .NET equivalent | Native thread/semaphore APIs are not exposed publicly in Box2D.NET; the built-in scheduler mirrors the fixed task array, worker threads, semaphore wakeup, and main-thread helping model. | OS-level details differ from C, but scheduler ownership and task lifetime now match closely. |
+| `src/physics_world.c`, `src/physics_world.h` | `src/Box2D.NET/B2World.cs`, `src/Box2D.NET/B2Worlds.cs` | Ported | Worker context create/destroy helpers added; built-in scheduler selected when no external callbacks are provided. | C# `B2TaskContext`/`B2SensorTaskContext` are classes, so recreation deliberately destroys and reallocates per-worker bitsets. |
+| `src/broad_phase.c` | `src/Box2D.NET/B2BroadPhases.cs` | Ported | Pair finding uses `b2ParallelFor`; tree rebuild uses simplified task callback; move-pair capacity changed from `8x` to `32x`. | Tree rebuild task falls back inline if `B2_MAX_TASKS` is exceeded. |
+| `src/sensor.c`, `src/sensor.h` | `src/Box2D.NET/B2Sensors.cs`, existing sensor context types | Ported | Sensor overlap work uses `b2ParallelFor` and internal worker indexes. | None known. |
+| `src/island.c`, `src/island.h` | `src/Box2D.NET/B2Islands.cs` | Ported | `b2SplitIslandTask` uses single task context callback. | None known. |
+| `src/solver.c`, `src/solver.h` | `src/Box2D.NET/B2Solvers.cs`, `src/Box2D.NET/B2SolverBlock.cs` | Ported | Solver block documentation preserved; block/stage initialization helpers added; finalize/bullet tasks use `b2ParallelFor`; solver tasks use simplified callback. | Managed runtime placement can still differ from native cache affinity. |
+| `src/contact_solver.c`, `src/contact_solver.h` | `src/Box2D.NET/B2ContactSolvers.cs` | Ported | `b2GetContactConstraintSIMDByteCount` renamed to `b2GetWideContactConstraintByteCount`. | C# allocation is element-count based, so byte count is kept as semantic/API counterpart, not used for pointer arithmetic. |
+| `src/container.h`, `src/array.h` | `src/Box2D.NET/B2Arrays.cs` | Already represented / partially ported | Existing generic arrays already distinguish class vs struct allocation; worker context recreation handles zero-initialization semantics explicitly. | No new generic resize-zero helper added because class field ownership must be destroyed deliberately. |
+| `test/test_determinism.c` | `test/Box2D.NET.Test/B2DeterminismTest.cs` | Ported | Determinism now exercises built-in scheduler over wider worker-count range. | More worker-count coverage increases runtime. |
+| `test/test_world.c` | `test/Box2D.NET.Test/B2WorldTest.cs` | Ported | Added `TestSetWorkerCount` with Junkyard stepping and clamp checks. | None known. |
+| `test/test_thread.c` | Existing .NET runtime / `B2Scheduler.cs`; no direct public core API | Not directly ported | Native `b2Thread`/`b2Semaphore` APIs do not exist in Box2D.NET. The relevant scheduler behavior is covered by determinism and worker-count tests. | Lower direct coverage of semaphore/thread wrappers because they are not public C# wrappers. |
+| `test/test_container.c`, `test/test_shape.c`, `test/main.c`, `test/CMakeLists.txt` | Existing NUnit tests / `.csproj` discovery | No direct code changes | Original changes are C test harness/build registration. NUnit auto-discovers tests. | None. |
+| `samples/*.cpp`, `samples/*.c`, `samples/*.h`, `samples/CMakeLists.txt` | `src/Box2D.NET.Samples/Samples/Sample.cs` | Ported where relevant | Samples no longer keep or pass task callbacks into worlds; built-in scheduler is used. | None known. |
+| `benchmark/main.c`, benchmark CSV files | `tools/Box2D.NET.Benchmark`, `src/Box2D.NET.Shared/*Data.cs` | Not directly ported | Original benchmark CSV and C harness updates do not map to the current .NET benchmark data flow in this branch. | Benchmark baselines may not reflect upstream m2air_neon CSV updates. |
+| `shared/random.c`, `shared/random.h`, `shared/utils.c`, `shared/utils.h`, `shared/human.c` | `src/Box2D.NET.Shared/RandomSupports.cs`, `src/Box2D.NET.Shared/Humans.cs` | Already represented / no runtime change needed | C rename from random to utils is build-organization cleanup; C# shared helpers are already split by domain. | No known runtime risk. |
+| `CMakeLists.txt`, `.gitignore`, `README.md`, `docs/foundation.md`, `docs/samples.md`, `src/CMakeLists.txt`, `benchmark/CMakeLists.txt`, `shared/CMakeLists.txt` | `.csproj`, `.sln`, `README.md`, `docs/*` | Reviewed, mostly not applicable | CMake/enkiTS removal has no direct .NET build counterpart. README/docs wording was not broadly rewritten because Box2D.NET docs are not 1:1 with upstream C docs. | Documentation may still mention old task callback details if present outside updated API comments. |
+
+## Special Handling
+
+- `B2TaskContext` and `B2SensorTaskContext` are C# classes. The port does not rely on shallow value-copy semantics; worker context lifetime is managed by destroy/recreate helpers.
+- `b2World_SetWorkerCount` switches a serial world to the built-in scheduler when the count rises above 1. This avoids a C#-specific deadlock where the serial callback would run worker 0 inline before other solver workers are enqueued.
+- Parallel-for worker identity is assigned internally by `B2ParallelForTask.workerIndex`, matching the upstream rule that user task systems no longer provide worker indexes.
+- The built-in scheduler uses managed `Thread` and `SemaphoreSlim` rather than native `b2Thread`/`b2Semaphore` wrappers, but keeps the upstream fixed worker and task-claiming structure.
+
+## Verification
+
+- `dotnet test test/Box2D.NET.Test/Box2D.NET.Test.csproj --framework net10.0 --no-restore`: passed, 163 tests.
+- `dotnet build Box2D.NET.sln --no-restore`: passed with pre-existing warnings.

src/Box2D.NET.Samples/Primitives/SampleTask.cs

@@ -19,6 +19,7 @@
 using Silk.NET.OpenGL.Extensions.ImGui;
 using Silk.NET.Windowing;
 using static Box2D.NET.B2Cores;
+using static Box2D.NET.B2Constants;
 using static Box2D.NET.B2Diagnostics;
 using static Box2D.NET.B2Buffers;
 using static Box2D.NET.B2MathFunction;
@@ -758,7 +759,7 @@ private unsafe void ScrollCallback(WindowHandle* window, double dx, double dy)
 
     private void UpdateUI()
     {
-        int maxWorkers = (int)(Environment.ProcessorCount * 1.5f);
+        int maxWorkers = B2_MAX_WORKERS;
 
         float fontSize = ImGui.GetFontSize();
         float menuWidth = 13.0f * fontSize;

src/Box2D.NET.Samples/Primitives/TaskScheduler.cs

@@ -27,8 +27,7 @@ namespace Box2D.NET.Samples.Samples;
 
 public class Sample : IDisposable
 {
-    public const int k_maxContactPoints = 12 * 2048;
-    public const int m_maxTasks = 64;
+    public const int m_maxTasks = 512;
     public const int m_maxThreads = 64;
     public const int m_profileCapacity = 512;
 
@@ -42,11 +41,6 @@ public class Sample : IDisposable
     protected Camera m_camera;
     protected Draw m_draw;
 
-    private TaskScheduler m_scheduler;
-    private SampleTask[] m_tasks;
-    private int m_taskCount;
-    protected int m_threadCount;
-
     private B2BodyId m_mouseBodyId;
 
     //
@@ -79,19 +73,6 @@ public Sample(SampleContext context)
         m_camera = context.camera;
         m_draw = context.draw;
 
-        m_scheduler = new TaskScheduler();
-        m_scheduler.Initialize(m_context.workerCount);
-
-        m_tasks = new SampleTask[m_maxTasks];
-        for (int i = 0; i < m_maxTasks; ++i)
-        {
-            m_tasks[i] = new SampleTask();
-        }
-
-        m_taskCount = 0;
-
-        m_threadCount = 1 + m_context.workerCount;
-
         m_worldId = b2_nullWorldId;
 
         m_textIncrement = 26;
@@ -125,7 +106,7 @@ public virtual void Dispose()
     {
         // By deleting the world, we delete the bomb, mouse joint, etc.
         b2DestroyWorld(m_worldId);
-
+        
         // delete m_scheduler;
         // delete[] m_tasks;
     }
@@ -140,8 +121,8 @@ public void CreateWorld()
 
         B2WorldDef worldDef = b2DefaultWorldDef();
         worldDef.workerCount = m_context.workerCount;
-        worldDef.enqueueTask = EnqueueTask;
-        worldDef.finishTask = FinishTask;
+        // worldDef.enqueueTask = EnqueueTask;
+        // worldDef.finishTask = FinishTask;
         worldDef.userTaskContext = this;
         worldDef.enableSleep = m_context.enableSleep;
 
@@ -340,41 +321,6 @@ private void DrawProfileSeries(ImDrawListPtr drawList, Vector2 origin, Vector2 s
             previous = current;
         }
     }
-
-
-    private static object EnqueueTask(b2TaskCallback task, int itemCount, int minRange, object taskContext, object userContext)
-    {
-        Sample sample = userContext as Sample;
-        if (sample.m_taskCount < m_maxTasks)
-        {
-            SampleTask sampleTask = sample.m_tasks[sample.m_taskCount];
-            sampleTask.m_SetSize = itemCount;
-            sampleTask.m_MinRange = minRange;
-            sampleTask.m_task = task;
-            sampleTask.m_taskContext = taskContext;
-            sample.m_scheduler.AddTaskSetToPipe(sampleTask);
-            ++sample.m_taskCount;
-            return sampleTask;
-        }
-        else
-        {
-            // This is not fatal but the maxTasks should be increased
-            B2_ASSERT(false);
-            task(0, itemCount, 0, taskContext);
-            return null;
-        }
-    }
-
-    private static void FinishTask(object taskPtr, object userContext)
-    {
-        if (taskPtr != null)
-        {
-            SampleTask sampleTask = taskPtr as SampleTask;
-            Sample sample = userContext as Sample;
-            sample.m_scheduler.WaitforTask(sampleTask);
-        }
-    }
-
     public void ResetText()
     {
         m_textLine = m_textIncrement;
@@ -568,7 +514,7 @@ public virtual void Step()
         for (int i = 0; i < 1; ++i)
         {
             b2World_Step(m_worldId, timeStep, m_context.subStepCount);
-            m_taskCount = 0;
+            // m_taskCount = 0;
         }
 
         if (timeStep > 0.0f)

src/Box2D.NET.Samples/SampleApp.cs

@@ -3,11 +3,9 @@
 // SPDX-License-Identifier: MIT
 
 using System;
-using System.Runtime.InteropServices;
 using System.Runtime.CompilerServices;
 using static Box2D.NET.B2Constants;
 using static Box2D.NET.B2Buffers;
-using static Box2D.NET.B2Diagnostics;
 
 namespace Box2D.NET
 {
@@ -205,5 +203,12 @@ public static void b2Array_Destroy<T>(ref B2Array<T> a)
             a.count = 0;
             a.capacity = 0;
         }
+
+        public static void b2Array_ResizeAndSetZero<T>(ref B2Array<T> a, int n) where T : new()
+        {
+            b2Array_Reserve(ref a, n);
+            // memset(0, ...)
+            a.count = n;
+        }
     }
-}
+}