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:
parent
8f3b2e12eb
commit
1767150df4
24 changed files with 2048 additions and 406 deletions
|
|
@ -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).
|
||||
|
|
|
|||
Loading…
Reference in a new issue