Unity Future .NET Development Status

A vote for something shorter. Please, my own code is already verbose enough. Official APIs should be concise and short if possible.

 

I really hope that a shorter name like UnityTask for example will be used instead of AwaitableCoroutine.

 

Everyone is entitled to their opinion and I respect that but for the love of whatever god I will never understand the itch for shorter code.... :shrugh:

 

It is not just about shorter code, it is about sensible code. AwaitableCoroutine (in my opinion) gives the false impression that it is related to Coroutine. Something like UnityTask, on the other hand, immediately makes it clear to the reader that it is something associated with Task but with Unity things added on top.

 

@goldbug if you go up in the forum enough, back in ancient times, I believe it was stated that Unity working with async is its own thing: still works with UniTask, UniTask may still bring added benefit, but the fundamentals of working with async, what you would normally do with UniTask, can now be done with Unity.

 

How do you handle cancellation tokens? Do Objects now have a (public) “isDestroyed” token, or does AwaitableCoroutine fill in some magic token we can’t change?
My biggest wish for this system was the ability to say “well cancel this task if other object dies”.

I suppose since it now just works with async, worst case we can wrap AwaitableCoroutine and provide a custom token, but it would be nice to know if Unity provides any quick and easy handles.

p.s. +1 on renaming to UnityTask, AwaitableCoroutine is a mouthful

 

In 2022.2, you can get the token from a MonoBehaviour.
https://docs.unity3d.com/2022.2/Doc...e/MonoBehaviour-destroyCancellationToken.html

 

@Laicasaane thanks can’t wait!

@simon-ferquel-unity any reason why it’s not in Object? Not judging, but it does seem strange that if it’s Object.Destroy, it’s not Object.destroyCancellationToken, not to mention leaving money on the table. I’m just curious why this decision was made: as I understand it, I still wouldn’t be able to say (minus own implementation) cancel my task if MeshRenderer is destroyed, or GameObject dies, or hell ScriptableObject gets unloaded.

 

Having a CancellationToken for all UnityEngine.Object-derived classes would be pretty useful, you could then use the Register method to receive a callback for when the object is destroyed: something you could not do previously without hooking C++ functions within the engine. I know I've needed such functionality before when loading assets at runtime (for example, an AudioClip that reads PCM data from a stream -- I want to dispose of that stream if the clip is destroyed).

 

I think you should explain more about its nature so we can brainstorm a better name if any.

 

At least you could rename it to AsyncCoroutine which is something not as painful to type out. "Awaitable" has letters all over keyboard for common use really horrible choice imo

Does this mean it is impossible to switch this Coroutine to background thread like Unitask allows you to?

 

How about the .ConfigureAwait(false) behaviour after the Task.Run ?

 

Does this mean we could sync background thread with Update cycle using wait await NextFrame() or something?

Also are you planning to provide APIs to come back to main thread like UniTask does?

Code (CSharp):

1.  
2. // Multithreading, run on ThreadPool under this code
3. await UniTask.SwitchToThreadPool();
4.  
5. /* work on ThreadPool */
6.  
7. // return to MainThread(same as `ObserveOnMainThread` in UniRx)
8. await UniTask.SwitchToMainThread();
9.  

If not I hope it could at least be possible to implement yourself? Not like I couldn't survive without this feature but it is rather handy when dealing with file IO like saving the game

 

That's a good reason. But because I'm a stickler, I'm gonna throw up one more ball.

What if you do this?

Code (CSharp):

1. internal interface ICancellable
2. {
3.     void Cancel();
4. }
5.  
6. internal struct EmptyCancellable : ICancellable
7. {
8.     public void Cancel() {}
9. }
10.  
11. internal struct Cancellable : ICancellable
12. {
13.     public CancellationTokenSource source;
14.  
15.     public Cancellable(CancellationTokenSource source)
16.     {
17.         this.source = source;
18.     }
19.  
20.     public void Cancel() => source.Cancel();
21. }
22.  
23. public void Object
24. {
25.     private static readonly EmptyCancellable emptyCancellable; // small optimization to only create the EmptyCancellable once. May be part of EmptyCancellable.
26.  
27.     private ICancellable _cancellable = emptyCancellable;
28.     public CancellationToken destroyCancellationToken
29.     {
30.         if (_cancellable is not Cancellable)
31.         {
32.             _cancellable = new Cancellable(new CancellationTokenSource()); // pseudo-code
33.         }
34.         return _cancellable.source.Token; // DEFINITELY pseudo-code :')
35.     }
36.  
37.     void InternalOnDestroy()
38.     {
39.         _cancellable.Cancel();
40.     }
41. }

