Pull model task API (#228)

Port the pull model task API from Box2D.

https://github.com/erincatto/box2d/pull/1133

Addresses discussion #150
This commit is contained in:
Erin Catto 2026-11-17 16:42:52 -08:00 • committed by GitHub
commit 1767150df4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
24 changed files with 2048 additions and 406 deletions

View file

@ -159,12 +159,12 @@ You can optionally connect your own task scheduler if you want more control. Mu
```c
// Implement b3EnqueueTaskCallback
void* MyEnqueueTask(b3TaskCallback* task, void* taskContext,
void* userContext, const char* taskName)
void* userContext, b3TaskType taskType)
{
MyTask* t = AllocTask();
t->task = task;
t->taskContext = taskContext;
Scheduler* myScheduler = (Scheduler*)userContact;
Scheduler* myScheduler = (Scheduler*)userContext;
SubmitToThreadPool(myScheduler, t);
return t;
}
@ -184,6 +184,53 @@ worldDef.userTaskContext = myScheduler;
worldDef.workerCount = GetMyWorkerCount();
```
The finish callback is optional. Without it `b3World_Step()` waits on an internal semaphore that
the last task of each phase signals. This suits task systems that can launch work but cannot wait
on a single task.
### Stepping without blocking
`b3World_Step()` holds the calling thread until the step is done. Some task systems cannot allow
this, for example a phased or wavefront scheduler where a thread that joins a parallel job cannot
leave it. For these you can drive the step yourself with `b3World_BeginStep()` and
`b3World_ContinueStep()`. Each call runs the serial work between two phases and returns the next
batch of tasks. An empty batch means the step is complete.
```c
b3TaskBatch batch = b3World_BeginStep( worldId, timeStep, subStepCount );
while ( batch.count > 0 )
{
// Run every task in the batch on any threads, in any order, then wait for them.
// MyRunTasks is a function you implement.
MyRunTasks( batch.tasks, batch.count );
batch = b3World_ContinueStep( worldId );
}
```
No callbacks are needed and the built-in scheduler is never created. The worker count still sets
the most tasks in a batch, `workerCount + 2`, and the size of the per-worker data. Each parallel
task claims blocks of work from a shared counter until none are left, so the tasks that run first
do most of the work and a task that starts late returns right away. Fewer threads than tasks costs
only the extra task launches, and you can adjust the worker count with `b3World_SetWorkerCount()` at
runtime.
The rules:
- Call each task function exactly once. Tasks in a batch may run concurrently on any threads.
- Begin and continue may be called from any thread, but never while a task of the current batch is
running.
- The world is locked until the step completes. Do not read or write it in between.
- The tasks of the constraint solver wait on each other. They work with any number of threads,
even when run one after another on a single thread, but a solver task that has started must not
be suspended indefinitely.
One task may be marked `b3Task::deferred`. This is the rebuild of the dynamic tree, which overlaps
the narrow phase and the solver. You may leave it running across continue calls. A later batch
lists it in `b3TaskBatch::joinTasks` and it must be complete before the continue that follows that
batch. If you ignore the flag and run it with the rest of its batch, the step is still correct, it
just loses the overlap.
### Threading model
The multithreading design for Box3D is focused on [data parallelism](https://en.wikipedia.org/wiki/Data_parallelism).