Property Dependency

Dependency

The ECS-related data dependencies of the system.

Declaration

protected JobHandle Dependency { get; set; }

Property Value

Type	Description
JobHandle

Remarks

Before OnUpdate(), the Dependency property represents the combined job handles of any job that writes to the same components that the current system reads -- or reads the same components that the current system writes to. When you use [Entities.ForEach] or Job.WithCode, the system uses the Dependency property to specify a job’s dependencies when scheduling it. The system also combines the new job's JobHandle with Dependency so that any subsequent job scheduled in the system depends on the earlier jobs (in sequence).

The following example illustrates an OnUpdate() implementation that relies on implicit dependency management. The function schedules three jobs, each depending on the previous one:

[BurstCompile]
partial struct JobOne : IJobEntity
{       
    public void Execute(in AComponent c)
    {
        /*...*/
    }
}
[BurstCompile]
partial struct JobTwo : IJobEntity
{
public void Execute(in AnotherComponent c)
{
/.../
}
}
[BurstCompile]
struct JobThree : IJob
{
[DeallocateOnJobCompletion] public NativeArray<int> Result; // Automatically disposed when job completes
public void Execute()
    {
        /*...*/
    Result[0] = 1;
}

}
protected override void OnUpdate()
{
// Implicit dependency chaining: each ScheduleParallel updates SystemBase.Dependency
new JobOne().ScheduleParallel();
new JobTwo().ScheduleParallel();
// Final job depends on previous via implicit Dependency and disposes its NativeArray automatically
var jobThree = new JobThree
    {
    Result = new NativeArray<int>(1, Allocator.TempJob)
};
jobThree.Schedule();

}

You can opt out of this default dependency management by explicitly passing a JobHandle to [Entities.ForEach] or Job.WithCode. When you pass in a JobHandle, these constructions also return a JobHandle representing the input dependencies combined with the new job. The JobHandle objects of any jobs scheduled with explicit dependencies are not combined with the system’s Dependency property. You must set the Dependency property manually to make sure that later systems receive the correct job dependencies.

The following OnUpdate() function illustrates manual dependency management. The function uses two [Entity.ForEach] constructions that schedule jobs which do not depend upon each other, only the incoming dependencies of the system. Then a Job.WithCode construction schedules a job that depends on both of the prior jobs, who’s dependencies are combined using JobHandle.CombineDependencies. Finally, the JobHandle of the last job is assigned to the Dependency property so that the ECS safety manager can propagate the dependencies to subsequent systems.

[BurstCompile]
partial struct JobOne : IJobEntity
{
    public void Execute(in AComponent c)
        {
            /*...*/
    }
}
[BurstCompile]
partial struct JobTwo : IJobEntity
{
public void Execute(in AnotherComponent c)
{
/.../
}
}
[BurstCompile]
struct JobThree : IJob
{
[DeallocateOnJobCompletion] public NativeArray<int> Result; // Automatically disposed when job completes
public void Execute()
{
    /*...*/
    Result[0] = 1;
}

}
protected override void OnUpdate()
{
// Explicitly opt-out of implicit chaining by scheduling with incoming system Dependency
JobHandle One = new JobOne().ScheduleParallel(this.Dependency);
JobHandle Two = new JobTwo().ScheduleParallel(this.Dependency);
JobHandle intermediateDependencies =
    JobHandle.CombineDependencies(One, Two);

var jobThree = new JobThree
    {
    Result = new NativeArray<int>(1, Allocator.TempJob)
};

JobHandle finalDependency = jobThree.Schedule(intermediateDependencies);

// Propagate combined dependency to subsequent systems
this.Dependency = finalDependency;

}

You can combine implicit and explicit dependency management (by using JobHandle.CombineDependencies); however, doing so can be error prone. When you set the Dependency property, the assigned JobHandle replaces any existing dependency, it is not combined with them.

Note that the default, implicit dependency management does not include IJobChunk jobs. You must manage the dependencies for IJobChunk explicitly.