From f7137393d757cc979b9960ebae8d191201ff6bc9 Mon Sep 17 00:00:00 2001 From: Jesse Talavera-Greenberg Date: Tue, 20 Oct 2020 15:50:02 -0400 Subject: [PATCH] Proofread the Getting started section --- README.md | 54 +++++++++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 4efc33a..055d55c 100644 --- a/README.md +++ b/README.md @@ -51,67 +51,71 @@ For advanced tips, see this other blog post: [Extends UnityWebRequest via async Getting started --- -Install via [UPM package](#upm-package) or asset package(`UniTask.*.*.*.unitypackage`) available in [UniTask/releases](https://github.com/Cysharp/UniTask/releases) page. +Install UniTask with either [the UPM package](#upm-package) or the traditional asset package (`UniTask.*.*.*.unitypackage`) available [on the releases page](https://github.com/Cysharp/UniTask/releases). + +Here's a brief overview of some of UniTask's features and their usage: ```csharp -// extension awaiter/methods can be used by this namespace +// This namespace provides a wide variety of awaiters, extension methods, and core types. using Cysharp.Threading.Tasks; -// You can return type as struct UniTask(or UniTask), it is unity specialized lightweight alternative of Task -// zero allocation and fast excution for zero overhead async/await integrate with Unity +// You'll generally want async methods to return a UniTask (or a non-generic UniTask). +// It's a Unity-optimized variant of the standard Task class that allocates no heap memory. async UniTask DemoAsync() { - // You can await Unity's AsyncObject + // Extension methods let you await Unity's standard AsyncOperations (including its subclasses) var asset = await Resources.LoadAsync("foo"); var txt = (await UnityWebRequest.Get("https://...").SendWebRequest()).downloadHandler.text; await SceneManager.LoadSceneAsync("scene2"); - // .WithCancellation enables Cancel, GetCancellationTokenOnDestroy synchornizes with lifetime of GameObject + // WithCancellation lets you cancel any UniTask. GetCancellationTokenOnDestroy is an extension + // method that provides a CancellationToken that's triggered when the GameObject is destroyed var asset2 = await Resources.LoadAsync("bar").WithCancellation(this.GetCancellationTokenOnDestroy()); - // .ToUniTask accepts progress callback(and all options), Progress.Create is a lightweight alternative of IProgress + // .ToUniTask accepts a progress callback (and all options) + // Progress.Create returns a lightweight implementation of System.IProgress var asset3 = await Resources.LoadAsync("baz").ToUniTask(Progress.Create(x => Debug.Log(x))); - // await frame-based operation like coroutine + // You can wait a specific number of frames. await UniTask.DelayFrame(100); - // replacement of yield return new WaitForSeconds/WaitForSecondsRealtime + // Use UniTask.Delay instead of WaitForSeconds or WaitForSecondsRealtime. await UniTask.Delay(TimeSpan.FromSeconds(10), ignoreTimeScale: false); - // yield any playerloop timing(PreUpdate, Update, LateUpdate, etc...) + // Suspend the current method and resume it in some other stage of the player loop (PreUpdate, Update, LateUpdate, etc...) await UniTask.Yield(PlayerLoopTiming.PreLateUpdate); - // replacement of yield return null + // Use these instead of `yield return null` (but there's a subtle difference, see below). await UniTask.Yield(); await UniTask.NextFrame(); - // replacement of WaitForEndOfFrame(same as UniTask.Yield(PlayerLoopTiming.LastPostLateUpdate)) + // UniTask provides WaitForEndOfFrame, equivalent to UniTask.Yield(PlayerLoopTiming.LastPostLateUpdate) await UniTask.WaitForEndOfFrame(); - // replacement of yield return new WaitForFixedUpdate(same as UniTask.Yield(PlayerLoopTiming.FixedUpdate)) + // UniTask provides WaitForFixedUpdate, equivalent to UniTask.Yield(PlayerLoopTiming.FixedUpdate) await UniTask.WaitForFixedUpdate(); - // replacement of yield return WaitUntil + // Use UniTask.WaitUntil instead of UnityEngine.WaitUntil. await UniTask.WaitUntil(() => isActive == false); - // special helper of WaitUntil + // There's a variant for the common case of waiting for a value to change, too. await UniTask.WaitUntilValueChanged(this, x => x.isActive); - // You can await IEnumerator coroutine + // You can await standard IEnumerator-based coroutines. await FooCoroutineEnumerator(); - // You can await standard task + // Standard Task objects are fully supported. await Task.Run(() => 100); - // Multithreading, run on ThreadPool under this code + // Suspend this method and resume it on another thread with UniTask.SwitchToThreadPool(). await UniTask.SwitchToThreadPool(); - /* work on ThreadPool */ + // Any code here will run on a separate thread. Multithreading is opt-in. - // return to MainThread(same as `ObserveOnMainThread` in UniRx) + // Now we return to the main thread (just like UniRx's `ObserveOnMainThread`) await UniTask.SwitchToMainThread(); - // get async webrequest + // Let's define this local async function. async UniTask GetTextAsync(UnityWebRequest req) { var op = await req.SendWebRequest(); @@ -122,16 +126,16 @@ async UniTask DemoAsync() var task2 = GetTextAsync(UnityWebRequest.Get("http://bing.com")); var task3 = GetTextAsync(UnityWebRequest.Get("http://yahoo.com")); - // concurrent async-wait and get result easily by tuple syntax + // You can await multiple concurrent UniTasks. var (google, bing, yahoo) = await UniTask.WhenAll(task1, task2, task3); - // shorthand of WhenAll, tuple can await directly + // You can await a tuple of UniTasks as shorthand for UniTask.WhenAll. var (google2, bing2, yahoo2) = await (task1, task2, task3); - // You can handle timeout easily + // UniTasks can easily be given timeouts. await GetTextAsync(UnityWebRequest.Get("http://unity.com")).Timeout(TimeSpan.FromMilliseconds(300)); - // return async-value.(or you can use `UniTask`(no result), `UniTaskVoid`(fire and forget)). + // You can return a value asynchronously, or use `UniTask` or `UniTaskVoid` when you don't need to. return (asset as TextAsset)?.text ?? throw new InvalidOperationException("Asset not found"); } ```