Main points:
- Only create the CancellationToken when it's requested.
- No branching or implementation costs (minus a single empty method call) when it's not.

This would of course be weird if called after the object has been destroyed / in an OnDestroy, but that's why throwing was invented. Or perhaps the token could just be set to true from the get go. Either way, I don't think it's a crime if it's well documented: Renderer.material is of a similar beast, where it does secret dirty-work under the hood.

 

How about AsyncCoroutine? As much as it pains me, UnityTask is off the table if the underlying API is definitely not tasks, that would just lead to confusion about its implementation. But if it's not Task, yet it is async, then AsyncCoroutine seems perfect for it. It seems that what is said here is exactly what you're doing. Even though async is awaitable, awaitable is not async, and AwaitableCoroutine seems to dwindle on its scope.

I wouldn't worry about it, you have an excellent community both on YouTube and in the forums, as well as great Unite talks highlighting new features for those who will teach the next generation. Heck, the roadmaps too now!

Plus, can't say I disagree with this:

 

After reading the rationale, AwaitableCoroutine sounds even better. Naming in code/apis should never be conditioned by the """""cost"""" of typing it... that's an 80's thing when we coded in VIM/Emacs... on any modern IDE we will only type "awa" and autocomplete anyway...

Clarity and explicitness should be almost always desired.

 

That's fair enough, but the async keyword in C# world still signals "not run on the main thread", which is as I understand the fundamental difference between Coroutine.

So maybe what would be really cool is just

async Coroutine DoSomethingAsync(CancellationToken token)

, and let the async keyword just specify its awaitable-ness.

But, alas, that name already exists in the UnityEngine namespace. Yet since we use it with the async keyword and you don't need to specify its Co-ness anymore maybe just...

async Routine DoSomethingAsync(CancellationToken token)

I don't even know how I feel about that myself :|

Nevertheless, I still think

async AwaitableCoroutine

is ugly for the same reason, you don't need to specify Awaitable if it's an async method, the compiler already tells us that.

EDIT:
And yes, I'm an idiot,

async AsyncCoroutine

would have been ugly in hindsight as well

 

By the by thanks for all the transparency throughout, I know I can get a bit direct in these discussions but I really appreciate them, the attention and involvement from the actual Unity team behind it is why this is the single greatest thread on this forum.

 

Autocomplete is slow and typing by hand if you know what you want to type is usually faster. At least in visual studio it is

UniRoutine?
I dunno, but the fact that there's probably already going to be 'async' near the name is a good touch, didn't think of it... Somehow

 

So I'll be throwing out some vocabulary so we can decide on a name:

• Job ( Unity's Job System is "async" )
• Timeline ( Another thread timeline )
• Path ( Same as timeline, but shorter )
• Execution ( What a CPU thread does )
• Process ( Same as execution, but shorter )
• Operation ( I think Unity has a class called AsyncOperation for the asychrony of SceneManager )
• Objective ( Similiar to Operation )
  
• Parallel ( C#'s threaded model )
• Stereo ( Instead of a mono threaded model )
• Independent ( A thread that doesn't rely on timeDelta or Object destruction, but is independent )
• Free ( Same as independent, but shorter )
  
• Unbound ( Similiar to independent, but shorter )
  
• Thread ( No need for explanation... right? Right?? )
• Pause ( As it can be awaited or the thread delayed )
• Seperation ( Seperated from the main thread )

Let's hope we can find a good name together that is ( hopefully ) rather short...

 

A compromise; AsyncRoutine

 

This. A thousand times this. Coroutines in Unity are a very specific implementation of async. They have their own manual page that describes what they are and how to use them.

"Coroutine" means something extremely specific within Unity and yet you are attempting to widen its meaning with the "AwaitableCoroutine" term.

DO NOT DO THIS.

Sticking "Coroutine" in the name here will drive no end of confusion for your users. The very first thing that you'll have to add to any documentation on the subject is "Despite the name, AwaitableCoroutine is only vaguely related to Unity's Coroutine implementation" and then you'll have to dig into what makes them different.

Please nip this silliness in the bud.

Any of those are better than the existing term. To restate:

• UnityAwaitable
• UnityFuture
• UnityPromise

are ALL dramatically preferable to "AwaitableCoroutine". Personally (and without any solid understanding of how they're used yet), I think the best of the options is the first. Using the terms "Future" or "Promise" may also feel misleading to folks coming from different language backgrounds (Python/JavaScript/etc.). If you're making something Unity-specific and this something boils down to "can be awaited" then "UnityAwaitable" sounds like an extremely reasonable name.

Even this is preferable to AwaitableCoroutine or AsyncCoroutine.

Excise the term "Coroutine" from this as fast as possible. You will do all of us a disservice by leaving it in.

 

Honestly, I agree!

By using the term Coroutine you are defining smth. that was already doing a task synchronously, but has another Routine which will occur later.
E.g. Cooking an Egg leaving it, to go cut some tomatoes, but if one side of the eggs are finished you return to the eggs and leave the tomatoes.

So a proper new name kind of makes more sense especially when Async and Coroutines are 2 totally different ways to delay execution.

 

Gonna second what's been said above here.

I have on notifications for this thread, but I don't really care much about async/await, so I kinda skimmed/skipped all of the posts about this feature.

I was totally assuming that it was some kind of native interoperability between async/await and Coroutine. So, yeah, don't name it that. At least, save the community from having to spend one million hours and way too much pain teaching people the difference.

 

To this I disagree though!
First of all why do we need the Unity name in this implementation? Aren’t namespaces designed to identify from which company/group a class is coming from? Also we have Coroutines not UnityCoroutines!

Also

Code (CSharp):

1. await new Awaitable()

seems super silly imo…

Like if we’re using an obviously asynchronous method then do we really need to specify that it is awaitable?

 

It sounds like you don't "disagree" with those name suggestions so much as you take issue with the names in general, yeah?

I see your concerns/points but I will suggest that there's precedence in UnityEvent. I'm not trying to suggest that "UnityEvent" is some sort of perfect name, but it does make the point that it's a Unity-specific event implementation. The purpose of "Unity" in that name is to disambiguate from another standard implementation (as well as improve searchability with tools like grep).

In this case, you could argue that "C# does not define Promise or Future". To that I would suggest "well, not yet". Those concepts are pretty common across multiple languages and being able to search the web for "unityfuture" would be preferable to "unity future".

Even if Unity decided to use something like UnityEngine.UnityFuture as the type name, you could locally rename it with something like:

Code (CSharp):

1. using FutureInt = UnityEngine.UnityFuture<int>;

if you're truly afraid of typing out the "Unity" prefix the handful of times you'd need this.

My point is that it I would basically prefer UnitySomething to anything with the term "coroutine" in it.

I guess that's fair? I'm not especially partial to any of those names myself. I just really, really hope that "coroutine" is removed from whatever they go with because that is straight-up garbage.

 

I don't know if that's true, because Coroutine is still the thing that it is in the background, and including "Coroutine" in the name specifies that. Even worse, because I'm a sick broken man, after mulling it over I'm now back on

AsyncCoroutine

as it would be similar to how they added

IAsyncEnumerable

to C#. But then

AsyncRoutine

might be better because a Coroutine is redundant if it's already async, but then again if it wouldn't be async it would still be a Coroutine so maybe the name is valid... oh brother

But if not... then I think

UnityTask

would be the best fit. Purely going by the "don't overthink it"-principle, that's the name everyone started suggesting before there was even discussion about it, so it seems to me that

UnityTask

was already in peoples minds before you even explained what any of it did. That's no silver bullet, but it matters. As well:

I could get behind the logic of "yeah it's a Task but specifically implemented with Unity in mind, hence UnityTask", and that the "Unity implementation part" may be Coroutines is neither here nor there.

Truly, just make

NextFrame

and friends Tasks so we can sidestep this naming-business altogether XD T_T

 

Mmmmmm I think this naming thing is a little offtopic, but not unproductive nor undesirable in itself. It might be useful to move to a different thread?

As for the naming thing in particular, I'm seeing a lot of suggestions that despite the reasoning, end up with very non descriptive names. Async in unity is coroutines, is the only thing we ever had from the engine side, having a "specialized" coroutine that have most of the same semantics: cancels on destruction, can wait for frames/unity events, returns to the main thread and only a few differences: has a typed return value, can be awaited with the async keyword, be called "AwaitableCoroutine" is quite descriptive. It tells u it has almost the same semantics but that u can also await on it. (u know, as any specialization class is usually named in OOP...)

For some additional context:
are "classic" coroutines being deprecated?
is a AwaitableCoroutine a Coroutine? (as in, do they share an ancestor? IEnumerator?).
Do we have utility methods to cancel AwaitableCoroutines without directly interacting with the cancellation token?
The underlying question is, how similar will u make to use one or the other?

 

Is that the case, though? @simon-ferquel-unity explained it as supporting:

You're suggesting that this is all a wrapper for an internal use of Unity's standard Coroutines?

 

I don't think they will deprecate any of this as Coroutine is seriously another workflow in of its own...

The idea of coroutine is to not bother with the execution of another thread which is why we don't have CancellationTokens there.

I still think though, that the Unity API should slowly become deprecated and be replaced with async methods!

Task was definitely the first thing people thought of and would be inline with the C# .NET Library and all that shazam.
But I think Unity has a problem of copyright... I'm not a lawyer myself, but I don't know if it is legal to call it UnityTask as UniTask exists and we only added 2 letters...

As we discussed UnityTask might just be the most comprehensable naming for this feature, but legality wise... hmmm..

 

Not really, because many async/await totorials/workshops/courses keep saying async != mutlithreading. For example, the await for external resources such as web requests, IO, etc., run async, but on the same thread.

Therefore, for me, UnityTask would be the best name, since it would be consistent with the C# names. A Task can also be executed on the same thread Task != Thread.

 

Future is a conventional term: https://en.wikipedia.org/wiki/Futures_and_promises

 

Or since it is still a Task call it something Task like?

 

If *Task is off-limits then I will go with AsyncRoutine. Since according to all the documentation I've read, it's no different from "coroutine".

However, the Unity documentation said: "In Unity, a coroutine is a method that can pause execution and return control to Unity but then continue where it left off on the following frame."

Can AwaitableCoroutine pause execution then continue where it left off too?

 

Instead of having async twice, why not use AwaitableRoutine?

 

+1 for UnityTask or UTask (I like shorter one more).

It's better to inline with .NET naming. As a bonus it's similar to Unreal's AsyncTask.

Is UnityTask a struct? If not and in the future UnityValueTask may be added then shorter names are simpler UTask, UValueTask.

Waiting for EndOfFrame sounds like a task.

 

Because we will have await twice if we await it...

await new AwaitableRoutine

...also we already decided that Routine or Coroutine is a bad idea. Read this page if you wanna know why.

 

“UTask” is explicitly against .NET naming [1][2]:

❌ DO NOT use abbreviations or contractions as part of identifier names.
❌ DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.
❌ DO NOT give class names a prefix (e.g., "C").

“UnityTask” — this is also uncommon in standard libraries to have types like MicrosoftSomething or XamarinSomething.
The brand name “Unity” is a part of the namespace; there is no point in duplicating it in the name of a type: `UnityEngine.UnityTask`.

[1] https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/general-naming-conventions
[2] https://learn.microsoft.com/en-us/d...lines/names-of-classes-structs-and-interfaces

 

yes.

The Unity API doesn't have anything that is prefixed with just a U ( correct me if I'm wrong ), so for concistency's sake let's agree on UnityTask!

 

Which is what I said, but UnityActions, UnityEvents, etc. exist as some people stated in this thread, so naming it UnityTask does make sense.

Also Unity always adds the Unity prefix to classes if they already exist in C#.
Actions are a part of C# as well as Events