Managing Coroutines in Unity Using a Job System

Coroutines are a powerful feature available to Unity Developers. Combined with the Unity API, coroutines can used to create animations, load assets, perform web requests and much more. Yet, as your project progresses, it becomes harder to manage all the different types of coroutines. What about managing coroutines in Unity using a specialized job system?

What are Coroutines in Unity?

Coroutines are available to Unity Developers. As opposed to regular methods in C#, coroutines allow you to create methods that execute over time. This means the method is executed while the game is running, not blocking the next frame from being rendered. In Unity, they are used to perform asynchronous work such as web requests, loading levels and even managing complex animations.

How to Manage Coroutines in Unity?

One way of easily managing coroutines in Unity is by controlling them through a Job System or Job Manager. If you are familiar with the default Job System included in Unity then you might already be fully aware of its features and benefits. If not, then all you need to know is that a Job System is a system that processes little tasks. These tasks are usually referred to as Jobs and can be executed in a predetermined order. Similar to how a Job System manages a set of multithreaded jobs, we can create our own system to manage coroutines.

Using Coroutines With The Unity Job System

Of course, you might ask why not just utilize the already existing Job System for this purpose? Well, that’s because the standard Job System is very specialized. Its main purpose is that of processing a lot of data in a multithreaded way. Unfortunately, at this point in time, coroutines are definitely not supported and chances are slim they will ever be. A detailed explanation is beyond the scope of this article so we will not be covering this.

For now, it’s time to roll up our sleeves as we start creating our very own Job System!

Creating a Design for the Job System

Before we start, we need to think about the design of the system for a moment. Simply put, we want to submit jobs to a manager that executes them for us. Next to that, we want to have more control over the execution order of each job. In the system that we’ll be developing we came up with the following design:

Class	Description
JobManager	This is the class to which we can submit jobs to perform. Developers are able to queue jobs, run them immediately and control their execution order based on priority. The execution will all be handled by the JobManager.
Job	This class will actually be the job that we are executing and contains the specialized logic (such as a coroutine). It also contains information about the priority and naming of the job. The naming could be used for debugging purposes.
JobHandle	To facilitate an extra layer of abstraction between the JobManager and the Job classes, we’ll be creating a JobHandle class that will act as a mediator between them. It also holds information about the status of the job, meaning whether it is scheduled, active or completed. The main reasoning behind this is that in our system we don’t want to expose methods that change the status of a job directly

Design of our Job System

Constants for the Job System

In order for the Job System to successfully apply a priority and a status to each job, we need to define a pair of constants. We implement these as a pair of Enums so they can be more easily expanded on later. Next to that, using enums makes it easier for developers to intuitively understand the code. Finally, for the JobPriority Enum we introduce a default value that corresponds to the Normal Priority. This value will be set as the default priority for each job.

Constants.cs

public enum JobPriority
{
    Low = 0,
    Normal,
    Medium,
    High,
    Default = Normal
}
 
public enum JobStatus
{
    None = 0,
    Scheduled,
    Active,
    Complete
}

The JobHandle Class

Whenever a job is submitted to our Job System, the JobManager will create a new handle for it. Below you can find the code that implements the JobHandle class. As can be seen, it is pretty much a wrapper around our Job class. Also, it adds extra functionality in order to get and set the state of a job.

JobHandle.cs

public class JobHandle
{
    private JobStatus m_Status = JobStatus.None;
    private Job m_Job = null;
 
    public JobHandle(Job job)
    {
       m_Job = job;
    }
 
    public IEnumerator RunJob()
    {
        return m_Job.Run();
    }
 
    public string GetIdentifier()
    {
        return m_Job.GetIdentifier();
    }
 
    public JobPriority GetPriority()
    {
        return m_Job.GetPriority();
    }
 
    public JobStatus GetStatus()
    {
        return m_Status;
    }
 
    public void ChangeStatus(JobStatus status)
    {
        m_Status = status;
    }
}

The abstract Job Class

In the snipper below, you can find the definition of the abstract Job class. By making it abstract, we force developers to implement a specialized version of the class. As a result, the job has to be implemented before it can be submitted to the JobManager.

Job.cs

public abstract class Job
{
    private JobPriority m_Priority = JobPriority.Default;
    private string m_Identifier = string.Empty;
    private JobHandle m_Handle = null;
 
    public abstract IEnumerator Run();
 
    public Job SetPriority(JobPriority priority)
    {
        m_Priority = priority;
        return this;
    }
 
    public JobPriority GetPriority()
    {
        return m_Priority;
    }
 
    public Job SetIdentifier(string identifier)
    {
        m_Identifier = identifier;
        return this;
    }
 
    public string GetIdentifier()
    {
        return m_Identifier;
    }
 
    public void SetHandle(JobHandle handle)
    {
        m_Handle = handle;
    }
 
    public JobStatus GetStatus()
    {
        if(m_Handle == null)
        {
            return JobStatus.None;
        }
        else
        {
            return m_Handle.GetStatus();
        }
    }
}

Another thing you may have noticed in the code is that there are several Setter methods which return the instance of the Job. This is done so it becomes easier for developers to initialize the job using chaining. Below you can find a snippet where we create a new ExampleJob and initialize it. During the initialization we set its identifier and priority values. More usage examples can be found at the end of this article.

new ExampleJob()
    .SetIdentifier("The Best job")
    .SetPriority(JobPriority.Medium);

As mentioned before, to submit a job, a developer has to implement the abstract Run() method that actually will be run inside the coroutine. We will now show some examples of specialized jobs.

Specialized DelayJob Class

The first specialized job implementation we will be looking at is the DelayJob class. Even though this class does nothing particularly useful, it might give you more insight into what is actually going on in the code.

Now, if you have worked with coroutines before, you might recognize the WaitForSeconds() method exposed through the Unity API. Quite simply, the main purpose of this job is to let the Job Manager run a job for a specified duration. The job will be considered complete after the Run() method finishes execution.

DelayJob.cs

public class DelayJob : Job
{
    private float m_Duration = 0.0f;
 
    public DelayJob(float duration)
    {
        m_Duration = duration;
    }
 
    public override IEnumerator Run()
    {
        yield return new WaitForSeconds(m_Duration);
    }
}

Specialized WebRequestJob Class

In contrast, the WebRequestJob class provides a more practical example of what a job can be. In this case, we are performing a WebRequest to a specified address and return its response. The job will be considered complete once the created UnityWebRequestAsyncOperation has been completed and the response has been logged to the debug console..

WebRequestJob.cs

public class WebRequestJob : Job
{
    private string m_Address = string.Empty;
 
    public WebRequestJob(string address)
    {
        m_Address = address;
    }
 
    public override IEnumerator Run()
    {
        UnityWebRequestAsyncOperation operation = UnityWebRequest.Get(m_Address).SendWebRequest();
 
        while(!operation.isDone)
        {
            yield return null;
        }
 
        Debug.Log(operation.webRequest.downloadHandler.text);
    }
}

AnonymousJob Class

Finally, we have the AnonymousJob class which is our equivalent of an Anonymous Method in C#. Using this job, we can simply pass in a function (An IEnumerator in this case) through the constructor and use it as a coroutine. When ordered by the JobManager, the job will execute the given function as a coroutine.

AnonymousJob.cs

public class AnonymousJob : Job
{
    private IEnumerator m_JobFunction = null;
 
    public AnonymousJob(IEnumerator jobFunction)
    {
        m_JobFunction = jobFunction;
    }
 
    public override IEnumerator Run()
    {
        yield return m_JobFunction;
    }
}

The JobManager Class

Now, the JobManager is the most complex class in our system. As it’s name suggests, this is the actual class that will be managing our Coroutines inside Unity. Because of this, we will try to go into a little more detail to explain its inner workings. One important point to make is that we have implemented it as a UnityEngine.MonoBehaviour which gives us access to the Update() method. Using this method, we can schedule and check for jobs that have been completed over time.

Next to that, the class manages two lists. The ScheduledJobs list holds a collection of scheduled jobs whereas the ActiveJobs list holds the jobs that are currently being executed. You will also see that we have clamped the number of ‘concurrent’ jobs to 2. This means that at any given point, we have a maximum of 2 jobs running.

Whenever we queue a new job, we add it through a job handle to our ScheduledJobs list. Next, if there are currently less than 2 jobs active, it means we can move some jobs from the ScheduledJobs list and add them to the ActiveJobs list. Once jobs are in the active list, they can be executed until completion.

JobManager.cs

public class JobManager : MonoBehaviour
{
    private List<JobHandle> m_ScheduledJobs = new List<JobHandle>();
    private List<JobHandle> m_ActiveJobs = new List<JobHandle>();
    private int m_MaxJobs = 2;
 
    public void Queue(Job job)
    {
        JobHandle handle = new JobHandle(job);
        handle.ChangeStatus(JobStatus.Scheduled);
 
        m_ScheduledJobs.Add(handle);
    }
 
    public void Queue(IEnumerator jobFunction)
    {
        Queue(new AnonymousJob(jobFunction));
    }
 
    public void Run(Job job)
    {
        StartJob(new JobHandle(job));
    }
 
    public void Run(IEnumerator jobFunction)
    {
        Run(new AnonymousJob(jobFunction));
    }
 
    public void Update()
    {
        ExecuteJobs();
    }
 
    public int GetActiveJobCount()
    {
        return m_ActiveJobs.Count;
    }
 
    public bool HasActiveJobs()
    {
        return GetActiveJobCount() > 0;
    }
 
    protected IEnumerator BaseJobFunction(JobHandle jobHandle)
    {
        m_ActiveJobs.Add(jobHandle);
        jobHandle.ChangeStatus(JobStatus.Active);
 
        Debug.LogFormat("Starting job '{0}'...", jobHandle.GetIdentifier());
        yield return jobHandle.RunJob();
        Debug.LogFormat("Completed job '{0}'", jobHandle.GetIdentifier());
 
        m_ActiveJobs.Remove(jobHandle);
        jobHandle.ChangeStatus(JobStatus.Complete);
    }
 
    private void StartJob(JobHandle handle)
    {
        StartCoroutine(BaseJobFunction(handle));
    }
 
    private void ExecuteJobs()
    {
        if(m_ActiveJobs.Count < m_MaxJobs)
        {
            if(m_ScheduledJobs.Count > 0)
            {
                m_ScheduledJobs = m_ScheduledJobs.OrderByDescending(jobHandle => jobHandle.GetPriority()).ToList();
 
                JobHandle firstJob = m_ScheduledJobs.First();
 
                StartJob(firstJob);
 
                m_ScheduledJobs.Remove(firstJob);
            }
        }
    }
}

Also, our JobManager class features a BaseJobFunction() that acts as a coroutine in which a job coroutine will run. This is useful because it allows us to set the state of the job outside the job itself. Without it, we would need to add unnecessary implementation details to the Job classes themselves.

Finally, we want to cover the priority sorting which we do every time the system detects that it can schedule a new job. Using the OrderByDescending() method from System.Linq, we are able to update the list of scheduled jobs based on their priority. Important to note is that we could also do this every time we queue a new job. However, in our implementation it is possible to change the priority of the job after it has been scheduled. This is useful as it allows more flexibility in reordering of the jobs if needed.

Example of using the Coroutine Job System

Now that every element has been implemented correctly, we can start using our new system. In the snippet below you can find a case where we schedule 3 jobs and try executing 1 job immediately.

When running this, you will find that the Unity3D Job will run first. This job is then followed by the Delay Job, the Google Job and finally the Microsoft Job. This is because the Unity3D Job is forced to run and the Delay Job has the highest priority. After that, the JobManager will simply execute the jobs in the order they have been submitted. As you can see, managing coroutines in Unity becomes very easy!

JobExamples.cs

public class JobExamples : MonoBehaviour
{
    [SerializeField]
    private JobManager m_JobManager = null;
 
    private void Awake()
    {
        m_JobManager.Queue(new WebRequestJob("http://www.google.com/")
            .SetIdentifier("Google Job"));
 
        m_JobManager.Queue(new DelayJob(3.0f)
            .SetIdentifier("Delay 3.0s")
            .SetPriority(JobPriority.High));
 
        m_JobManager.Queue(new WebRequestJob("http://www.microsoft.com/")
            .SetIdentifier("Microsoft Job"));
 
        m_JobManager.Run(new WebRequestJob("http://unity3d.com/")
            .SetIdentifier("Unity3D Job"));
    }
}

Another way to submit jobs to the system is by using the Anonymous overload that we created earlier. Rather than creating a specialized class implementation for a job, we can simply put in any coroutine that we want to execute. In the sample below, you can see how this is done: