Property Job

Job

Provides a mechanism for defining and executing an [IJob].

Declaration

protected LambdaSingleJobDescription Job { get; }

Property Value

Type	Description
Unity.Entities.CodeGeneratedJobForEach.LambdaSingleJobDescription

Remarks

The Jobs property provides a convenient mechanism for implementing single jobs. Unity uses a compiler extension to convert the job description you create with Job.WithCode into efficient, executable code that (optionally) runs in a background thread.

public partial class RandomSumJob : SystemBase
{
   private uint seed = 1;

   protected override void OnUpdate()
   {
       Random randomGen = new Random(seed++);
       NativeArray<float> randomNumbers
           = new NativeArray<float>(500, Allocator.TempJob);

       Job.WithCode(() =>
       {
           for (int i = 0; i < randomNumbers.Length; i++)
           {
               randomNumbers[i] = randomGen.NextFloat();
           }
       }).Schedule();

       // To get data out of a job, you must use a NativeArray
       // even if there is only one value
       NativeArray<float> result
           = new NativeArray<float>(1, Allocator.TempJob);

       Job.WithCode(() =>
       {
           for (int i = 0; i < randomNumbers.Length; i++)
           {
               result[0] += randomNumbers[i];
           }
       }).Schedule();

       // This completes the scheduled jobs to get the result immediately, but for
       // better efficiency you should schedule jobs early in the frame with one
       // system and get the results late in the frame with a different system.
       this.CompleteDependency();
       UnityEngine.Debug.Log("The sum of "
           + randomNumbers.Length + " numbers is " + result[0]);

       randomNumbers.Dispose();
       result.Dispose();
   }
}

Implement your lambda function inside the Job.WithCode(lambda) function. The lambda function cannot take any parameters. You can capture local variables.

• Schedule() -- executes the lambda function as a single job.
• Run() -- executes immediately on the main thread. Immediately before it invokes Run() the system completes all jobs with a JobHandle in the system Dependency property as well as any jobs with a JobHandle passed as a dependency to Run() as an (optional) parameter.

When scheduling a job, you can pass a JobHandle to set the job's dependencies explicitly and the construction returns the updated JobHandle combining the earlier dependencies with the new job. If you do not provide a JobHandle, the system uses Dependency when scheduling the job, and updates the property to include the new job automatically.

You can use the additional options listed for Entities.ForEach with a Job.WithCode construction.

Capturing variables

You can capture local variables in the lambda function. When you execute the function using a job (by calling Schedule(), ScheduleParallel() or ScheduleSingle() instead of Run()) there are some restrictions on the captured variables and how you use them:

• Only native containers and blittable types can be captured.
• A job can only write to captured variables that are native containers. (To “return” a single value, create a [native array] with one element.)

You can use the following functions to apply modifiers and attributes to the captured [native container] variables, including [native arrays]:

• WithReadOnly(myvar) — restricts access to the variable as read-only.

• WithDisposeOnCompletion(myvar) — indicates that you want captured NativeContainers or types that contain NativeContainers to be Disposed of after your lambda runs.

• WithNativeDisableParallelForRestriction(myvar) — permits multiple threads to access the same writable native container. Parallel access is only safe when each thread only accesses its own, unique range of elements in the container. If more than one thread accesses the same element a race condition is created in which the timing of the access changes the result. See NativeDisableParallelForRestriction.

• WithNativeDisableContainerSafetyRestriction(myvar) — disables normal safety restrictions that prevent dangerous access to the native container. Disabling safety restrictions unwisely can lead to race conditions, subtle bugs, and crashes in your application. See NativeDisableContainerSafetyRestrictionAttribute.

• WithNativeDisableUnsafePtrRestrictionAttribute(myvar) — Allows you to use unsafe pointers provided by the native container. Incorrect pointer use can lead to subtle bugs, instability, and crashes in your application. See NativeDisableUnsafePtrRestrictionAttribute.