tanrye / enkiTS

C++ and C multithreading task scheduler

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Support development of enkiTS through our Patreon

Become a Patron

enkiTS

Build Status for branch: master

enki Task Scheduler

A permissively licensed C and C++ Task Scheduler for creating parallel programs. NEW The master branch now requires C++11 support, A C++98 branch exists for those without access to a C++11 compiler or for ease in porting to pure C, though it may be deprecated in time.

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. The example code requires C++ 11 for chrono.

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 require the pthreads library.

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

  1. mkdir build
  2. cmake ..
  3. either run make or open enkiTS.sln

Project Features

  1. Lightweight - enkiTS is designed to be lean so you can use it anywhere easily, and understand it.
  2. Fast, then scalable - enkiTS is designed for consumer devices first, so performance on a low number of threads is important, followed by scalability.
  3. 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.
  4. Up-front Allocation friendly - enkiTS is designed for zero allocations during scheduling.
  5. Can pin tasks to a given thread - enkiTS can schedule a task which will only be run on the specified thread.
  6. NEW - 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.

Usage

C++ usage:

#include "TaskScheduler.h"

enki::TaskScheduler g_TS;

// define a task set, can ignore range if we only do one thing
struct ParallelTaskSet : enki::ITaskSet {
   virtual void    ExecuteRange(  enki::TaskSetPartition range, uint32_t threadnum ) {
      // 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 (not available on C++98 branch):

#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++ (see example/Priorities_c.c for C example).

// See full example in Priorities.cpp
#include "TaskScheduler.h"

enki::TaskScheduler g_TS;

struct ExampleTask : enki::ITaskSet
{
    ExampleTask( ) { m_SetSize = size_; }

    virtual void ExecuteRange( enki::TaskSetPartition range, uint32_t threadnum ) {
        // 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++ (see example/PinnedTask_c.c for C example).

#include "TaskScheduler.h"

enki::TaskScheduler g_TS;

// define a task set, can ignore range if we only do one thing
struct PinnedTask : enki::IPinnedTask {
    virtual void    Execute() {
      // 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;
}

C usage:

#include "TaskScheduler_c.h"

enkiTaskScheduler*	g_pTS;

void ParalleTaskSetFunc( uint32_t start_, uint32_t end, uint32_t threadnum_, void* pArgs_ ) {
   /* Do something here, can issue tasks with g_pTS */
}

int main(int argc, const char * argv[]) {
   enkiTaskSet* pTask;
   g_pTS = enkiNewTaskScheduler();
   enkiInitTaskScheduler( g_pTS );
	
   // create a task, can re-use this to get allocation occurring on startup
   pTask	= enkiCreateTaskSet( g_pTS, ParalleTaskSetFunc );

   enkiAddTaskSetToPipe( g_pTS, pTask, NULL, 1); // NULL args, setsize of 1

   // 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.
   enkiWaitForTaskSet( g_pTS, pTask );
   
   enkiDeleteTaskSet( pTask );
   
   enkiDeleteTaskScheduler( g_pTS );
   
   return 0;
}

Bindings

Deprecated

The user thread versions are no longer being maintained as they are no longer in use.

Projects using enkiTS

Avoyd

Avoyd is an abstract 6 degrees of freedom voxel game. enkiTS was developed for use in our in-house engine powering Avoyd.

Avoyd screenshot

Imogen

GPU/CPU Texture Generator

Imogen screenshot

ToyPathRacer

Aras Pranckevičius' code for his series on Daily Path Tracer experiments with various languages.

ToyPathTracer screenshot.

License (zlib)

Copyright (c) 2013-2019 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:

  1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgement in the product documentation would be appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.

About

C++ and C multithreading task scheduler

License:zlib License


Languages

Language:C++ 79.5%Language:C 16.9%Language:CMake 3.5%