ZeroAllocJobScheduler 1.1.2

dotnet add package ZeroAllocJobScheduler --version 1.1.2                
NuGet\Install-Package ZeroAllocJobScheduler -Version 1.1.2                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ZeroAllocJobScheduler" Version="1.1.2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ZeroAllocJobScheduler --version 1.1.2                
#r "nuget: ZeroAllocJobScheduler, 1.1.2"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install ZeroAllocJobScheduler as a Cake Addin
#addin nuget:?package=ZeroAllocJobScheduler&version=1.1.2

// Install ZeroAllocJobScheduler as a Cake Tool
#tool nuget:?package=ZeroAllocJobScheduler&version=1.1.2                

ZeroAllocJobScheduler

Maintenance Nuget License C#

A high-performance alloc-free C# job scheduler.
Schedules and executes jobs on a set of worker threads with automatic pooling of internal handles.

Usage


public class HeavyCalculation : IJob
{
  public void Execute()
  {
    Thread.Sleep(50);  // Simulate heavy work
    Console.WriteLine("Done");
  }
}

// Create a new Scheduler, which you should keep the lifetime of your program. This is the only API call that will allocate or generate garbage.
var scheduler = new JobScheduler(new JobScheduler.Config()
{
    // Names the process "MyProgram0", "MyProgram1", etc.
    ThreadPrefixName = "MyProgram",

    // Automatically chooses threads based on your processor count
    ThreadCount = 0,

    // The amount of jobs that can exist in the queue at once without the scheduler spontaneously allocating and generating garbage.
    // Past this number, the scheduler is no longer Zero-Alloc!
    // Higher numbers slightly decrease performance and increase memory consumption, so keep this on the lowest possible end for your application.
    MaxExpectedConcurrentJobs = 64,

    // Enables or disables strict allocation mode: if more jobs are scheduled at once than MaxExpectedConcurrentJobs, it throws an error.
    // Not recommended for production code, but good for debugging allocation issues.
    StrictAllocationMode = false,
});

// You need to pool/create jobs by yourself. This will, of course, allocate, so cache and reuse the jobs.
var firstJob = new HeavyCalculation();  
var firstHandle = scheduler.Schedule(firstJob); // Schedules job locally

scheduler.Flush();                              // Dispatches all scheduled jobs to the worker threads
firstHandle.Complete();                         // Blocks the thread until the job is complete.

// Call Dispose at program exit, which shuts down all worker threads
scheduler.Dispose();                

Dependencies

To set a sequential dependency on a job, simply pass a created JobHandle to JobScheduler.Schedule(job, dependency).

var handle1 = scheduler.Schedule(job1);
var handle2 = scheduler.Schedule(job2, handle1);    // job2 will only begin execution once job1 is complete!
scheduler.Flush();

Multiple dependencies

Use Scheduler.CombineDependencies(JobHandle[] handles) to get a new handle that depends on the handles in parallel. That handle can then be passed into future Schedule call as a dependency itself!

// You must create the array of handles, and handle caching/storage yourself.
JobHandle[] handles = new JobHandle[2];

handles[0] = Scheduler.Schedule(job1);
handles[1] = Scheduler.Schedule(job2);
JobHandle combinedHandle = Scheduler.CombineDependencies(handles);          // Combines all handles into the array into one

var dependantHandle = Scheduler.Schedule(job3, combinedHandle);             // job3 now depends on job1 and job2.
                                                                            // job1 and job2 can Complete() in parallel, but job3 can only run once both are complete.

dependantHandle.Complete();                                                 // Blocks the main thread until all three tasks are complete.

Bulk complete

Rather than using CombineDependencies(), if you just need to block the main thread until a list of handles are complete, you can use this syntax:

JobHandle.CompleteAll(JobHandle[] handles);                     // Waits for all JobHandles to finish, and blocks the main thread until they each complete (in any order)
JobHandle.CompleteAll(List<JobHandle> handles);

Or, if you don't want to maintain a list or array, you can just call handle.Complete() on all your handles, in any order.

Parallel-For support

Instead of IJob, you may extend your class from IJobParallelFor to implement foreach-style indexing on a job. This is useful for when you have very many small operations, and it would be inefficient to schedule a whole job for each one; for example, iterating through a giant set of data.

Define an IJobParallelFor like so:

public class ManyCalculations : IJobParallelFor
{
  // Execute will be called for each i for the specified amount
  public void Execute(int i)
  {
    // ... do some operation with i here
  }

  // Finish will be called once all operations are completed.
  public void Finish()
  {
    Debug.Log("All done!");
  }

  // BatchSize is a measure of how "complicated" your operations are. Detailed below.
  public int BatchSize => 32;

  // Restrict the number of spawned jobs to decrease memory usage and overhead. Keep this at 0 to use the Scheduler's number of active threads (recommended).
  public int ThreadCount => 0;
}

Run your IJobParallelFor with this syntax:

var job = new ManyCalculations();
var handle = scheduler.Schedule(job, 512); // Execute will be called 512 times


However, there are several caveats:

  • Don't overuse IJobParallelFor. In general, over-parallelization is a bad thing. Only schedule your job in parallel if it is truly iterating a huge amount of times, and make sure to always profile when dealing with multithreaded code.
  • You must choose a sane BatchSize for the work inside your job. If you have very many small tasks that complete very quickly, a higher batch size will dispatch more indices to each thread at once, minimizing scheduler overhead. On the other hand, if you have complicated (or mixed-complexity) tasks, a smaller batch size will maximize the ability for threads to use work-stealing and thus might complete faster. The only way to know what batch size to use is to profile your code and see what's faster!
  • Scheduling just a single IJobParallelFor actually schedules ThreadCount jobs on the backend, decreasing the jobs pool. If you make a lot of these, the amount of jobs in play could quickly increase. For example, on a 16-core CPU, with default settings, spawning 8 IJobParallelFor would spawn 128 jobs on the backend. The scheduler can certainly handle it, but you'll probably want to keep an eye on MaxExpectedCurrentJobs if you want to keep the scheduler truly zero-allocation.
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.1

    • No dependencies.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on ZeroAllocJobScheduler:

Package Downloads
Arch

A high performance c# net.6 and net.7 archetype based ECS ( Entity component system ).

ABEngine.Arch

A high performance c# net.6 and net.7 archetype based ECS ( Entity component system ).

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on ZeroAllocJobScheduler:

Repository Stars
genaray/Arch
A high-performance C# based Archetype & Chunks Entity Component System (ECS) with optional multithreading.
Version Downloads Last updated
1.1.2 8,047 3/13/2024
1.1.1 293 11/22/2023
1.0.2 10,253 11/12/2022
1.0.1 1,230 11/12/2022
1.0.0 318 11/12/2022

Added dependencies.
Several improvements and bug fixes.