Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

IJobFor

An interface that represents a job that performs the same independent operation for each element of a native container or for a fixed number of iterations.
Read time 2 minutesLast updated 4 days ago

Definition

  • Type: Interface
  • Namespace: Unity.Jobs
  • Assembly: UnityEngine.ManagedKernelModule
[JobProducerType(typeof(IJobForExtensions.ForJobStruct<>))]public interface IJobFor

Remarks

This job type has the following options to schedule work:
  • IJobForExtensions.RunByRef runs the job on the main thread and finishes immediately.
  • IJobForExtensions.ScheduleByRef schedules the job to run on a worker thread or the main thread, but indicates that the work should happen in a single thread. This option allows for work to be done off the main thread, but the work is performed sequentially.
  • IJobForExtensions.ScheduleParallelByRef schedules the job to run asynchronously, distributing the work across multiple worker threads. This scheduling option can give the best performance, but race conditions can occur if the job writes to shared or global data without proper synchronization.
Execute(int index)
is executed once for each index from 0 to the provided length.
RunByRef
and 
ScheduleByRef
guarantee that the the job's 
Execute(int index)
method is invoked sequentially. 
ScheduleParallelByRef
doesn't invoke the job's 
Execute
method sequentially because it's called from multiple worker threads in parallel to each other.
Each iteration must be independent from other iterations and the safety system enforces this rule for you. The indices have no guaranteed order and are executed on multiple cores in parallel.
Unity automatically splits the work into chunks of no less than the provided 
batchSize
, and schedules an appropriate number of jobs based on the number of worker threads, the length of the array and the batch size. You should choose the batch size based on the amount of work performed in the job. If the batch size is too large, work may not be distributed evenly across the available worker threads. If it's too small, the overhead of fetching new work items may dominate the time it takes to process them. A simple job, for example adding a couple of Vector3 to each other should have a batch size of 32 to 128. However, if the work performed has a large overhead then it's best practice to use a small batch size, for example, a batch size of 1. Work stealing is performed using atomic operations.
You can use the returned 
JobHandle
to check that the job has completed, or pass it to other jobs as a dependency. When you pass a 
JobHandle
as a dependency, it ensures that the jobs are executed one after another on the worker threads.
Additional Resources: IJobForExtensions

Examples

{code Tests/EditModeAndPlayModeTests/Jobs/Assets/DocumentationExamples/ManagedJobDocExamples.cs#ijobfor-apidocs-example}

Methods

Method

Description

ExecutePerforms work against a specific iteration index.