Support development of enkiTS through Github Sponsors or Patreon

enkiTS Logo

enkiTS

| Master branch | Dev branch | | --- | --- | | | |

enki Task Scheduler

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.

Platforms

Windows, Linux, Mac OS, Android (should work on iOS)
x64 & x86, ARM

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.

Examples

Several examples exist in the example folder.

For further examples, see https://github.com/dougbinks/enkiTSExamples

Building

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++

Use #include "TaskScheduler.h"
Add enkiTS/src to your include path
Compile / Add to project:
- TaskScheduler.cpp
Unix / Linux builds will likely require the pthreads library.

For C

Use #include "TaskScheduler_c.h"
Add enkiTS/src to your include path
Compile / Add to project:
- TaskScheduler.cpp
- TaskScheduler_c.cpp
Unix / Linux builds will likely require the pthreads library.

For cmake, on Windows / Mac OS X / Linux with cmake installed, open a prompt in the enkiTS directory and:

mkdir build
cd build
cmake ..
either run make all or for Visual Studio open enkiTS.sln

Project Features

Lightweight - enkiTS is designed to be lean so you can use it anywhere easily, and understand it.
Fast, then scalable - enkiTS is designed for consumer devices first, so performance on a low number of threads is important, followed by scalability.
Braided parallelism - enkiTS can issue tasks from another task as well as from the thread which created the Task System, and has a simple task interface for both data parallel and task parallelism.
Up-front Allocation friendly - enkiTS is designed for zero allocations during scheduling.
Can pin tasks to a given thread - enkiTS can schedule a task which will only be run on the specified thread.
Can set task priorities - Up to 5 task priorities can be configured via define ENKITS_TASK_PRIORITIES_NUM (defaults to 3). Higher priority tasks are run before lower priority ones.
Can register external threads to use with enkiTS - Can configure enkiTS with numExternalTaskThreads which can be registered to use with the enkiTS API.
Custom allocator API - can configure enkiTS with custom allocators, see example/CustomAllocator.cpp and example/CustomAllocator_c.c.
Dependencies - can set dependendencies between tasks see example/Dependencies.cpp and example/Dependencies_c.c.
Completion Actions - can perform an action on task completion. This avoids the expensive action of adding the task to the scheduler, and can be used to safely delete a completed task. See example/CompletionAction.cpp and example/CompletionAction_c.c
NEW Can wait for pinned tasks - Can wait for pinned tasks, useful for creating IO threads which do no other work. See example/WaitForNewPinnedTasks.cpp and example/WaitForNewPinnedTasks_c.c.

Installing

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

Using enkiTS

C++ usage

full example in example/ParallelSum.cpp
C example in example/ParallelSum_c.c

#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;
}

C++ 11 lambda usage

full example in example/LambdaTask.cpp

#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;
}

Task priorities usage in C++

full example in example/Priorities.cpp
C example in example/Priorities_c.c

// 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;
}

Pinned Tasks usage in C++

full example in example/PinnedTask.cpp
C example in example/PinnedTask_c.c

#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;
}

Dependency usage in C++

full example in example/Dependencies.cpp
C example in example/Dependencies_c.c

#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 i

EnkiTS

Install / Use

README