A permissively licensed C and C++ Task Scheduler for creating parallel programs. Requires C++11 support.
ZLIB License
Support development of enkiTS through Github Sponsors or Patreon
Master branch | Dev branch |
---|---|
A permissively licensed C and C++ Task Scheduler for creating parallel programs. Requires C++11 support.
The primary goal of enkiTS is to help developers create programs which handle both data and task level parallelism to utilize the full performance of multicore CPUs, whilst being lightweight (only a small amount of code) and easy to use.
enkiTS was developed for, and is used in enkisoftware's Avoyd codebase.
enkiTS is primarily developed on x64 and x86 Intel architectures on MS Windows, with well tested support for Linux and somewhat less frequently tested support on Mac OS and ARM Android.
Several examples exist in the example folder.
For further examples, see https://github.com/dougbinks/enkiTSExamples
Building enkiTS is simple, just add the files in enkiTS/src to your build system (_c.* files can be ignored if you only need C++ interface), and add enkiTS/src to your include path. Unix / Linux builds will likely require the pthreads library.
For C++
#include "TaskScheduler.h"
TaskScheduler.cpp
For C
#include "TaskScheduler_c.h"
TaskScheduler.cpp
TaskScheduler_c.cpp
For cmake, on Windows / Mac OS X / Linux with cmake installed, open a prompt in the enkiTS directory and:
mkdir build
cd build
cmake ..
make all
or for Visual Studio open enkiTS.sln
I recommend using enkiTS directly from source in each project rather than installing it for system wide use. However enkiTS' cmake script can also be used to install the library
if the ENKITS_INSTALL
cmake variable is set to ON
(it defaults to OFF
).
When installed the header files are installed in a subdirectory of the include path, include/enkiTS
to ensure that they do not conflict with header files from other packages.
When building applications either ensure this is part of the INCLUDE_PATH
variable or ensure that enkiTS is in the header path in the source files, for example use #include "enkiTS/TaskScheduler.h"
instead of #include "TaskScheduler.h"
.
#include "TaskScheduler.h"
enki::TaskScheduler g_TS;
// define a task set, can ignore range if we only do one thing
struct ParallelTaskSet : enki::ITaskSet {
void ExecuteRange( enki::TaskSetPartition range_, uint32_t threadnum_ ) override {
// do something here, can issue tasks with g_TS
}
};
int main(int argc, const char * argv[]) {
g_TS.Initialize();
ParallelTaskSet task; // default constructor has a set size of 1
g_TS.AddTaskSetToPipe( &task );
// wait for task set (running tasks if they exist)
// since we've just added it and it has no range we'll likely run it.
g_TS.WaitforTask( &task );
return 0;
}
#include "TaskScheduler.h"
enki::TaskScheduler g_TS;
int main(int argc, const char * argv[]) {
g_TS.Initialize();
enki::TaskSet task( 1, []( enki::TaskSetPartition range_, uint32_t threadnum_ ) {
// do something here
} );
g_TS.AddTaskSetToPipe( &task );
g_TS.WaitforTask( &task );
return 0;
}
// See full example in Priorities.cpp
#include "TaskScheduler.h"
enki::TaskScheduler g_TS;
struct ExampleTask : enki::ITaskSet
{
ExampleTask( ) { m_SetSize = size_; }
void ExecuteRange( enki::TaskSetPartition range_, uint32_t threadnum_ ) override {
// See full example in Priorities.cpp
}
};
// This example demonstrates how to run a long running task alongside tasks
// which must complete as early as possible using priorities.
int main(int argc, const char * argv[])
{
g_TS.Initialize();
ExampleTask lowPriorityTask( 10 );
lowPriorityTask.m_Priority = enki::TASK_PRIORITY_LOW;
ExampleTask highPriorityTask( 1 );
highPriorityTask.m_Priority = enki::TASK_PRIORITY_HIGH;
g_TS.AddTaskSetToPipe( &lowPriorityTask );
for( int task = 0; task < 10; ++task )
{
// run high priority tasks
g_TS.AddTaskSetToPipe( &highPriorityTask );
// wait for task but only run tasks of the same priority or higher on this thread
g_TS.WaitforTask( &highPriorityTask, highPriorityTask.m_Priority );
}
// wait for low priority task, run any tasks on this thread whilst waiting
g_TS.WaitforTask( &lowPriorityTask );
return 0;
}
#include "TaskScheduler.h"
enki::TaskScheduler g_TS;
// define a task set, can ignore range if we only do one thing
struct PinnedTask : enki::IPinnedTask {
void Execute() override {
// do something here, can issue tasks with g_TS
}
};
int main(int argc, const char * argv[]) {
g_TS.Initialize();
PinnedTask task; //default constructor sets thread for pinned task to 0 (main thread)
g_TS.AddPinnedTask( &task );
// RunPinnedTasks must be called on main thread to run any pinned tasks for that thread.
// Tasking threads automatically do this in their task loop.
g_TS.RunPinnedTasks();
// wait for task set (running tasks if they exist)
// since we've just added it and it has no range we'll likely run it.
g_TS.WaitforTask( &task );
return 0;
}
#include "TaskScheduler.h"
enki::TaskScheduler g_TS;
// define a task set, can ignore range if we only do one thing
struct TaskA : enki::ITaskSet {
void ExecuteRange( enki::TaskSetPartition range_, uint32_t threadnum_ ) override {
// do something here, can issue tasks with g_TS
}
};
struct TaskB : enki::ITaskSet {
enki::Dependency m_Dependency;
void ExecuteRange( enki::TaskSetPartition range_, uint32_t threadnum_ ) override {
// do something here, can issue tasks with g_TS
}
};
int main(int argc, const char * argv[]) {
g_TS.Initialize();
// set dependencies once (can set more than one if needed).
TaskA taskA;
TaskB taskB;
taskB.SetDependency( taskB.m_Dependency, &taskA );
g_TS.AddTaskSetToPipe( &taskA ); // add first task
g_TS.WaitforTask( &taskB ); // wait for last
return 0;
}
#include "TaskScheduler.h"
enki::TaskScheduler g_TS;
struct ParallelTaskSet : ITaskSet
{
void ExecuteRange( enki::TaskSetPartition range_, uint32_t threadnum_ ) override {
// Do something
}
};
void threadFunction()
{
g_TS.RegisterExternalTaskThread();
// sleep for a while instead of doing something such as file IO
std::this_thread::sleep_for( std::chrono::milliseconds( num_ * 100 ) );
ParallelTaskSet task;
g_TS.AddTaskSetToPipe( &task );
g_TS.WaitforTask( &task);
g_TS.DeRegisterExternalTaskThread();
}
int main(int argc, const char * argv[])
{
enki::TaskSchedulerConfig config;
config.numExternalTaskThreads = 1; // we have one extra external thread
g_TS.Initialize( config );
std::thread exampleThread( threadFunction );
exampleThread.join();
return 0;
}
#include "TaskScheduler.h"
enki::TaskScheduler g_TS;
struct RunPinnedTaskLoopTask : enki::IPinnedTask
{
void Execute() override
{
while( !g_TS.GetIsShutdownRequested() )
{
g_TS.WaitForNewPinnedTasks(); // this thread will 'sleep' until there are new pinned tasks
g_TS.RunPinnedTasks();
}
}
};
struct PretendDoFileIO : enki::IPinnedTask
{
void Execute() override
{
// Do file IO
}
};
int main(int argc, const char * argv[])
{
enki::TaskSchedulerConfig config;
// In this example we create more threads than the hardware can run,
// because the IO thread will spend most of it's time idle or blocked
// and therefore not scheduled for CPU time by the OS
config.numTaskThreadsToCreate += 1;
g_TS.Initialize( config );
// in this example we place our IO threads at the end
RunPinnedTaskLoopTask runPinnedTaskLoopTasks;
runPinnedTaskLoopTasks.threadNum = g_TS.GetNumTaskThreads() - 1;
g_TS.AddPinnedTask( &runPinnedTaskLoopTasks );
// Send pretend file IO task to external thread FILE_IO
PretendDoFileIO pretendDoFileIO;
pretendDoFileIO.threadNum = runPinnedTaskLoopTasks.threadNum;
g_TS.AddPinnedTask( &pretendDoFileIO );
// ensure runPinnedTaskLoopTasks complete by explicitly calling shutdown
g_TS.WaitforAllAndShutdown();
return 0;
}
The C++98 compatible branch has been deprecated as I'm not aware of anyone needing it.
The user thread versions are no longer being maintained as they are no longer in use. Similar functionality can be obtained with the externalTaskThreads
Avoyd is an abstract 6 degrees of freedom voxel game. enkiTS was developed for use in our in-house engine powering Avoyd.
GPU/CPU Texture Generator
Aras Pranckevičius' code for his series on Daily Path Tracer experiments with various languages.
.
Marco Castorina and Gabriel Sassone's book on developing a modern rendering engine from first principles using the Vulkan API. enkiTS is used as the task library to distribute work across cores.
Copyright (c) 2013-2020 Doug Binks
This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: