In the last article we focused on the internals behind Unity’s Coroutines and went in depth on how they work. We covered IEnumerator interface and iterator blocks to get a grasp on how the engine takes care of the coroutine functions. We’ve also managed to list a few problems with the implementation and shortcomings that you can stumble upon if a need to write more complex coroutines arises.
In today’s article, we’re going to present you the idea of Promises and where they originated from.

Callbacks

Most asynchronous operations in Javascript APIs return a result with a callback (in C# terms: an Action delegate) when they finish work. You can explicitly provide a function for those, but to follow asynchronous code easier many decide to implement callbacks using anonymous functions. In theory it does seem like a decent upgrade to our Coroutines. Let’s try to form an example of how to do that in C#:

Not bad! As you can see that actually works fairly well. It gives us a possibility to return a value as well as raise errors and react to them. The problem, however, is the code growing horizontally with more indents as you stack coroutines in a sequence. Also, the error checking has to be done in each and every one of them. Eventually, with more complicated functions you end up in a callback hell. What is that? Well, let’s just copy our coroutine calls and stack four of these bad boys:

Just look at the pyramid shape and all the } and })); at the end. Yikes! You’d also need to get really creative with the names as they have to be unique. In terms of errors, you could probably clean it up a bit if you moved error handling to another function. But it still doesn’t look appealing and here we only have four coroutines stacked. When writing more complex functions or perhaps APIs for your backend services, that number can increase drastically. So, what’s the solution?

Promises

Promises have been popularized by many 3rd party Javascript libraries before getting a native implementation in ES6. It’s interesting to note that the idea itself had been actually researched and introduced in the 70s and 80s. Promises as we know them today were first introduced in a year 1988 by Barbara Liskov and Liuba Shira, but a similar idea came from the functional programming languages years before.

A C# library conforming the Promises/A+ Spec was released a couple of years ago and is a big game changer for managing asynchronous operations. Let’s dive into the code.

A Promise is an object that you return from your asynchronous function immediately, so the caller can await resolution (or error) of your operations. Essentially, it represents a proxy for a value not necessarily known when the promise is created. A Promise can be later resolved or rejected once you complete your actions. This allows asynchronous methods to return values and run like synchronous methods: except instead of the final value, they return a promise of having a value at some point in the future. The best part, however, is the simplicity of stacking them with a simple interface. Here’s how we can redo our first example and implement Promises instead of pure Action delegates:

Much better on the caller side! You get to hide and encapsulate coroutine behavior while getting all the advantages from the promises. With .Then() function you can easily stack new promises in a logical order and handle different result types throughout them. Moreover, with .Catch() you can catch exceptions in all of your promises. If any of the above gets rejected, then the promise chain will get immediately terminated and the code will jump to the nearest catch. Not only that, the catch function actually uses Exception type, so you can also easily throw your own exceptions:

As long as you extend from Exception class you can write your own exceptions, mimicking try…catch behavior. Handle them like this:

Summary

As you can see, Promises provide a great mechanism to handle your asynchronous operations. You can easily throw errors from any of your promises in stack, handle returning values as well as hide the coroutine implementation if you use it while working with Unity. You retain all the powerful aspects of Coroutines in terms of the implementation, but also improve greatly the interface for your complicated APIs and services. The library offers much more than what was covered and we strongly recommend looking up the documentation to see what else it has to offer.
In the final part of the series, we’ll show you a real example of writing a REST API interface using Unity’s Coroutines & Promises to achieve the cleanest code possible.

Continued in Part 3 here.

Every Unity developer should be familiar with Coroutines. For many they are the way to script a lot of asynchronous and time-delayed tasks. If you’re not up to the speed, they’re pretty much special methods that can suspend and resume their execution for any time desired. In practice, they can be perceived as an illusion of concurrent functions (although they have nothing to do with threads!). There are, however, some problems that many programmers stumble upon while using them. Let’s take a closer look.

The internals

So what exactly are Unity’s coroutines under the hood? How do they work? Granted that we don’t have a direct access to Unity’s source code, but gathering evidence from Manual and expanding on the knowledge from C# we can assume this is more or less how they’re done. Let’s lean over this simple example:

You don’t have to be genius to figure out that this will log “Hello there!” in the console and “Hello from future!” after 2 seconds. But how? To understand coroutines one must first look at the function’s signature – more precisely, the returned type. The IEnumerator serves as a way of performing iterations on a collection. It controls moving from one object to the next one in a sequence.

To do it, it declares two very important members: a Current property, which has a reference to the element that enumerator (or a cursor you could say) is currently over, and a MoveNext() function, which moves to the next element whilst calculating the new current value. It also has a Reset() function that sets the enumerator to its initial position, but we’ll skip that.

Now since the IEnumerator is just an interface it doesn’t explicitly specify the Current type (other than it’s an object). We can do whatever we want to calculate the next object. MoveNext() will simply do the job and return false if we end up at the end of a sequence.

Iterator blocks

In pure C# we can easily “implement” this interface in special iterator blocks. In practice, C# compiler converts iterator blocks into state machines. Those are the functions that return the IEnumerator type and use the yield return statement to return the values (yes, multiple ones). Calling that makes the MoveNext() function simply return true and set Current to whatever you’re returning. If you want to stop the enumerator you can just call yield break which makes sure that MoveNext() returns false and terminates the sequence (think of it like break; in a loop). An example:

Compile this on your own and you’ll get the following output:

This example uses the generic interface IEnumerator<T>, but as previously mentioned, you can use the regular one, IEnumerator, where your Current will be of any type. This is exactly what Unity requires in coroutines.

So, with that in mind, we start to get a clearer picture on what Unity actually does with coroutines. StartCoroutine adds the coroutine to some sort of a container. Unity iterates through every executed coroutine in StartCoroutine and performs MoveNext() on those which are ready to continue their work. As shown in the example above, it evaluates expressions between yield return statements and returns a value. If it returns false then it obviously tells Unity to terminate that coroutine (as it simply has just finished). If true, it checks the Current property (remember, non-generic interface!) and sees if there are any familiar types. Remember WaitForSeconds() in the very first example? Unity sees that and pauses the coroutine for seconds specified. In fact, it actually extends from YieldInstruction base type. You’ve also got:

• WaitForEndForFrame, which resumes the coroutine at the end of the frame after all cameras and GUI are rendered
• WaitForFixedUpdate, which waits until next fixed frame rate update function
• Coroutine type itself, which you could use for nest coroutines
• CustomYieldInstruction, introduced to write your own custom yield statements – just extend from that class and override keepWaiting property

So where’s the catch?

It goes without saying that with these simple types you can suddenly script some time-based game logic as well as asynchronous events very easily. You can show a UI notification after few seconds in just a few lines of code without any dirty timers. Not only that, but you can even yield return the UnityWebRequest.Send() function and pause your function until you get a HTTP response. “What’s the problem with that then?”, you may ask.

First of all, you can’t easily return a value from coroutines. The signature needs to return IEnumerator to keep a track of when and where to resume your method. Second of all, there is no exception handling at the coroutine level. You can’t use try…catch block with a yield statement in it. You would have to basically try catch every non-yield expression in your coroutine. But what if there are multiple expressions segregated with multiple yields? Or maybe you’d like to stack coroutines one after another. But how to communicate to the coroutines down below the pipe that the top one has encountered a runtime exception?

Fortunately, there is a solution. In the next part we’ll take a look at Promises and their origin from Javascript. Read it here.