[
{
"path": ".config/dotnet-tools.json",
"content": "{\n \"version\": 1,\n \"isRoot\": true,\n \"tools\": {\n \"docfx\": {\n \"version\": \"2.78.3\",\n \"commands\": [\n \"docfx\"\n ],\n \"rollForward\": false\n }\n }\n}\n"
},
{
"path": ".editorconfig",
"content": "# top-most EditorConfig file\nroot = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\nindent_style = space\nindent_size = 2\ninsert_final_newline = true\ntrim_trailing_whitespace = true\n\n# Visual Studio Spell checker configs (https://learn.microsoft.com/en-us/visualstudio/ide/text-spell-checker?view=vs-2022#how-to-customize-the-spell-checker)\nspelling_exclusion_path = ./exclusion.dic\n\n[*.cs]\nindent_size = 4\ncharset = utf-8-bom\nend_of_line = unset\n\n# Solution files\n[*.{sln,slnx}]\nend_of_line = unset\n\n# MSBuild project files\n[*.{csproj,props,targets}]\nend_of_line = unset\n\n# Xml config files\n[*.{ruleset,config,nuspec,resx,runsettings,DotSettings}]\nend_of_line = unset\n\n[*{_AssemblyInfo.cs,.notsupported.cs}]\ngenerated_code = true\n\n# C# code style settings\n[*.{cs}]\ndotnet_diagnostic.IDE0044.severity = none # IDE0044: Make field readonly\n\n# https://stackoverflow.com/questions/79195382/how-to-disable-fading-unused-methods-in-visual-studio-2022-17-12-0\ndotnet_diagnostic.IDE0051.severity = none # IDE0051: Remove unused private member\ndotnet_diagnostic.IDE0130.severity = none # IDE0130: Namespace does not match folder structure\n"
},
{
"path": ".github/FUNDING.yml",
"content": "github: [neuecc]\n"
},
{
"path": ".github/dependabot.yaml",
"content": "# ref: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot\nversion: 2\nupdates:\n - package-ecosystem: \"github-actions\"\n directory: \"/\"\n schedule:\n interval: \"weekly\" # Check for updates to GitHub Actions every week\n groups:\n dependencies:\n patterns:\n - \"*\"\n cooldown:\n default-days: 14 # Wait 14 days before creating another PR for the same dependency. This will prevent vulnerability on the package impact.\n ignore:\n # I just want update action when major/minor version is updated. patch updates are too noisy.\n - dependency-name: \"*\"\n update-types:\n - version-update:semver-patch\n"
},
{
"path": ".github/workflows/build-debug.yaml",
"content": "name: Build-Debug\n\non:\n push:\n branches:\n - \"master\"\n pull_request:\n branches:\n - \"master\"\n\njobs:\n build-dotnet:\n permissions:\n contents: read\n runs-on: ubuntu-24.04\n timeout-minutes: 10\n steps:\n - uses: Cysharp/Actions/.github/actions/checkout@main\n - uses: Cysharp/Actions/.github/actions/setup-dotnet@main\n - run: dotnet build -c Release\n - run: dotnet test -c Release\n - run: dotnet pack -c Release --no-build -p:IncludeSymbols=true -o $GITHUB_WORKSPACE/artifacts\n\n build-unity:\n if: ${{ ((github.event_name == 'push' && github.repository_owner == 'Cysharp') || startsWith(github.event.pull_request.head.label, 'Cysharp:')) && github.triggering_actor != 'dependabot[bot]' }}\n strategy:\n fail-fast: false\n max-parallel: 2\n matrix:\n unity: [\"2022.3.39f1\", \"6000.0.12f1\"] # Test with LTS\n permissions:\n contents: read\n runs-on: ubuntu-24.04\n timeout-minutes: 30 # Unity build takes more than 20min.\n steps:\n - name: Load secrets\n id: op-load-secret\n uses: 1password/load-secrets-action@581a835fb51b8e7ec56b71cf2ffddd7e68bb25e0 # v2.0.0\n with:\n export-env: false\n env:\n OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN_PUBLIC }}\n UNITY_EMAIL: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/username\"\n UNITY_PASSWORD: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/credential\"\n UNITY_SERIAL: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/serial\"\n\n - uses: Cysharp/Actions/.github/actions/checkout@main\n\n # Execute scripts: Export Package\n # /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -logFile -projectPath . -executeMethod PackageExporter.Export\n - name: Build Unity (.unitypacakge)\n if: ${{ startsWith(matrix.unity, '2022') }} # only execute once\n uses: Cysharp/Actions/.github/actions/unity-builder@main\n env:\n UNITY_EMAIL: ${{ steps.op-load-secret.outputs.UNITY_EMAIL }}\n UNITY_PASSWORD: ${{ steps.op-load-secret.outputs.UNITY_PASSWORD }}\n UNITY_SERIAL: ${{ steps.op-load-secret.outputs.UNITY_SERIAL }}\n with:\n projectPath: src/UniTask\n unityVersion: ${{ matrix.unity }}\n targetPlatform: StandaloneLinux64\n buildMethod: PackageExporter.Export\n\n # Execute UnitTest\n # /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -logFile -projectPath . -executeMethod UnitTestBuilder.BuildUnitTest /headless /ScriptBackend IL2CPP /BuildTarget StandaloneLinux64\n - name: Build UnitTest (IL2CPP)\n uses: Cysharp/Actions/.github/actions/unity-builder@main\n env:\n UNITY_EMAIL: ${{ steps.op-load-secret.outputs.UNITY_EMAIL }}\n UNITY_PASSWORD: ${{ steps.op-load-secret.outputs.UNITY_PASSWORD }}\n UNITY_SERIAL: ${{ steps.op-load-secret.outputs.UNITY_SERIAL }}\n with:\n projectPath: src/UniTask\n unityVersion: ${{ matrix.unity }}\n targetPlatform: StandaloneLinux64\n buildMethod: UnitTestBuilder.BuildUnitTest\n customParameters: \"/headless /ScriptBackend IL2CPP\"\n - name: Check UnitTest file is generated\n run: ls -lR ./src/UniTask/bin/UnitTest\n - name: Execute UnitTest\n run: ./src/UniTask/bin/UnitTest/StandaloneLinux64_IL2CPP/test\n\n - uses: Cysharp/Actions/.github/actions/check-metas@main # check meta files\n with:\n directory: src/UniTask\n\n # Store artifacts.\n - uses: Cysharp/Actions/.github/actions/upload-artifact@main\n if: ${{ startsWith(matrix.unity, '2021') }} # only execute 2021\n with:\n name: UniTask.unitypackage-${{ matrix.unity }}.zip\n path: ./src/UniTask/*.unitypackage\n retention-days: 1\n"
},
{
"path": ".github/workflows/build-docs.yaml",
"content": "name: build-docs\n\non:\n push:\n branches:\n - master\n - feature/docs\n\njobs:\n run-docfx:\n if: ${{ ((github.event_name == 'push' && github.repository_owner == 'Cysharp') || startsWith(github.event.pull_request.head.label, 'Cysharp:')) && github.triggering_actor != 'dependabot[bot]' }}\n permissions:\n contents: write\n pages: write\n runs-on: ubuntu-24.04\n timeout-minutes: 10\n steps:\n - name: Load secrets\n id: op-load-secret\n uses: 1password/load-secrets-action@581a835fb51b8e7ec56b71cf2ffddd7e68bb25e0 # v2.0.0\n with:\n export-env: false\n env:\n OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN_PUBLIC }}\n UNITY_EMAIL: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/username\"\n UNITY_PASSWORD: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/credential\"\n UNITY_SERIAL: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/serial\"\n - uses: Cysharp/Actions/.github/actions/checkout@main\n # Execute scripts: Export Package\n # /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -logFile -projectPath . -executeMethod PackageExporter.Export\n - name: Build Unity (.unitypackage)\n uses: Cysharp/Actions/.github/actions/unity-builder@main\n env:\n UNITY_EMAIL: ${{ steps.op-load-secret.outputs.UNITY_EMAIL }}\n UNITY_PASSWORD: ${{ steps.op-load-secret.outputs.UNITY_PASSWORD }}\n UNITY_SERIAL: ${{ steps.op-load-secret.outputs.UNITY_SERIAL }}\n with:\n projectPath: src/UniTask\n unityVersion: \"2022.3.39f1\"\n targetPlatform: StandaloneLinux64\n buildMethod: PackageExporter.Export\n\n - uses: Cysharp/Actions/.github/actions/checkout@main\n with:\n repository: Cysharp/DocfxTemplate\n path: docs/_DocfxTemplate\n - uses: Cysharp/Actions/.github/actions/setup-dotnet@main\n - name: dotnet tool restore\n run: dotnet tool restore\n - name: Docfx metadata\n run: dotnet docfx metadata docs/docfx.json\n - name: Docfx build\n run: dotnet docfx build docs/docfx.json\n - name: Publish to GitHub Pages\n uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0\n with:\n github_token: ${{ secrets.GITHUB_TOKEN }}\n publish_dir: docs/_site\n"
},
{
"path": ".github/workflows/build-release.yaml",
"content": "name: build-release\n\non:\n workflow_dispatch:\n inputs:\n tag:\n description: \"tag: git tag you want create. (sample 1.0.0)\"\n required: true\n dry-run:\n description: \"dry-run: true will never create relase/nuget.\"\n required: true\n default: false\n type: boolean\n\njobs:\n update-packagejson:\n permissions:\n actions: read\n contents: write\n uses: Cysharp/Actions/.github/workflows/update-packagejson.yaml@main\n with:\n file-path: ./src/UniTask/Assets/Plugins/UniTask/package.json\n tag: ${{ inputs.tag }}\n dry-run: ${{ inputs.dry-run }}\n\n build-dotnet:\n needs: [update-packagejson]\n permissions:\n contents: read\n runs-on: ubuntu-24.04\n timeout-minutes: 10\n steps:\n - run: echo ${{ needs.update-packagejson.outputs.sha }}\n - uses: Cysharp/Actions/.github/actions/checkout@main\n with:\n ref: ${{ needs.update-packagejson.outputs.sha }}\n - uses: Cysharp/Actions/.github/actions/setup-dotnet@main\n # build and pack\n - run: dotnet build -c Release -p:Version=${{ inputs.tag }}\n - run: dotnet test -c Release --no-build\n - run: dotnet pack ./src/UniTask.NetCore/UniTask.NetCore.csproj -c Release --no-build -p:Version=${{ inputs.tag }} -o ./publish\n # Store artifacts.\n - uses: Cysharp/Actions/.github/actions/upload-artifact@main\n with:\n name: nuget\n path: ./publish/\n retention-days: 1\n\n build-unity:\n needs: [update-packagejson]\n strategy:\n matrix:\n unity: [\"2022.3.39f1\"]\n permissions:\n contents: read\n runs-on: ubuntu-24.04\n timeout-minutes: 15\n steps:\n - name: Load secrets\n id: op-load-secret\n uses: 1password/load-secrets-action@581a835fb51b8e7ec56b71cf2ffddd7e68bb25e0 # v2.0.0\n with:\n export-env: false\n env:\n OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN_PUBLIC }}\n UNITY_EMAIL: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/username\"\n UNITY_PASSWORD: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/credential\"\n UNITY_SERIAL: \"op://${{ vars.OP_VAULT_ACTIONS_PUBLIC }}/UNITY_LICENSE/serial\"\n\n - run: echo ${{ needs.update-packagejson.outputs.sha }}\n - uses: Cysharp/Actions/.github/actions/checkout@main\n with:\n ref: ${{ needs.update-packagejson.outputs.sha }}\n # Execute scripts: Export Package\n # /opt/Unity/Editor/Unity -quit -batchmode -nographics -silent-crashes -logFile -projectPath . -executeMethod PackageExporter.Export\n - name: Build Unity (.unitypacakge)\n uses: Cysharp/Actions/.github/actions/unity-builder@main\n env:\n UNITY_EMAIL: ${{ steps.op-load-secret.outputs.UNITY_EMAIL }}\n UNITY_PASSWORD: ${{ steps.op-load-secret.outputs.UNITY_PASSWORD }}\n UNITY_SERIAL: ${{ steps.op-load-secret.outputs.UNITY_SERIAL }}\n with:\n projectPath: src/UniTask\n unityVersion: ${{ matrix.unity }}\n targetPlatform: StandaloneLinux64\n buildMethod: PackageExporter.Export\n\n - uses: Cysharp/Actions/.github/actions/check-metas@main # check meta files\n with:\n directory: src/UniTask\n\n # Store artifacts.\n - uses: Cysharp/Actions/.github/actions/upload-artifact@main\n with:\n name: UniTask.${{ inputs.tag }}.unitypackage\n path: ./src/UniTask/UniTask.${{ inputs.tag }}.unitypackage\n retention-days: 1\n\n # release\n create-release:\n needs: [update-packagejson, build-dotnet, build-unity]\n permissions:\n contents: write\n id-token: write # required for NuGet Trusted Publish\n uses: Cysharp/Actions/.github/workflows/create-release.yaml@main\n with:\n commit-id: ${{ needs.update-packagejson.outputs.sha }}\n dry-run: ${{ inputs.dry-run }}\n tag: ${{ inputs.tag }}\n nuget-push: true\n release-upload: true\n release-asset-path: ./UniTask.${{ inputs.tag }}.unitypackage/UniTask.${{ inputs.tag }}.unitypackage\n secrets: inherit\n\n cleanup:\n if: ${{ needs.update-packagejson.outputs.is-branch-created == 'true' }}\n needs: [update-packagejson, build-dotnet, build-unity]\n permissions:\n contents: write\n uses: Cysharp/Actions/.github/workflows/clean-packagejson-branch.yaml@main\n with:\n branch: ${{ needs.update-packagejson.outputs.branch-name }}\n"
},
{
"path": ".github/workflows/prevent-github-change.yaml",
"content": "name: Prevent github change\non:\n pull_request:\n paths:\n - \".github/**/*.yaml\"\n - \".github/**/*.yml\"\n\njobs:\n detect:\n permissions:\n contents: read\n uses: Cysharp/Actions/.github/workflows/prevent-github-change.yaml@main\n"
},
{
"path": ".github/workflows/stale.yaml",
"content": "name: \"Close stale issues\"\n\non:\n workflow_dispatch:\n schedule:\n - cron: \"0 0 * * *\"\n\njobs:\n stale:\n permissions:\n contents: read\n pull-requests: write\n issues: write\n uses: Cysharp/Actions/.github/workflows/stale-issue.yaml@main\n"
},
{
"path": ".github/workflows/toc.yaml",
"content": "name: TOC Generator\n\non:\n push:\n paths:\n - 'README.md'\n\njobs:\n toc:\n permissions:\n contents: write\n uses: Cysharp/Actions/.github/workflows/toc-generator.yaml@main\n with:\n TOC_TITLE: \"## Table of Contents\"\n secrets: inherit\n"
},
{
"path": ".gitignore",
"content": "# Unity\n\n*.pidb\n*.suo\n*.userprefs\n*.vsmdi\n*.testsettings\n*/bin\n*/obj\n*/publish\n$tf\nTestResults\n!*.sln\n!*.csproj\n!*/*.csproj\n[Ll]ibrary/\n[Tt]emp/\n[Oo]bj/\n\n# VS2013\n\n# Build Folders (you can keep bin if you'd like, to store dlls and pdbs)\n[Bb]in/\n[Oo]bj/\n\n# mstest test results\nTestResults\n\n## Ignore Visual Studio temporary files, build results, and\n## files generated by popular Visual Studio add-ons.\n\n# User-specific files\n*.suo\n*.user\n*.sln.docstates\n\n# Build results\n[Dd]ebug/\n[Rr]elease/\nx64/\n*_i.c\n*_p.c\n*.ilk\n# *.meta # already ignored in Unity section\n*.obj\n*.pch\n*.pdb\n*.pgc\n*.pgd\n*.rsp\n*.sbr\n*.tlb\n*.tli\n*.tlh\n*.tmp\n*.log\n*.vspscc\n*.vssscc\n.builds\n\n# Visual C++ cache files\nipch/\n*.aps\n*.ncb\n*.opensdf\n*.sdf\n\n# Visual Studio profiler\n*.psess\n*.vsp\n*.vspx\n\n# Guidance Automation Toolkit\n*.gpState\n\n# ReSharper is a .NET coding add-in\n_ReSharper*\n\n# NCrunch\n*.ncrunch*\n.*crunch*.local.xml\n\n# Installshield output folder\n[Ee]xpress\n\n# DocProject is a documentation generator add-in\nDocProject/buildhelp/\nDocProject/Help/*.HxT\nDocProject/Help/*.HxC\nDocProject/Help/*.hhc\nDocProject/Help/*.hhk\nDocProject/Help/*.hhp\nDocProject/Help/Html2\nDocProject/Help/html\n\n# Click-Once directory\npublish\n\n# Publish Web Output\n*.Publish.xml\n\n# NuGet Packages Directory\n*.nupkg\n# NuGet Symbol Packages\n*.snupkg\n# The packages folder can be ignored because of Package Restore\n# packages # upm pacakge will use Packages\n# **/[Pp]ackages/*\n# except build/, which is used as an MSBuild target.\n# !**/[Pp]ackages/build/\n# Uncomment if necessary however generally it will be regenerated when needed\n#!**/[Pp]ackages/repositories.config\n# NuGet v3's project.json files produces more ignorable files\n*.nuget.props\n*.nuget.targets\n\n# Windows Azure Build Output\ncsx\n*.build.csdef\n\n# Windows Store app package directory\nAppPackages/\n\n# Others\n[Bb]in\n[Oo]bj\nsql\nTestResults\n[Tt]est[Rr]esult*\n*.Cache\nClientBin\n[Ss]tyle[Cc]op.*\n~$*\n*.dbmdl\nGenerated_Code #added for RIA/Silverlight projects\n\n# Backup & report files from converting an old project file to a newer\n# Visual Studio version. Backup files are not needed, because we have git ;-)\n_UpgradeReport_Files/\nBackup*/\nUpgradeLog*.XML\nAssets/WSATestCertificate.pfx\n.vs/\n\n# Unity\n\n# Unity\n.vsconfig\nsrc/UniTask/Library/*\nsrc/UniTask/Temp/*\nsrc/UniTask/Logs/*\nsrc/UniTask/[Uu]ser[Ss]ettings/\nsrc/UniTask/*.sln\nsrc/UniTask/*.csproj\nsrc/UniTask/*.unitypackage\n!src/UniTask/Packages/\n"
},
{
"path": "Directory.Build.props",
"content": "\n\n \n true\n $(MSBuildThisFileDirectory)opensource.snk\n\n \n false\n $(Version)\n Cysharp\n Cysharp\n © Cysharp, Inc.\n task;async\n https://github.com/Cysharp/UniTask\n README.md\n $(PackageProjectUrl)\n git\n MIT\n Icon.png\n \n\n \n \n \n \n \n\n"
},
{
"path": "LICENSE",
"content": "The MIT License (MIT)\n\nCopyright (c) 2019 Yoshifumi Kawai / Cysharp, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "UniTask\n===\n[](https://github.com/Cysharp/UniTask/actions) [](https://github.com/Cysharp/UniTask/releases) [](https://github.com/Cysharp/UniTask/blob/master/README_CN.md)\n\nProvides an efficient allocation free async/await integration for Unity.\n\n* Struct based `UniTask` and custom AsyncMethodBuilder to achieve zero allocation\n* Makes all Unity AsyncOperations and Coroutines awaitable\n* PlayerLoop based task(`UniTask.Yield`, `UniTask.Delay`, `UniTask.DelayFrame`, etc..) that enable replacing all coroutine operations\n* MonoBehaviour Message Events and uGUI Events as awaitable/async-enumerable\n* Runs completely on Unity's PlayerLoop so doesn't use threads and runs on WebGL, wasm, etc.\n* Asynchronous LINQ, with Channel and AsyncReactiveProperty\n* TaskTracker window to prevent memory leaks\n* Highly compatible behaviour with Task/ValueTask/IValueTaskSource\n\nFor technical details, see blog post: [UniTask v2 — Zero Allocation async/await for Unity, with Asynchronous LINQ\n](https://medium.com/@neuecc/unitask-v2-zero-allocation-async-await-for-unity-with-asynchronous-linq-1aa9c96aa7dd) \nFor advanced tips, see blog post: [Extends UnityWebRequest via async decorator pattern — Advanced Techniques of UniTask](https://medium.com/@neuecc/extends-unitywebrequest-via-async-decorator-pattern-advanced-techniques-of-unitask-ceff9c5ee846)\n\n\n\n## Table of Contents\n\n- [Getting started](#getting-started)\n- [Basics of UniTask and AsyncOperation](#basics-of-unitask-and-asyncoperation)\n- [Cancellation and Exception handling](#cancellation-and-exception-handling)\n- [Timeout handling](#timeout-handling)\n- [Progress](#progress)\n- [PlayerLoop](#playerloop)\n- [async void vs async UniTaskVoid](#async-void-vs-async-unitaskvoid)\n- [UniTaskTracker](#unitasktracker)\n- [External Assets](#external-assets)\n- [AsyncEnumerable and Async LINQ](#asyncenumerable-and-async-linq)\n- [Awaitable Events](#awaitable-events)\n- [Channel](#channel)\n- [vs Awaitable](#vs-awaitable)\n- [For Unit Testing](#for-unit-testing)\n- [ThreadPool limitation](#threadpool-limitation)\n- [IEnumerator.ToUniTask limitation](#ienumeratortounitask-limitation)\n- [For UnityEditor](#for-unityeditor)\n- [Compare with Standard Task API](#compare-with-standard-task-api)\n- [Pooling Configuration](#pooling-configuration)\n- [Allocation on Profiler](#allocation-on-profiler)\n- [UniTaskSynchronizationContext](#unitasksynchronizationcontext)\n- [API References](#api-references)\n- [UPM Package](#upm-package)\n - [Install via git URL](#install-via-git-url)\n- [.NET Core](#net-core)\n- [License](#license)\n\n\n\nGetting started\n---\nInstall via [UPM package](#upm-package) with git reference or asset package(`UniTask.*.*.*.unitypackage`) available in [UniTask/releases](https://github.com/Cysharp/UniTask/releases).\n\n```csharp\n// extension awaiter/methods can be used by this namespace\nusing Cysharp.Threading.Tasks;\n\n// You can return type as struct UniTask(or UniTask), it is unity specialized lightweight alternative of Task\n// zero allocation and fast excution for zero overhead async/await integrate with Unity\nasync UniTask DemoAsync()\n{\n // You can await Unity's AsyncObject\n var asset = await Resources.LoadAsync(\"foo\");\n var txt = (await UnityWebRequest.Get(\"https://...\").SendWebRequest()).downloadHandler.text;\n await SceneManager.LoadSceneAsync(\"scene2\");\n\n // .WithCancellation enables Cancel, GetCancellationTokenOnDestroy synchornizes with lifetime of GameObject\n // after Unity 2022.2, you can use `destroyCancellationToken` in MonoBehaviour\n var asset2 = await Resources.LoadAsync(\"bar\").WithCancellation(this.GetCancellationTokenOnDestroy());\n\n // .ToUniTask accepts progress callback(and all options), Progress.Create is a lightweight alternative of IProgress\n var asset3 = await Resources.LoadAsync(\"baz\").ToUniTask(Progress.Create(x => Debug.Log(x)));\n\n // await frame-based operation like a coroutine\n await UniTask.DelayFrame(100); \n\n // replacement of yield return new WaitForSeconds/WaitForSecondsRealtime\n await UniTask.Delay(TimeSpan.FromSeconds(10), ignoreTimeScale: false);\n \n // yield any playerloop timing(PreUpdate, Update, LateUpdate, etc...)\n await UniTask.Yield(PlayerLoopTiming.PreLateUpdate);\n\n // replacement of yield return null\n await UniTask.Yield();\n await UniTask.NextFrame();\n\n // replacement of WaitForEndOfFrame\n#if UNITY_2023_1_OR_NEWER\n await UniTask.WaitForEndOfFrame();\n#else\n // requires MonoBehaviour(CoroutineRunner))\n await UniTask.WaitForEndOfFrame(this); // this is MonoBehaviour\n#endif\n\n // replacement of yield return new WaitForFixedUpdate(same as UniTask.Yield(PlayerLoopTiming.FixedUpdate))\n await UniTask.WaitForFixedUpdate();\n \n // replacement of yield return WaitUntil\n await UniTask.WaitUntil(() => isActive == false);\n\n // special helper of WaitUntil\n await UniTask.WaitUntilValueChanged(this, x => x.isActive);\n\n // You can await IEnumerator coroutines\n await FooCoroutineEnumerator();\n\n // You can await a standard task\n await Task.Run(() => 100);\n\n // Multithreading, run on ThreadPool under this code\n await UniTask.SwitchToThreadPool();\n\n /* work on ThreadPool */\n\n // return to MainThread(same as `ObserveOnMainThread` in UniRx)\n await UniTask.SwitchToMainThread();\n\n // get async webrequest\n async UniTask GetTextAsync(UnityWebRequest req)\n {\n var op = await req.SendWebRequest();\n return op.downloadHandler.text;\n }\n\n var task1 = GetTextAsync(UnityWebRequest.Get(\"http://google.com\"));\n var task2 = GetTextAsync(UnityWebRequest.Get(\"http://bing.com\"));\n var task3 = GetTextAsync(UnityWebRequest.Get(\"http://yahoo.com\"));\n\n // concurrent async-wait and get results easily by tuple syntax\n var (google, bing, yahoo) = await UniTask.WhenAll(task1, task2, task3);\n\n // shorthand of WhenAll, tuple can await directly\n var (google2, bing2, yahoo2) = await (task1, task2, task3);\n\n // return async-value.(or you can use `UniTask`(no result), `UniTaskVoid`(fire and forget)).\n return (asset as TextAsset)?.text ?? throw new InvalidOperationException(\"Asset not found\");\n}\n```\n\nBasics of UniTask and AsyncOperation\n---\nUniTask features rely on C# 7.0([task-like custom async method builder feature](https://github.com/dotnet/roslyn/blob/master/docs/features/task-types.md)) so the required Unity version is after `Unity 2018.3`, the official lowest version supported is `Unity 2018.4.13f1`.\n\nWhy is UniTask(custom task-like object) required? Because Task is too heavy and not matched to Unity threading (single-thread). UniTask does not use threads and SynchronizationContext/ExecutionContext because Unity's asynchronous object is automaticaly dispatched by Unity's engine layer. It achieves faster and lower allocation, and is completely integrated with Unity.\n\nYou can await `AsyncOperation`, `ResourceRequest`, `AssetBundleRequest`, `AssetBundleCreateRequest`, `UnityWebRequestAsyncOperation`, `AsyncGPUReadbackRequest`, `IEnumerator` and others when `using Cysharp.Threading.Tasks;`.\n\nUniTask provides three pattern of extension methods.\n\n```csharp\n* await asyncOperation;\n* .WithCancellation(CancellationToken);\n* .ToUniTask(IProgress, PlayerLoopTiming, CancellationToken);\n```\n\n`WithCancellation` is a simple version of `ToUniTask`, both return `UniTask`. For details of cancellation, see: [Cancellation and Exception handling](#cancellation-and-exception-handling) section.\n\n> Note: await directly is returned from native timing of PlayerLoop but WithCancellation and ToUniTask are returned from specified PlayerLoopTiming. For details of timing, see: [PlayerLoop](#playerloop) section.\n\n> Note: AssetBundleRequest has `asset` and `allAssets`, default await returns `asset`. If you want to get `allAssets`, you can use `AwaitForAllAssets()` method.\n\nThe type of `UniTask` can use utilities like `UniTask.WhenAll`, `UniTask.WhenAny`, `UniTask.WhenEach`. They are like `Task.WhenAll`/`Task.WhenAny` but the return type is more useful. They return value tuples so you can deconstruct each result and pass multiple types.\n\n```csharp\npublic async UniTaskVoid LoadManyAsync()\n{\n // parallel load.\n var (a, b, c) = await UniTask.WhenAll(\n LoadAsSprite(\"foo\"),\n LoadAsSprite(\"bar\"),\n LoadAsSprite(\"baz\"));\n}\n\nasync UniTask LoadAsSprite(string path)\n{\n var resource = await Resources.LoadAsync(path);\n return (resource as Sprite);\n}\n```\n\nIf you want to convert a callback to UniTask, you can use `UniTaskCompletionSource` which is a lightweight edition of `TaskCompletionSource`. \n\n```csharp\npublic UniTask WrapByUniTaskCompletionSource()\n{\n var utcs = new UniTaskCompletionSource();\n\n // when complete, call utcs.TrySetResult();\n // when failed, call utcs.TrySetException();\n // when cancel, call utcs.TrySetCanceled();\n\n return utcs.Task; //return UniTask\n}\n```\n\nYou can convert Task -> UniTask: `AsUniTask`, `UniTask` -> `UniTask`: `AsAsyncUnitUniTask`, `UniTask` -> `UniTask`: `AsUniTask`. `UniTask` -> `UniTask`'s conversion cost is free.\n\nIf you want to convert async to coroutine, you can use `.ToCoroutine()`, this is useful if you want to only allow using the coroutine system.\n\nUniTask can not await twice. This is a similar constraint to the [ValueTask/IValueTaskSource](https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.valuetask-1?view=netcore-3.1) introduced in .NET Standard 2.1.\n\n> The following operations should never be performed on a ValueTask instance:\n>\n> * Awaiting the instance multiple times.\n> * Calling AsTask multiple times.\n> * Using .Result or .GetAwaiter().GetResult() when the operation hasn't yet completed, or using them multiple times.\n> * Using more than one of these techniques to consume the instance.\n>\n> If you do any of the above, the results are undefined.\n\n```csharp\nvar task = UniTask.DelayFrame(10);\nawait task;\nawait task; // NG, throws Exception\n```\n\nStore to the class field, you can use `UniTask.Lazy` that supports calling multiple times. `.Preserve()` allows for multiple calls (internally cached results). This is useful when there are multiple calls in a function scope.\n\nAlso `UniTaskCompletionSource` can await multiple times and await from many callers.\n\nCancellation and Exception handling\n---\nSome UniTask factory methods have a `CancellationToken cancellationToken = default` parameter. Also some async operations for Unity have `WithCancellation(CancellationToken)` and `ToUniTask(..., CancellationToken cancellation = default)` extension methods. \n\nYou can pass `CancellationToken` to parameter by standard [`CancellationTokenSource`](https://docs.microsoft.com/en-us/dotnet/api/system.threading.cancellationtokensource).\n\n```csharp\nvar cts = new CancellationTokenSource();\n\ncancelButton.onClick.AddListener(() =>\n{\n cts.Cancel();\n});\n\nawait UnityWebRequest.Get(\"http://google.co.jp\").SendWebRequest().WithCancellation(cts.Token);\n\nawait UniTask.DelayFrame(1000, cancellationToken: cts.Token);\n```\n\nCancellationToken can be created by `CancellationTokenSource` or MonoBehaviour's extension method `GetCancellationTokenOnDestroy`.\n\n```csharp\n// this CancellationToken lifecycle is same as GameObject.\nawait UniTask.DelayFrame(1000, cancellationToken: this.GetCancellationTokenOnDestroy());\n```\n\nFor propagate Cancellation, all async method recommend to accept `CancellationToken cancellationToken` at last argument, and pass `CancellationToken` from root to end.\n\n```csharp\nawait FooAsync(this.GetCancellationTokenOnDestroy());\n\n// ---\n\nasync UniTask FooAsync(CancellationToken cancellationToken)\n{\n await BarAsync(cancellationToken);\n}\n\nasync UniTask BarAsync(CancellationToken cancellationToken)\n{\n await UniTask.Delay(TimeSpan.FromSeconds(3), cancellationToken);\n}\n```\n\n`CancellationToken` means lifecycle of async. You can hold your own lifecycle insteadof default CancellationTokenOnDestroy.\n\n```csharp\npublic class MyBehaviour : MonoBehaviour\n{\n CancellationTokenSource disableCancellation = new CancellationTokenSource();\n CancellationTokenSource destroyCancellation = new CancellationTokenSource();\n\n private void OnEnable()\n {\n if (disableCancellation != null)\n {\n disableCancellation.Dispose();\n }\n disableCancellation = new CancellationTokenSource();\n }\n\n private void OnDisable()\n {\n disableCancellation.Cancel();\n }\n\n private void OnDestroy()\n {\n destroyCancellation.Cancel();\n destroyCancellation.Dispose();\n }\n}\n```\n\nAfter Unity 2022.2, Unity adds CancellationToken in [MonoBehaviour.destroyCancellationToken](https://docs.unity3d.com/ScriptReference/MonoBehaviour-destroyCancellationToken.html) and [Application.exitCancellationToken](https://docs.unity3d.com/ScriptReference/Application-exitCancellationToken.html).\n\nWhen cancellation is detected, all methods throw `OperationCanceledException` and propagate upstream. When exception(not limited to `OperationCanceledException`) is not handled in async method, it is propagated finally to `UniTaskScheduler.UnobservedTaskException`. The default behaviour of received unhandled exception is to write log as exception. Log level can be changed using `UniTaskScheduler.UnobservedExceptionWriteLogType`. If you want to use custom behaviour, set an action to `UniTaskScheduler.UnobservedTaskException.`\n\nAnd also `OperationCanceledException` is a special exception, this is silently ignored at `UnobservedTaskException`.\n\nIf you want to cancel behaviour in an async UniTask method, throw `OperationCanceledException` manually.\n\n```csharp\npublic async UniTask FooAsync()\n{\n await UniTask.Yield();\n throw new OperationCanceledException();\n}\n```\n\nIf you handle an exception but want to ignore(propagate to global cancellation handling), use an exception filter.\n\n```csharp\npublic async UniTask BarAsync()\n{\n try\n {\n var x = await FooAsync();\n return x * 2;\n }\n catch (Exception ex) when (!(ex is OperationCanceledException)) // when (ex is not OperationCanceledException) at C# 9.0\n {\n return -1;\n }\n}\n```\n\nthrows/catch `OperationCanceledException` is slightly heavy, so if performance is a concern, use `UniTask.SuppressCancellationThrow` to avoid OperationCanceledException throw. It returns `(bool IsCanceled, T Result)` instead of throwing.\n\n```csharp\nvar (isCanceled, _) = await UniTask.DelayFrame(10, cancellationToken: cts.Token).SuppressCancellationThrow();\nif (isCanceled)\n{\n // ...\n}\n```\n\nNote: Only suppress throws if you call directly into the most source method. Otherwise, the return value will be converted, but the entire pipeline will not suppress throws.\n\nSome features that use Unity's player loop, such as `UniTask.Yield` and `UniTask.Delay` etc, determines CancellationToken state on the player loop. \nThis means it does not cancel immediately upon `CancellationToken` fired. \n\nIf you want to change this behaviour, the cancellation to be immediate, set the `cancelImmediately` flag as an argument.\n\n```csharp\nawait UniTask.Yield(cancellationToken, cancelImmediately: true);\n```\n\nNote: Setting `cancelImmediately` to true and detecting an immediate cancellation is more costly than the default behavior.\nThis is because it uses `CancellationToken.Register`; it is heavier than checking CancellationToken on the player loop.\n\nTimeout handling\n---\nTimeout is a variation of cancellation. You can set timeout by `CancellationTokenSouce.CancelAfterSlim(TimeSpan)` and pass CancellationToken to async methods.\n\n```csharp\nvar cts = new CancellationTokenSource();\ncts.CancelAfterSlim(TimeSpan.FromSeconds(5)); // 5sec timeout.\n\ntry\n{\n await UnityWebRequest.Get(\"http://foo\").SendWebRequest().WithCancellation(cts.Token);\n}\ncatch (OperationCanceledException ex)\n{\n if (ex.CancellationToken == cts.Token)\n {\n UnityEngine.Debug.Log(\"Timeout\");\n }\n}\n```\n\n> `CancellationTokenSouce.CancelAfter` is a standard api. However in Unity you should not use it because it depends threading timer. `CancelAfterSlim` is UniTask's extension methods, it uses PlayerLoop instead.\n\nIf you want to use timeout with other source of cancellation, use `CancellationTokenSource.CreateLinkedTokenSource`.\n\n```csharp\nvar cancelToken = new CancellationTokenSource();\ncancelButton.onClick.AddListener(() =>\n{\n cancelToken.Cancel(); // cancel from button click.\n});\n\nvar timeoutToken = new CancellationTokenSource();\ntimeoutToken.CancelAfterSlim(TimeSpan.FromSeconds(5)); // 5sec timeout.\n\ntry\n{\n // combine token\n var linkedTokenSource = CancellationTokenSource.CreateLinkedTokenSource(cancelToken.Token, timeoutToken.Token);\n\n await UnityWebRequest.Get(\"http://foo\").SendWebRequest().WithCancellation(linkedTokenSource.Token);\n}\ncatch (OperationCanceledException ex)\n{\n if (timeoutToken.IsCancellationRequested)\n {\n UnityEngine.Debug.Log(\"Timeout.\");\n }\n else if (cancelToken.IsCancellationRequested)\n {\n UnityEngine.Debug.Log(\"Cancel clicked.\");\n }\n}\n```\n\nOptimize for reduce allocation of CancellationTokenSource for timeout per call async method, you can use UniTask's `TimeoutController`.\n\n```csharp\nTimeoutController timeoutController = new TimeoutController(); // setup to field for reuse.\n\nasync UniTask FooAsync()\n{\n try\n {\n // you can pass timeoutController.Timeout(TimeSpan) to cancellationToken.\n await UnityWebRequest.Get(\"http://foo\").SendWebRequest()\n .WithCancellation(timeoutController.Timeout(TimeSpan.FromSeconds(5)));\n timeoutController.Reset(); // call Reset(Stop timeout timer and ready for reuse) when succeed.\n }\n catch (OperationCanceledException ex)\n {\n if (timeoutController.IsTimeout())\n {\n UnityEngine.Debug.Log(\"timeout\");\n }\n }\n}\n```\n\nIf you want to use timeout with other source of cancellation, use `new TimeoutController(CancellationToken)`.\n\n```csharp\nTimeoutController timeoutController;\nCancellationTokenSource clickCancelSource;\n\nvoid Start()\n{\n this.clickCancelSource = new CancellationTokenSource();\n this.timeoutController = new TimeoutController(clickCancelSource);\n}\n```\n\nNote: UniTask has `.Timeout`, `.TimeoutWithoutException` methods however, if possible, do not use these, please pass `CancellationToken`. Because `.Timeout` work from external of task, can not stop timeoutted task. `.Timeout` means ignore result when timeout. If you pass a `CancellationToken` to the method, it will act from inside of the task, so it is possible to stop a running task.\n\nProgress\n---\nSome async operations for unity have `ToUniTask(IProgress progress = null, ...)` extension methods. \n\n```csharp\nvar progress = Progress.Create(x => Debug.Log(x));\n\nvar request = await UnityWebRequest.Get(\"http://google.co.jp\")\n .SendWebRequest()\n .ToUniTask(progress: progress);\n```\n\nYou should not use standard `new System.Progress`, because it causes allocation every time. Use `Cysharp.Threading.Tasks.Progress` instead. This progress factory has two methods, `Create` and `CreateOnlyValueChanged`. `CreateOnlyValueChanged` calls only when the progress value has changed.\n\nImplementing IProgress interface to caller is better as there is no lambda allocation.\n\n```csharp\npublic class Foo : MonoBehaviour, IProgress\n{\n public void Report(float value)\n {\n UnityEngine.Debug.Log(value);\n }\n\n public async UniTaskVoid WebRequest()\n {\n var request = await UnityWebRequest.Get(\"http://google.co.jp\")\n .SendWebRequest()\n .ToUniTask(progress: this); // pass this\n }\n}\n```\n\nPlayerLoop\n---\nUniTask is run on a custom [PlayerLoop](https://docs.unity3d.com/ScriptReference/LowLevel.PlayerLoop.html). UniTask's playerloop based methods (such as `Delay`, `DelayFrame`, `asyncOperation.ToUniTask`, etc...) accept this `PlayerLoopTiming`.\n\n```csharp\npublic enum PlayerLoopTiming\n{\n Initialization = 0,\n LastInitialization = 1,\n\n EarlyUpdate = 2,\n LastEarlyUpdate = 3,\n\n FixedUpdate = 4,\n LastFixedUpdate = 5,\n\n PreUpdate = 6,\n LastPreUpdate = 7,\n\n Update = 8,\n LastUpdate = 9,\n\n PreLateUpdate = 10,\n LastPreLateUpdate = 11,\n\n PostLateUpdate = 12,\n LastPostLateUpdate = 13\n \n#if UNITY_2020_2_OR_NEWER\n TimeUpdate = 14,\n LastTimeUpdate = 15,\n#endif\n}\n```\n\nIt indicates when to run, you can check [PlayerLoopList.md](https://gist.github.com/neuecc/bc3a1cfd4d74501ad057e49efcd7bdae) to Unity's default playerloop and injected UniTask's custom loop.\n\n`PlayerLoopTiming.Update` is similar to `yield return null` in a coroutine, but it is called before Update(Update and uGUI events(button.onClick, etc...) are called on `ScriptRunBehaviourUpdate`, yield return null is called on `ScriptRunDelayedDynamicFrameRate`). `PlayerLoopTiming.FixedUpdate` is similar to `WaitForFixedUpdate`.\n\n> `PlayerLoopTiming.LastPostLateUpdate` is not equivalent to coroutine's `yield return new WaitForEndOfFrame()`. Coroutine's WaitForEndOfFrame seems to run after the PlayerLoop is done. Some methods that require coroutine's end of frame(`Texture2D.ReadPixels`, `ScreenCapture.CaptureScreenshotAsTexture`, `CommandBuffer`, etc) do not work correctly when replaced with async/await. In these cases, pass MonoBehaviour(coroutine runnner) to `UniTask.WaitForEndOfFrame`. For example, `await UniTask.WaitForEndOfFrame(this);` is lightweight allocation free alternative of `yield return new WaitForEndOfFrame()`.\n> \n> Note: In Unity 2023.1 or newer, `await UniTask.WaitForEndOfFrame();` no longer requires MonoBehaviour. It uses `UnityEngine.Awaitable.EndOfFrameAsync`.\n\n`yield return null` and `UniTask.Yield` are similar but different. `yield return null` always returns next frame but `UniTask.Yield` returns next called. That is, call `UniTask.Yield(PlayerLoopTiming.Update)` on `PreUpdate`, it returns same frame. `UniTask.NextFrame()` guarantees return next frame, you can expect this to behave exactly the same as `yield return null`.\n\n> UniTask.Yield(without CancellationToken) is a special type, returns `YieldAwaitable` and runs on YieldRunner. It is the most lightweight and fastest.\n\n`AsyncOperation` is returned from native timing. For example, await `SceneManager.LoadSceneAsync` is returned from `EarlyUpdate.UpdatePreloading` and after being called, the loaded scene's `Start` is called from `EarlyUpdate.ScriptRunDelayedStartupFrame`. Also `await UnityWebRequest` is returned from `EarlyUpdate.ExecuteMainThreadJobs`.\n\nIn UniTask, await directly uses native timing, while `WithCancellation` and `ToUniTask` use specified timing. This is usually not a particular problem, but with `LoadSceneAsync`, it causes a different order of Start and continuation after await. So it is recommended not to use `LoadSceneAsync.ToUniTask`.\n\n> Note: When using Unity 2023.1 or newer, ensure you have `using UnityEngine;` in the using statements of your file when working with new `UnityEngine.Awaitable` methods like `SceneManager.LoadSceneAsync`. \n> This prevents compilation errors by avoiding the use of the `UnityEngine.AsyncOperation` version.\n\nIn the stacktrace, you can check where it is running in playerloop.\n\n\n\nBy default, UniTask's PlayerLoop is initialized at `[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]`.\n\nThe order in which methods are called in BeforeSceneLoad is nondeterministic, so if you want to use UniTask in other BeforeSceneLoad methods, you should try to initialize it before this.\n\n```csharp\n// AfterAssembliesLoaded is called before BeforeSceneLoad\n[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)]\npublic static void InitUniTaskLoop()\n{\n var loop = PlayerLoop.GetCurrentPlayerLoop();\n Cysharp.Threading.Tasks.PlayerLoopHelper.Initialize(ref loop);\n}\n```\n\nIf you import Unity's `Entities` package, that resets the custom player loop to default at `BeforeSceneLoad` and injects ECS's loop. When Unity calls ECS's inject method after UniTask's initialize method, UniTask will no longer work.\n\nTo solve this issue, you can re-initialize the UniTask PlayerLoop after ECS is initialized.\n\n```csharp\n// Get ECS Loop.\nvar playerLoop = ScriptBehaviourUpdateOrder.CurrentPlayerLoop;\n\n// Setup UniTask's PlayerLoop.\nPlayerLoopHelper.Initialize(ref playerLoop);\n```\n\nYou can diagnose whether UniTask's player loop is ready by calling `PlayerLoopHelper.IsInjectedUniTaskPlayerLoop()`. And also `PlayerLoopHelper.DumpCurrentPlayerLoop` logs all current playerloops to console.\n\n```csharp\nvoid Start()\n{\n UnityEngine.Debug.Log(\"UniTaskPlayerLoop ready? \" + PlayerLoopHelper.IsInjectedUniTaskPlayerLoop());\n PlayerLoopHelper.DumpCurrentPlayerLoop();\n}\n```\n\nYou can optimize loop cost slightly by remove unuse PlayerLoopTiming injection. You can call `PlayerLoopHelper.Initialize(InjectPlayerLoopTimings)` on initialize.\n\n```csharp\nvar loop = PlayerLoop.GetCurrentPlayerLoop();\nPlayerLoopHelper.Initialize(ref loop, InjectPlayerLoopTimings.Minimum); // minimum is Update | FixedUpdate | LastPostLateUpdate\n```\n\n`InjectPlayerLoopTimings` has three preset, `All` and `Standard`(All without last except LastPostLateUpdate), `Minimum`(`Update | FixedUpdate | LastPostLateUpdate`). Default is All and you can combine custom inject timings like `InjectPlayerLoopTimings.Update | InjectPlayerLoopTimings.FixedUpdate | InjectPlayerLoopTimings.PreLateUpdate`.\n\nYou can make error to use uninjected `PlayerLoopTiming` by [Microsoft.CodeAnalysis.BannedApiAnalyzers](https://github.com/dotnet/roslyn-analyzers/blob/master/src/Microsoft.CodeAnalysis.BannedApiAnalyzers/BannedApiAnalyzers.Help.md). For example, you can setup `BannedSymbols.txt` like this for `InjectPlayerLoopTimings.Minimum`.\n\n```txt\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.Initialization; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastInitialization; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.EarlyUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastEarlyUpdate; Isn't injected this PlayerLoop in this project.d\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastFixedUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.PreUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastPreUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.PreLateUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastPreLateUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.PostLateUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.TimeUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastTimeUpdate; Isn't injected this PlayerLoop in this project.\n```\n\nYou can configure `RS0030` severity to error.\n\n\n\nasync void vs async UniTaskVoid\n---\n`async void` is a standard C# task system so it does not run on UniTask systems. It is better not to use it. `async UniTaskVoid` is a lightweight version of `async UniTask` because it does not have awaitable completion and reports errors immediately to `UniTaskScheduler.UnobservedTaskException`. If you don't require awaiting (fire and forget), using `UniTaskVoid` is better. Unfortunately to dismiss warning, you're required to call `Forget()`.\n\n```csharp\npublic async UniTaskVoid FireAndForgetMethod()\n{\n // do anything...\n await UniTask.Yield();\n}\n\npublic void Caller()\n{\n FireAndForgetMethod().Forget();\n}\n```\n\nAlso UniTask has the `Forget` method, it is similar to `UniTaskVoid` and has the same effects. However `UniTaskVoid` is more efficient if you completely don't use `await`。\n\n```csharp\npublic async UniTask DoAsync()\n{\n // do anything...\n await UniTask.Yield();\n}\n\npublic void Caller()\n{\n DoAsync().Forget();\n}\n```\n\nTo use an async lambda registered to an event, don't use `async void`. Instead you can use `UniTask.Action` or `UniTask.UnityAction`, both of which create a delegate via `async UniTaskVoid` lambda.\n\n```csharp\nAction actEvent;\nUnityAction unityEvent; // especially used in uGUI\n\n// Bad: async void\nactEvent += async () => { };\nunityEvent += async () => { };\n\n// Ok: create Action delegate by lambda\nactEvent += UniTask.Action(async () => { await UniTask.Yield(); });\nunityEvent += UniTask.UnityAction(async () => { await UniTask.Yield(); });\n```\n\n`UniTaskVoid` can also be used in MonoBehaviour's `Start` method.\n\n```csharp\nclass Sample : MonoBehaviour\n{\n async UniTaskVoid Start()\n {\n // async init code.\n }\n}\n```\n\nUniTaskTracker\n---\nuseful for checking (leaked) UniTasks. You can open tracker window in `Window -> UniTask Tracker`.\n\n\n\n* Enable AutoReload(Toggle) - Reload automatically.\n* Reload - Reload view.\n* GC.Collect - Invoke GC.Collect.\n* Enable Tracking(Toggle) - Start to track async/await UniTask. Performance impact: low.\n* Enable StackTrace(Toggle) - Capture StackTrace when task is started. Performance impact: high.\n\nUniTaskTracker is intended for debugging use only as enabling tracking and capturing stacktraces is useful but has a heavy performance impact. Recommended usage is to enable both tracking and stacktraces to find task leaks and to disable them both when done.\n\nExternal Assets\n---\nBy default, UniTask supports TextMeshPro(`BindTo(TMP_Text)` and `TMP_InputField` event extensions like standard uGUI `InputField`), DOTween(`Tween` as awaitable) and Addressables(`AsyncOperationHandle` and `AsyncOperationHandle` as awaitable).\n\nThere are defined in separated asmdefs like `UniTask.TextMeshPro`, `UniTask.DOTween`, `UniTask.Addressables`.\n\nTextMeshPro and Addressables support are automatically enabled when importing their packages from package manager. \nHowever for DOTween support, after importing from the [DOTWeen assets](https://assetstore.unity.com/packages/tools/animation/dotween-hotween-v2-27676r) and define the scripting define symbol `UNITASK_DOTWEEN_SUPPORT` to enable it.\n\n```csharp\n// sequential\nawait transform.DOMoveX(2, 10);\nawait transform.DOMoveZ(5, 20);\n\n// parallel with cancellation\nvar ct = this.GetCancellationTokenOnDestroy();\n\nawait UniTask.WhenAll(\n transform.DOMoveX(10, 3).WithCancellation(ct),\n transform.DOScale(10, 3).WithCancellation(ct));\n```\n\nDOTween support's default behaviour(`await`, `WithCancellation`, `ToUniTask`) awaits tween is killed. It works on both Complete(true/false) and Kill(true/false). But if you want to reuse tweens (`SetAutoKill(false)`), it does not work as expected. If you want to await for another timing, the following extension methods exist in Tween, `AwaitForComplete`, `AwaitForPause`, `AwaitForPlay`, `AwaitForRewind`, `AwaitForStepComplete`.\n\nAsyncEnumerable and Async LINQ\n---\nUnity 2020.2 supports C# 8.0 so you can use `await foreach`. This is the new Update notation in the async era.\n\n```csharp\n// Unity 2020.2, C# 8.0\nawait foreach (var _ in UniTaskAsyncEnumerable.EveryUpdate().WithCancellation(token))\n{\n Debug.Log(\"Update() \" + Time.frameCount);\n}\n```\n\nIn a C# 7.3 environment, you can use the `ForEachAsync` method to work in almost the same way.\n\n```csharp\n// C# 7.3(Unity 2018.3~)\nawait UniTaskAsyncEnumerable.EveryUpdate().ForEachAsync(_ =>\n{\n Debug.Log(\"Update() \" + Time.frameCount);\n}, token);\n```\n\n`UniTask.WhenEach` that is similar to .NET 9's `Task.WhenEach` can consume new way for await multiple tasks.\n\n```csharp\nawait foreach (var result in UniTask.WhenEach(task1, task2, task3))\n{\n // The result is of type WhenEachResult.\n // It contains either `T Result` or `Exception Exception`.\n // You can check `IsCompletedSuccessfully` or `IsFaulted` to determine whether to access `.Result` or `.Exception`.\n // If you want to throw an exception when `IsFaulted` and retrieve the result when successful, use `GetResult()`.\n Debug.Log(result.GetResult());\n}\n```\n\nUniTaskAsyncEnumerable implements asynchronous LINQ, similar to LINQ in `IEnumerable` or Rx in `IObservable`. All standard LINQ query operators can be applied to asynchronous streams. For example, the following code shows how to apply a Where filter to a button-click asynchronous stream that runs once every two clicks.\n\n```csharp\nawait okButton.OnClickAsAsyncEnumerable().Where((x, i) => i % 2 == 0).ForEachAsync(_ =>\n{\n});\n```\n\nFire and Forget style(for example, event handling), you can also use `Subscribe`.\n\n```csharp\nokButton.OnClickAsAsyncEnumerable().Where((x, i) => i % 2 == 0).Subscribe(_ =>\n{\n});\n```\n\nAsync LINQ is enabled when `using Cysharp.Threading.Tasks.Linq;`, and `UniTaskAsyncEnumerable` is defined in `UniTask.Linq` asmdef.\n\nIt's closer to UniRx (Reactive Extensions), but UniTaskAsyncEnumerable is a pull-based asynchronous stream, whereas Rx was a push-based asynchronous stream. Note that although similar, the characteristics are different and the details behave differently along with them.\n\n`UniTaskAsyncEnumerable` is the entry point like `Enumerable`. In addition to the standard query operators, there are other generators for Unity such as `EveryUpdate`, `Timer`, `TimerFrame`, `Interval`, `IntervalFrame`, and `EveryValueChanged`. And also added additional UniTask original query operators like `Append`, `Prepend`, `DistinctUntilChanged`, `ToHashSet`, `Buffer`, `CombineLatest`,`Merge` `Do`, `Never`, `ForEachAsync`, `Pairwise`, `Publish`, `Queue`, `Return`, `SkipUntil`, `TakeUntil`, `SkipUntilCanceled`, `TakeUntilCanceled`, `TakeLast`, `Subscribe`.\n\nThe method with Func as an argument has three additional overloads, `***Await`, `***AwaitWithCancellation`.\n\n```csharp\nSelect(Func selector)\nSelectAwait(Func> selector)\nSelectAwaitWithCancellation(Func> selector)\n```\n\nIf you want to use the `async` method inside the func, use the `***Await` or `***AwaitWithCancellation`.\n\nHow to create an async iterator: C# 8.0 supports async iterator(`async yield return`) but it only allows `IAsyncEnumerable` and of course requires C# 8.0. UniTask supports `UniTaskAsyncEnumerable.Create` method to create custom async iterator.\n\n```csharp\n// IAsyncEnumerable, C# 8.0 version of async iterator. ( do not use this style, IAsyncEnumerable is not controled in UniTask).\npublic async IAsyncEnumerable MyEveryUpdate([EnumeratorCancellation]CancellationToken cancelationToken = default)\n{\n var frameCount = 0;\n await UniTask.Yield();\n while (!token.IsCancellationRequested)\n {\n yield return frameCount++;\n await UniTask.Yield();\n }\n}\n\n// UniTaskAsyncEnumerable.Create and use `await writer.YieldAsync` instead of `yield return`.\npublic IUniTaskAsyncEnumerable MyEveryUpdate()\n{\n // writer(IAsyncWriter) has `YieldAsync(value)` method.\n return UniTaskAsyncEnumerable.Create(async (writer, token) =>\n {\n var frameCount = 0;\n await UniTask.Yield();\n while (!token.IsCancellationRequested)\n {\n await writer.YieldAsync(frameCount++); // instead of `yield return`\n await UniTask.Yield();\n }\n });\n}\n```\n\nAwaitable Events\n---\nAll uGUI component implements `***AsAsyncEnumerable` to convert asynchronous streams of events.\n\n```csharp\nasync UniTask TripleClick()\n{\n // In default, used button.GetCancellationTokenOnDestroy to manage lieftime of async\n await button.OnClickAsync();\n await button.OnClickAsync();\n await button.OnClickAsync();\n Debug.Log(\"Three times clicked\");\n}\n\n// more efficient way\nasync UniTask TripleClick()\n{\n using (var handler = button.GetAsyncClickEventHandler())\n {\n await handler.OnClickAsync();\n await handler.OnClickAsync();\n await handler.OnClickAsync();\n Debug.Log(\"Three times clicked\");\n }\n}\n\n// use async LINQ\nasync UniTask TripleClick(CancellationToken token)\n{\n await button.OnClickAsAsyncEnumerable().Take(3).Last();\n Debug.Log(\"Three times clicked\");\n}\n\n// use async LINQ2\nasync UniTask TripleClick(CancellationToken token)\n{\n await button.OnClickAsAsyncEnumerable().Take(3).ForEachAsync(_ =>\n {\n Debug.Log(\"Every clicked\");\n });\n Debug.Log(\"Three times clicked, complete.\");\n}\n```\n\nAll MonoBehaviour message events can convert async-streams by `AsyncTriggers` that can be enabled by `using Cysharp.Threading.Tasks.Triggers;`. AsyncTrigger can be created using `GetAsync***Trigger` and triggers itself as UniTaskAsyncEnumerable.\n\n```csharp\nvar trigger = this.GetOnCollisionEnterAsyncHandler();\nawait trigger.OnCollisionEnterAsync();\nawait trigger.OnCollisionEnterAsync();\nawait trigger.OnCollisionEnterAsync();\n\n// every moves.\nawait this.GetAsyncMoveTrigger().ForEachAsync(axisEventData =>\n{\n});\n```\n\n`AsyncReactiveProperty`, `AsyncReadOnlyReactiveProperty` is UniTask's version of ReactiveProperty. `BindTo` extension method of `IUniTaskAsyncEnumerable` for binding asynchronous stream values to Unity components(Text/Selectable/TMP/Text).\n\n```csharp\nvar rp = new AsyncReactiveProperty(99);\n\n// AsyncReactiveProperty itself is IUniTaskAsyncEnumerable, you can query by LINQ\nrp.ForEachAsync(x =>\n{\n Debug.Log(x);\n}, this.GetCancellationTokenOnDestroy()).Forget();\n\nrp.Value = 10; // push 10 to all subscriber\nrp.Value = 11; // push 11 to all subscriber\n\n// WithoutCurrent ignore initial value\n// BindTo bind stream value to unity components.\nrp.WithoutCurrent().BindTo(this.textComponent);\n\nawait rp.WaitAsync(); // wait until next value set\n\n// also exists ToReadOnlyAsyncReactiveProperty\nvar rp2 = new AsyncReactiveProperty(99);\nvar rorp = rp.CombineLatest(rp2, (x, y) => (x, y)).ToReadOnlyAsyncReactiveProperty(CancellationToken.None);\n```\n\nA pull-type asynchronous stream does not get the next values until the asynchronous processing in the sequence is complete. This could spill data from push-type events such as buttons.\n\n```csharp\n// can not get click event during 3 seconds complete.\nawait button.OnClickAsAsyncEnumerable().ForEachAwaitAsync(async x =>\n{\n await UniTask.Delay(TimeSpan.FromSeconds(3));\n});\n```\n\nIt is useful (prevent double-click) but not useful sometimes.\n\nUsing the `Queue()` method will also queue events during asynchronous processing.\n\n```csharp\n// queued message in asynchronous processing\nawait button.OnClickAsAsyncEnumerable().Queue().ForEachAwaitAsync(async x =>\n{\n await UniTask.Delay(TimeSpan.FromSeconds(3));\n});\n```\n\nOr use `Subscribe`, fire and forget style.\n\n```csharp\nbutton.OnClickAsAsyncEnumerable().Subscribe(async x =>\n{\n await UniTask.Delay(TimeSpan.FromSeconds(3));\n});\n```\n\nChannel\n---\n`Channel` is the same as [System.Threading.Tasks.Channels](https://docs.microsoft.com/en-us/dotnet/api/system.threading.channels?view=netcore-3.1) which is similar to a GoLang Channel.\n\nCurrently it only supports multiple-producer, single-consumer unbounded channels. It can create by `Channel.CreateSingleConsumerUnbounded()`.\n\nFor producer(`.Writer`), use `TryWrite` to push value and `TryComplete` to complete channel. For consumer(`.Reader`), use `TryRead`, `WaitToReadAsync`, `ReadAsync`, `Completion` and `ReadAllAsync` to read queued messages.\n\n`ReadAllAsync` returns `IUniTaskAsyncEnumerable` so query LINQ operators. Reader only allows single-consumer but uses `.Publish()` query operator to enable multicast message. For example, make pub/sub utility.\n\n```csharp\npublic class AsyncMessageBroker : IDisposable\n{\n Channel channel;\n\n IConnectableUniTaskAsyncEnumerable multicastSource;\n IDisposable connection;\n\n public AsyncMessageBroker()\n {\n channel = Channel.CreateSingleConsumerUnbounded();\n multicastSource = channel.Reader.ReadAllAsync().Publish();\n connection = multicastSource.Connect(); // Publish returns IConnectableUniTaskAsyncEnumerable.\n }\n\n public void Publish(T value)\n {\n channel.Writer.TryWrite(value);\n }\n\n public IUniTaskAsyncEnumerable Subscribe()\n {\n return multicastSource;\n }\n\n public void Dispose()\n {\n channel.Writer.TryComplete();\n connection.Dispose();\n }\n}\n```\n\nvs Awaitable\n---\nUnity 6 introduces the awaitable type, [Awaitable](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Awaitable.html). To put it simply, Awaitable can be considered a subset of UniTask, and in fact, Awaitable's design was influenced by UniTask. It should be able to handle PlayerLoop-based awaits, pooled Tasks, and support for cancellation with `CancellationToken` in a similar way. With its inclusion in the standard library, you may wonder whether to continue using UniTask or migrate to Awaitable. Here's a brief guide.\n\nFirst, the functionality provided by Awaitable is equivalent to what coroutines offer. Instead of `yield return`, you use await; `await NextFrameAsync()` replaces `yield return null`; and there are equivalents for `WaitForSeconds` and `EndOfFrame`. However, that's the extent of it. Being coroutine-based in terms of functionality, it lacks Task-based features. In practical application development using async/await, operations like `WhenAll` are essential. Additionally, UniTask enables many frame-based operations (such as `DelayFrame`) and more flexible PlayerLoopTiming control, which are not available in Awaitable. Of course, there's no Tracker Window either.\n\nTherefore, I recommend using UniTask for application development. UniTask is a superset of Awaitable and includes many essential features. For library development, where you want to avoid external dependencies, using Awaitable as a return type for methods would be appropriate. Awaitable can be converted to UniTask using `AsUniTask`, so there's no issue in handling Awaitable-based functionality within the UniTask library. Of course, if you don't need to worry about dependencies, using UniTask would be the best choice even for library development.\n\nFor Unit Testing\n---\nUnity's `[UnityTest]` attribute can test coroutine(IEnumerator) but can not test async. `UniTask.ToCoroutine` bridges async/await to coroutine so you can test async methods.\n\n```csharp\n[UnityTest]\npublic IEnumerator DelayIgnore() => UniTask.ToCoroutine(async () =>\n{\n var time = Time.realtimeSinceStartup;\n\n Time.timeScale = 0.5f;\n try\n {\n await UniTask.Delay(TimeSpan.FromSeconds(3), ignoreTimeScale: true);\n\n var elapsed = Time.realtimeSinceStartup - time;\n Assert.AreEqual(3, (int)Math.Round(TimeSpan.FromSeconds(elapsed).TotalSeconds, MidpointRounding.ToEven));\n }\n finally\n {\n Time.timeScale = 1.0f;\n }\n});\n```\n\nUniTask's own unit tests are written using Unity Test Runner and [Cysharp/RuntimeUnitTestToolkit](https://github.com/Cysharp/RuntimeUnitTestToolkit) to integrate with CI and check if IL2CPP is working.\n\nThreadPool limitation\n---\nMost UniTask methods run on a single thread (PlayerLoop), with only `UniTask.Run`(`Task.Run` equivalent) and `UniTask.SwitchToThreadPool` running on a thread pool. If you use a thread pool, it won't work with WebGL and so on.\n\n`UniTask.Run` is now deprecated. You can use `UniTask.RunOnThreadPool` instead. And also consider whether you can use `UniTask.Create` or `UniTask.Void`.\n\nIEnumerator.ToUniTask limitation\n---\nYou can convert coroutine(IEnumerator) to UniTask(or await directly) but it has some limitations.\n\n* `WaitForEndOfFrame`/`WaitForFixedUpdate`/`Coroutine` is not supported.\n* Consuming loop timing is not the same as `StartCoroutine`, it uses the specified `PlayerLoopTiming` and the default `PlayerLoopTiming.Update` is run before MonoBehaviour's `Update` and `StartCoroutine`'s loop.\n\nIf you want fully compatible conversion from coroutine to async, use the `IEnumerator.ToUniTask(MonoBehaviour coroutineRunner)` overload. It executes StartCoroutine on an instance of the argument MonoBehaviour and waits for it to complete in UniTask.\n\nFor UnityEditor\n---\nUniTask can run on Unity Editor like an Editor Coroutine. However, there are some limitations.\n\n* UniTask.Delay's DelayType.DeltaTime, UnscaledDeltaTime do not work correctly because they can not get deltaTime in editor. Therefore run on EditMode, automatically change DelayType to `DelayType.Realtime` that wait for the right time.\n* All PlayerLoopTiming run on the timing `EditorApplication.update`.\n* `-batchmode` with `-quit` does not work because Unity does not run `EditorApplication.update` and quit after a single frame. Instead, don't use `-quit` and quit manually with `EditorApplication.Exit(0)`.\n\nCompare with Standard Task API\n---\nUniTask has many standard Task-like APIs. This table shows what the alternative apis are.\n\nUse standard type.\n\n| .NET Type | UniTask Type | \n| --- | --- |\n| `IProgress` | --- |\n| `CancellationToken` | --- | \n| `CancellationTokenSource` | --- |\n\nUse UniTask type.\n\n| .NET Type | UniTask Type | \n| --- | --- |\n| `Task`/`ValueTask` | `UniTask` |\n| `Task`/`ValueTask` | `UniTask` |\n| `async void` | `async UniTaskVoid` | \n| `+= async () => { }` | `UniTask.Void`, `UniTask.Action`, `UniTask.UnityAction` |\n| --- | `UniTaskCompletionSource` |\n| `TaskCompletionSource` | `UniTaskCompletionSource`/`AutoResetUniTaskCompletionSource` |\n| `ManualResetValueTaskSourceCore` | `UniTaskCompletionSourceCore` |\n| `IValueTaskSource` | `IUniTaskSource` |\n| `IValueTaskSource` | `IUniTaskSource` |\n| `ValueTask.IsCompleted` | `UniTask.Status.IsCompleted()` |\n| `ValueTask.IsCompleted` | `UniTask.Status.IsCompleted()` |\n| `new Progress` | `Progress.Create` |\n| `CancellationToken.Register(UnsafeRegister)` | `CancellationToken.RegisterWithoutCaptureExecutionContext` |\n| `CancellationTokenSource.CancelAfter` | `CancellationTokenSource.CancelAfterSlim` |\n| `Channel.CreateUnbounded(false){ SingleReader = true }` | `Channel.CreateSingleConsumerUnbounded` |\n| `IAsyncEnumerable` | `IUniTaskAsyncEnumerable` |\n| `IAsyncEnumerator` | `IUniTaskAsyncEnumerator` |\n| `IAsyncDisposable` | `IUniTaskAsyncDisposable` |\n| `Task.Delay` | `UniTask.Delay` |\n| `Task.Yield` | `UniTask.Yield` |\n| `Task.Run` | `UniTask.RunOnThreadPool` |\n| `Task.WhenAll` | `UniTask.WhenAll` |\n| `Task.WhenAny` | `UniTask.WhenAny` |\n| `Task.WhenEach` | `UniTask.WhenEach` |\n| `Task.CompletedTask` | `UniTask.CompletedTask` |\n| `Task.FromException` | `UniTask.FromException` |\n| `Task.FromResult` | `UniTask.FromResult` |\n| `Task.FromCanceled` | `UniTask.FromCanceled` |\n| `Task.ContinueWith` | `UniTask.ContinueWith` |\n| `TaskScheduler.UnobservedTaskException` | `UniTaskScheduler.UnobservedTaskException` |\n\nPooling Configuration\n---\nUniTask aggressively caches async promise objects to achieve zero allocation (for technical details, see blog post [UniTask v2 — Zero Allocation async/await for Unity, with Asynchronous LINQ](https://medium.com/@neuecc/unitask-v2-zero-allocation-async-await-for-unity-with-asynchronous-linq-1aa9c96aa7dd)). By default, it caches all promises but you can configure `TaskPool.SetMaxPoolSize` to your value, the value indicates cache size per type. `TaskPool.GetCacheSizeInfo` returns currently cached objects in pool.\n\n```csharp\nforeach (var (type, size) in TaskPool.GetCacheSizeInfo())\n{\n Debug.Log(type + \":\" + size);\n}\n```\n\nAllocation on Profiler\n---\nIn UnityEditor the profiler shows allocation of compiler generated AsyncStateMachine but it only occurs in debug(development) build. C# Compiler generates AsyncStateMachine as class on Debug build and as struct on Release build.\n\nUnity supports Code Optimization option starting in 2020.1 (right, footer).\n\n\n\nYou can change C# compiler optimization to release to remove AsyncStateMachine allocation in development builds. This optimization option can also be set via `Compilation.CompilationPipeline-codeOptimization`, and `Compilation.CodeOptimization`.\n\nUniTaskSynchronizationContext\n---\nUnity's default SynchronizationContext(`UnitySynchronizationContext`) is a poor implementation for performance. UniTask bypasses `SynchronizationContext`(and `ExecutionContext`) so it does not use it but if exists in `async Task`, still used it. `UniTaskSynchronizationContext` is a replacement of `UnitySynchronizationContext` which is better for performance.\n\n```csharp\npublic class SyncContextInjecter\n{\n [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]\n public static void Inject()\n {\n SynchronizationContext.SetSynchronizationContext(new UniTaskSynchronizationContext());\n }\n}\n```\n\nThis is an optional choice and is not always recommended; `UniTaskSynchronizationContext` is less performant than `async UniTask` and is not a complete UniTask replacement. It also does not guarantee full behavioral compatibility with the `UnitySynchronizationContext`.\n\nAPI References\n---\nUniTask's API References are hosted at [cysharp.github.io/UniTask](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.html) by [DocFX](https://dotnet.github.io/docfx/) and [Cysharp/DocfXTemplate](https://github.com/Cysharp/DocfxTemplate).\n\nFor example, UniTask's factory methods can be seen at [UniTask#methods](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.UniTask.html#methods-1). UniTaskAsyncEnumerable's factory/extension methods can be seen at [UniTaskAsyncEnumerable#methods](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.Linq.UniTaskAsyncEnumerable.html#methods-1).\n\nUPM Package\n---\n### Install via git URL\n\nRequires a version of unity that supports path query parameter for git packages (Unity >= 2019.3.4f1, Unity >= 2020.1a21). You can add `https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask` to Package Manager\n\n\n\n\n\nor add `\"com.cysharp.unitask\": \"https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask\"` to `Packages/manifest.json`.\n\nIf you want to set a target version, UniTask uses the `*.*.*` release tag so you can specify a version like `#2.1.0`. For example `https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask#2.1.0`.\n\n\n.NET Core\n---\nFor .NET Core, use NuGet.\n\n> PM> Install-Package [UniTask](https://www.nuget.org/packages/UniTask)\n\nUniTask of .NET Core version is a subset of Unity UniTask with PlayerLoop dependent methods removed.\n\nIt runs at higher performance than the standard Task/ValueTask, but you should be careful to ignore the ExecutionContext/SynchronizationContext when using it. `AsyncLocal` also does not work because it ignores ExecutionContext.\n\nIf you use UniTask internally, but provide ValueTask as an external API, you can write it like the following(Inspired by [PooledAwait](https://github.com/mgravell/PooledAwait)).\n\n```csharp\npublic class ZeroAllocAsyncAwaitInDotNetCore\n{\n public ValueTask DoAsync(int x, int y)\n {\n return Core(this, x, y);\n\n static async UniTask Core(ZeroAllocAsyncAwaitInDotNetCore self, int x, int y)\n {\n // do anything...\n await Task.Delay(TimeSpan.FromSeconds(x + y));\n await UniTask.Yield();\n\n return 10;\n }\n }\n}\n\n// UniTask does not return to original SynchronizationContext but you can use helper `ReturnToCurrentSynchronizationContext`.\npublic ValueTask TestAsync()\n{\n await using (UniTask.ReturnToCurrentSynchronizationContext())\n {\n await UniTask.SwitchToThreadPool();\n // do anything..\n }\n}\n```\n\n.NET Core version is intended to allow users to use UniTask as an interface when sharing code with Unity (such as [Cysharp/MagicOnion](https://github.com/Cysharp/MagicOnion/)). .NET Core version of UniTask enables smooth code sharing.\n\nUtility methods such as WhenAll which are equivalent to UniTask are provided as [Cysharp/ValueTaskSupplement](https://github.com/Cysharp/ValueTaskSupplement).\n\nLicense\n---\nThis library is under the MIT License.\n"
},
{
"path": "README_CN.md",
"content": "UniTask\n===\n[](https://github.com/Cysharp/UniTask/actions) [](https://github.com/Cysharp/UniTask/releases)\n\n为Unity提供一个高性能，零堆内存分配的 async/await 异步方案。\n\n- 基于值类型的`UniTask`和自定义的 AsyncMethodBuilder 来实现零堆内存分配\n- 使所有 Unity 的 AsyncOperations 和 Coroutines 可等待\n- 基于 PlayerLoop 的任务（`UniTask.Yield`，`UniTask.Delay`，`UniTask.DelayFrame`等..）可以替换所有协程操作\n- 对 MonoBehaviour 消息事件和 uGUI 事件进行可等待/异步枚举扩展\n- 完全在 Unity 的 PlayerLoop 上运行，因此不使用Thread，并且同样能在 WebGL、wasm 等平台上运行。\n- 带有 Channel 和 AsyncReactiveProperty 的异步 LINQ\n- 提供一个 TaskTracker EditorWindow 以追踪所有 UniTask 分配来预防内存泄漏\n- 与原生 Task/ValueTask/IValueTaskSource 高度兼容的行为\n\n有关技术细节，请参阅博客文章：[UniTask v2 — 适用于 Unity 的零堆内存分配的async/await，支持异步 LINQ](https://medium.com/@neuecc/unitask-v2-zero-allocation-async-await-for-unity-with-asynchronous-linq-1aa9c96aa7dd) \n有关高级技巧，请参阅博客文章：[通过异步装饰器模式扩展 UnityWebRequest — UniTask 的高级技术](https://medium.com/@neuecc/extends-unitywebrequest-via-async-decorator-pattern-advanced-techniques-of-unitask-ceff9c5ee846)\n\n\n\n## 目录\n\n- [入门](#%E5%85%A5%E9%97%A8)\n- [UniTask 和 AsyncOperation 的基础知识](#unitask-%E5%92%8C-asyncoperation-%E7%9A%84%E5%9F%BA%E7%A1%80%E7%9F%A5%E8%AF%86)\n- [取消和异常处理](#%E5%8F%96%E6%B6%88%E5%92%8C%E5%BC%82%E5%B8%B8%E5%A4%84%E7%90%86)\n- [超时处理](#%E8%B6%85%E6%97%B6%E5%A4%84%E7%90%86)\n- [进度](#%E8%BF%9B%E5%BA%A6)\n- [PlayerLoop](#playerloop)\n- [async void 与 async UniTaskVoid 对比](#async-void-%E4%B8%8E-async-unitaskvoid-%E5%AF%B9%E6%AF%94)\n- [UniTaskTracker](#unitasktracker)\n- [外部拓展](#%E5%A4%96%E9%83%A8%E6%8B%93%E5%B1%95)\n- [AsyncEnumerable 和 Async LINQ](#asyncenumerable-%E5%92%8C-async-linq)\n- [可等待事件](#%E5%8F%AF%E7%AD%89%E5%BE%85%E4%BA%8B%E4%BB%B6)\n- [Channel](#channel)\n- [与 Awaitable 对比](#%E4%B8%8E-awaitable-%E5%AF%B9%E6%AF%94)\n- [单元测试](#%E5%8D%95%E5%85%83%E6%B5%8B%E8%AF%95)\n- [线程池的限制](#%E7%BA%BF%E7%A8%8B%E6%B1%A0%E7%9A%84%E9%99%90%E5%88%B6)\n- [IEnumerator.ToUniTask 的限制](#ienumeratortounitask-%E7%9A%84%E9%99%90%E5%88%B6)\n- [关于 UnityEditor](#%E5%85%B3%E4%BA%8E-unityeditor)\n- [与原生 Task API 对比](#%E4%B8%8E%E5%8E%9F%E7%94%9F-task-api-%E5%AF%B9%E6%AF%94)\n- [池化配置](#%E6%B1%A0%E5%8C%96%E9%85%8D%E7%BD%AE)\n- [Profiler 下的堆内存分配](#profiler-%E4%B8%8B%E7%9A%84%E5%A0%86%E5%86%85%E5%AD%98%E5%88%86%E9%85%8D)\n- [UniTaskSynchronizationContext](#unitasksynchronizationcontext)\n- [API 文档](#api-%E6%96%87%E6%A1%A3)\n- [UPM 包](#upm-%E5%8C%85)\n- [通过 git URL 安装](#%E9%80%9A%E8%BF%87-git-url-%E5%AE%89%E8%A3%85)\n- [关于 .NET Core](#%E5%85%B3%E4%BA%8E-net-core)\n- [许可证](#%E8%AE%B8%E5%8F%AF%E8%AF%81)\n\n\n\n入门\n---\n通过[UniTask/releases](https://github.com/Cysharp/UniTask/releases)页面中提供的[UPM 包](https://github.com/Cysharp/UniTask#upm-package)或资产包（`UniTask.*.*.*.unitypackage`）安装。\n\n```csharp\n// 使用 UniTask 所需的命名空间\nusing Cysharp.Threading.Tasks;\n\n// 您可以返回一个形如 UniTask(或 UniTask) 的类型，这种类型事为Unity定制的，作为替代原生 Task 的轻量级方案\n// 为 Unity 集成的零堆内存分配，快速调用，0消耗的 async/await 方案\nasync UniTask DemoAsync()\n{\n // 您可以等待一个 Unity 异步对象\n var asset = await Resources.LoadAsync(\"foo\");\n var txt = (await UnityWebRequest.Get(\"https://...\").SendWebRequest()).downloadHandler.text;\n await SceneManager.LoadSceneAsync(\"scene2\");\n\n // .WithCancellation 会启用取消功能，GetCancellationTokenOnDestroy 表示获取一个依赖对象生命周期的 Cancel 句柄，当对象被销毁时，将会调用这个 Cancel 句柄，从而实现取消的功能\n // 在 Unity 2022.2之后，您可以在 MonoBehaviour 中使用`destroyCancellationToken`\n var asset2 = await Resources.LoadAsync(\"bar\").WithCancellation(this.GetCancellationTokenOnDestroy());\n\n // .ToUniTask 可接收一个 progress 回调以及一些配置参数，Progress.Create 是 IProgress 的轻量级替代方案\n var asset3 = await Resources.LoadAsync(\"baz\").ToUniTask(Progress.Create(x => Debug.Log(x)));\n\n // 等待一个基于帧的延时操作（就像一个协程一样）\n await UniTask.DelayFrame(100); \n\n // yield return new WaitForSeconds/WaitForSecondsRealtime 的替代方案\n await UniTask.Delay(TimeSpan.FromSeconds(10), ignoreTimeScale: false);\n \n // 可以等待任何 playerloop 的生命周期（PreUpdate，Update，LateUpdate等）\n await UniTask.Yield(PlayerLoopTiming.PreLateUpdate);\n\n // yield return null 的替代方案\n await UniTask.Yield();\n await UniTask.NextFrame();\n\n // WaitForEndOfFrame 的替代方案\n#if UNITY_2023_1_OR_NEWER\n await UniTask.WaitForEndOfFrame();\n#else\n // 需要 MonoBehaviour（CoroutineRunner）\n await UniTask.WaitForEndOfFrame(this); // this是一个 MonoBehaviour\n#endif\n \n // yield return new WaitForFixedUpdate 的替代方案，（等同于 UniTask.Yield(PlayerLoopTiming.FixedUpdate)）\n await UniTask.WaitForFixedUpdate();\n \n // yield return WaitUntil 的替代方案\n await UniTask.WaitUntil(() => isActive == false);\n\n // WaitUntil 扩展，指定某个值改变时触发\n await UniTask.WaitUntilValueChanged(this, x => x.isActive);\n\n // 您可以直接 await 一个 IEnumerator 协程\n await FooCoroutineEnumerator();\n\n // 您可以直接 await 一个原生 task\n await Task.Run(() => 100);\n\n // 多线程示例，在此行代码后的内容都运行在一个线程池上\n await UniTask.SwitchToThreadPool();\n\n /* 工作在线程池上的代码 */\n\n // 转回主线程（等同于 UniRx 的`ObserveOnMainThread`）\n await UniTask.SwitchToMainThread();\n\n // 获取异步的 webrequest\n async UniTask GetTextAsync(UnityWebRequest req)\n {\n var op = await req.SendWebRequest();\n return op.downloadHandler.text;\n }\n\n var task1 = GetTextAsync(UnityWebRequest.Get(\"http://google.com\"));\n var task2 = GetTextAsync(UnityWebRequest.Get(\"http://bing.com\"));\n var task3 = GetTextAsync(UnityWebRequest.Get(\"http://yahoo.com\"));\n\n // 构造一个 async-wait，并通过元组语义轻松获取所有结果\n var (google, bing, yahoo) = await UniTask.WhenAll(task1, task2, task3);\n\n // WhenAll 的简写形式，元组可以直接 await\n var (google2, bing2, yahoo2) = await (task1, task2, task3);\n\n // 返回一个异步值，或者您也可以使用`UniTask`（无结果），`UniTaskVoid`（不可等待）\n return (asset as TextAsset)?.text ?? throw new InvalidOperationException(\"Asset not found\");\n}\n```\n\nUniTask 和 AsyncOperation 的基础知识\n---\nUniTask 功能依赖于 C# 7.0（[task-like custom async method builder feature](https://github.com/dotnet/roslyn/blob/master/docs/features/task-types.md)），所以需要`Unity 2018.3`之后的版本，官方支持的最低版本是`Unity 2018.4.13f1`。\n\n为什么需要 UniTask（自定义task对象）？因为原生 Task 太重，与 Unity 线程（单线程）相性不好。因为 Unity 的异步对象由 Unity 的引擎层自动调度，所以 UniTask 不使用线程和 SynchronizationContext/ExecutionContext。它实现了更快和更低的分配，并且与Unity完全兼容。\n\n您可以在使用`using Cysharp.Threading.Tasks;`时对`AsyncOperation`，`ResourceRequest`，`AssetBundleRequest`，`AssetBundleCreateRequest`，`UnityWebRequestAsyncOperation`，`AsyncGPUReadbackRequest`，`IEnumerator`以及其他的异步操作进行 await\n\nUniTask 提供了三种模式的扩展方法。\n\n```csharp\nawait asyncOperation;\n.WithCancellation(CancellationToken);\n.ToUniTask(IProgress, PlayerLoopTiming, CancellationToken);\n```\n\n`WithCancellation`是`ToUniTask`的简化版本，两者都返回`UniTask`。有关 cancellation 的详细信息，请参阅：[取消和异常处理](https://github.com/Cysharp/UniTask#cancellation-and-exception-handling)部分。\n\n> 注意：await 会在 PlayerLoop 执行await对象的相应native生命周期方法时返回（如果条件满足的话），而 WithCancellation 和 ToUniTask 是从指定的 PlayerLoop 生命周期执行时返回。有关 PlayLoop生命周期 的详细信息，请参阅：[PlayerLoop](https://github.com/Cysharp/UniTask#playerloop)部分。\n\n> 注意： AssetBundleRequest 有`asset`和`allAssets`，默认 await 返回`asset`。如果您想得到`allAssets`，您可以使用`AwaitForAllAssets()`方法。\n\n`UniTask`可以使用`UniTask.WhenAll`，`UniTask.WhenAny`，`UniTask.WhenEach`等实用函数。它们就像`Task.WhenAll`和`Task.WhenAny`，但它们返回的数据类型更好用。它们会返回值元组，因此您可以传递多种类型并解构每个结果。\n\n```csharp\npublic async UniTaskVoid LoadManyAsync()\n{\n // 并行加载.\n var (a, b, c) = await UniTask.WhenAll(\n LoadAsSprite(\"foo\"),\n LoadAsSprite(\"bar\"),\n LoadAsSprite(\"baz\"));\n}\n\nasync UniTask LoadAsSprite(string path)\n{\n var resource = await Resources.LoadAsync(path);\n return (resource as Sprite);\n}\n```\n\n如果您想要将一个回调转换为 UniTask，您可以使用`UniTaskCompletionSource`，它是`TaskCompletionSource`的轻量级版本。\n\n```csharp\npublic UniTask WrapByUniTaskCompletionSource()\n{\n var utcs = new UniTaskCompletionSource();\n\n // 当操作完成时，调用 utcs.TrySetResult();\n // 当操作失败时，调用 utcs.TrySetException();\n // 当操作取消时，调用 utcs.TrySetCanceled();\n\n return utcs.Task; //本质上就是返回了一个 UniTask\n}\n```\n\n您可以进行如下转换：
-`Task` -> `UniTask `：使用`AsUniTask`
-`UniTask` -> `UniTask`：使用 `AsAsyncUnitUniTask`
-`UniTask` -> `UniTask`：使用 `AsUniTask`。`UniTask` -> `UniTask`的转换是无消耗的。\n\n如果您想将异步转换为协程，您可以使用`.ToCoroutine()`，这对于您想只允许使用协程系统大有帮助。\n\nUniTask 不能 await 两次。这是与.NET Standard 2.1 中引入的[ValueTask/IValueTaskSource](https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.valuetask-1?view=netcore-3.1)具有相同的约束。\n\n> 千万不要对 `ValueTask` 实例执行以下操作：\n>\n> - 多次await实例。\n> - 多次调用 AsTask。\n> - 在操作尚未完成时调用 .Result 或 .GetAwaiter().GetResult()，或对它们进行多次调用。\n> - 对实例进行上述多种操作。\n>\n> 如果您执行了上述任何操作，则结果是未定义的。\n\n```csharp\nvar task = UniTask.DelayFrame(10);\nawait task;\nawait task; // 错误，抛出异常\n```\n\n如果实在需要多次 await 一个异步操作，可以使用支持多次调用的`UniTask.Lazy`。`.Preserve()`同样允许多次调用（由 UniTask 内部缓存结果）。这种方法在函数范围内有多次调用时很有用。\n\n同样的，`UniTaskCompletionSource`可以在同一个地方被 await 多次，或者在很多不同的地方被 await。\n\n取消和异常处理\n---\n一些 UniTask 工厂方法中有一个`CancellationToken cancellationToken = default`参数。Unity 的一些异步操作也有`WithCancellation(CancellationToken)`和`ToUniTask(..., CancellationToken cancellation = default)`扩展方法。\n\n可以通过原生的[`CancellationTokenSource`](https://docs.microsoft.com/en-us/dotnet/api/system.threading.cancellationtokensource)将 CancellationToken 传递给参数\n\n```csharp\nvar cts = new CancellationTokenSource();\n\ncancelButton.onClick.AddListener(() =>\n{\n cts.Cancel();\n});\n\nawait UnityWebRequest.Get(\"http://google.co.jp\").SendWebRequest().WithCancellation(cts.Token);\n\nawait UniTask.DelayFrame(1000, cancellationToken: cts.Token);\n```\n\nCancellationToken 可通过`CancellationTokenSource`或 MonoBehaviour 的扩展方法`GetCancellationTokenOnDestroy`来创建。\n\n```csharp\n// 这个 CancellationToken 的生命周期与 GameObject 的相同\nawait UniTask.DelayFrame(1000, cancellationToken: this.GetCancellationTokenOnDestroy());\n```\n\n对于链式取消，建议所有异步方法的最后一个参数都接受`CancellationToken cancellationToken`，并将`CancellationToken`从头传递到尾。\n\n```csharp\nawait FooAsync(this.GetCancellationTokenOnDestroy());\n\n// ---\n\nasync UniTask FooAsync(CancellationToken cancellationToken)\n{\n await BarAsync(cancellationToken);\n}\n\nasync UniTask BarAsync(CancellationToken cancellationToken)\n{\n await UniTask.Delay(TimeSpan.FromSeconds(3), cancellationToken);\n}\n```\n\n`CancellationToken`代表了异步操作的生命周期。您可以不使用默认的 CancellationTokenOnDestroy ，通过自定义的`CancellationToken`自行管理生命周期。\n\n```csharp\npublic class MyBehaviour : MonoBehaviour\n{\n CancellationTokenSource disableCancellation = new CancellationTokenSource();\n CancellationTokenSource destroyCancellation = new CancellationTokenSource();\n\n private void OnEnable()\n {\n if (disableCancellation != null)\n {\n disableCancellation.Dispose();\n }\n disableCancellation = new CancellationTokenSource();\n }\n\n private void OnDisable()\n {\n disableCancellation.Cancel();\n }\n\n private void OnDestroy()\n {\n destroyCancellation.Cancel();\n destroyCancellation.Dispose();\n }\n}\n```\n\n在Unity 2022.2之后，Unity在[MonoBehaviour.destroyCancellationToken](https://docs.unity3d.com/ScriptReference/MonoBehaviour-destroyCancellationToken.html)和[Application.exitCancellationToken](https://docs.unity3d.com/ScriptReference/Application-exitCancellationToken.html)中添加了 CancellationToken。\n\n当检测到取消时，所有方法都会向上游抛出并传播`OperationCanceledException`。当异常（不限于`OperationCanceledException`）没有在异步方法中处理时，它将被传播到`UniTaskScheduler.UnobservedTaskException`。默认情况下，将接收到的未处理异常作为一般异常写入日志。可以使用`UniTaskScheduler.UnobservedExceptionWriteLogType`更改日志级别。若想对接收到未处理异常时的处理进行自定义，请为`UniTaskScheduler.UnobservedTaskException`设置一个委托\n\n而`OperationCanceledException`是一种特殊的异常，会被`UnobservedTaskException`无视\n\n如果要取消异步 UniTask 方法中的行为，请手动抛出`OperationCanceledException`。\n\n```csharp\npublic async UniTask FooAsync()\n{\n await UniTask.Yield();\n throw new OperationCanceledException();\n}\n```\n\n如果您只想处理异常，忽略取消操作（让其传播到全局处理 cancellation 的地方），请使用异常过滤器。\n\n```csharp\npublic async UniTask BarAsync()\n{\n try\n {\n var x = await FooAsync();\n return x * 2;\n }\n catch (Exception ex) when (!(ex is OperationCanceledException)) // 在 C# 9.0 下改成 when (ex is not OperationCanceledException) \n {\n return -1;\n }\n}\n```\n\n抛出和捕获`OperationCanceledException`有点重度，如果比较在意性能开销，请使用`UniTask.SuppressCancellationThrow`以避免抛出 OperationCanceledException 。它将返回`(bool IsCanceled, T Result)`而不是抛出异常。\n\n```csharp\nvar (isCanceled, _) = await UniTask.DelayFrame(10, cancellationToken: cts.Token).SuppressCancellationThrow();\nif (isCanceled)\n{\n // ...\n}\n```\n\n注意：仅当您在源头处直接调用`UniTask.SuppressCancellationThrow`时才会抑制异常抛出。否则，返回值将被转换，且整个管道不会抑制异常抛出。\n\n`UniTask.Yield`和`UniTask.Delay`等功能依赖于 Unity 的 PlayerLoop，它们在 PlayerLoop 中确定`CancellationToken`状态。\n这意味着当`CancellationToken`被触发时，它们并不会立即取消。\n\n如果要更改此行为，实现立即取消，可将`cancelImmediately`标志设置为 true。\n\n```csharp\nawait UniTask.Yield(cancellationToken, cancelImmediately: true);\n```\n\n注意：比起默认行为，设置 `cancelImmediately` 为 true 并检测立即取消会有更多的性能开销。\n这是因为它使用了`CancellationToken.Register`；这比在 PlayerLoop 中检查 CancellationToken 更重度。\n\n超时处理\n---\n超时是取消的一种变体。您可以通过`CancellationTokenSouce.CancelAfterSlim(TimeSpan)`设置超时并将 CancellationToken 传递给异步方法。\n\n```csharp\nvar cts = new CancellationTokenSource();\ncts.CancelAfterSlim(TimeSpan.FromSeconds(5)); // 设置5s超时。\n\ntry\n{\n await UnityWebRequest.Get(\"http://foo\").SendWebRequest().WithCancellation(cts.Token);\n}\ncatch (OperationCanceledException ex)\n{\n if (ex.CancellationToken == cts.Token)\n {\n UnityEngine.Debug.Log(\"Timeout\");\n }\n}\n```\n\n> `CancellationTokenSouce.CancelAfter`是一个原生的 api。但是在 Unity 中您不应该使用它，因为它依赖于线程计时器。`CancelAfterSlim`是 UniTask 的扩展方法，它使用 PlayerLoop 代替了线程计时器。\n\n如果您想将超时与其他 cancellation 一起使用，请使用`CancellationTokenSource.CreateLinkedTokenSource`。\n\n```csharp\nvar cancelToken = new CancellationTokenSource();\ncancelButton.onClick.AddListener(()=>\n{\n cancelToken.Cancel(); // 点击按钮后取消。\n});\n\nvar timeoutToken = new CancellationTokenSource();\ntimeoutToken.CancelAfterSlim(TimeSpan.FromSeconds(5)); // 设置5s超时。\n\ntry\n{\n // 链接 token\n var linkedTokenSource = CancellationTokenSource.CreateLinkedTokenSource(cancelToken.Token, timeoutToken.Token);\n\n await UnityWebRequest.Get(\"http://foo\").SendWebRequest().WithCancellation(linkedTokenSource.Token);\n}\ncatch (OperationCanceledException ex)\n{\n if (timeoutToken.IsCancellationRequested)\n {\n UnityEngine.Debug.Log(\"Timeout.\");\n }\n else if (cancelToken.IsCancellationRequested)\n {\n UnityEngine.Debug.Log(\"Cancel clicked.\");\n }\n}\n```\n\n为减少每次调用异步方法时用于超时的 CancellationTokenSource 的堆内存分配，您可以使用 UniTask 的`TimeoutController`进行优化。\n\n```csharp\nTimeoutController timeoutController = new TimeoutController(); // 提前创建好，以便复用。\n\nasync UniTask FooAsync()\n{\n try\n {\n // 您可以通过 timeoutController.Timeout(TimeSpan) 把超时设置传递到 cancellationToken。\n await UnityWebRequest.Get(\"http://foo\").SendWebRequest()\n .WithCancellation(timeoutController.Timeout(TimeSpan.FromSeconds(5)));\n timeoutController.Reset(); // 当 await 完成后调用 Reset（停止超时计时器，并准备下一次复用）。\n }\n catch (OperationCanceledException ex)\n {\n if (timeoutController.IsTimeout())\n {\n UnityEngine.Debug.Log(\"timeout\");\n }\n }\n}\n```\n\n如果您想将超时结合其他取消源一起使用，请使用`new TimeoutController(CancellationToken)`.\n\n```csharp\nTimeoutController timeoutController;\nCancellationTokenSource clickCancelSource;\n\nvoid Start()\n{\n this.clickCancelSource = new CancellationTokenSource();\n this.timeoutController = new TimeoutController(clickCancelSource);\n}\n```\n\n注意：UniTask 有`.Timeout`，`.TimeoutWithoutException`方法，但如果可以的话，尽量不要使用这些方法，请传递`CancellationToken`。因为`.Timeout`是在任务外部执行，所以无法停止超时任务。`.Timeout`意味着超时后忽略结果。如果您将一个`CancellationToken`传递给该方法，它将从任务内部执行，因此可以停止正在运行的任务。\n\n进度\n---\n一些 Unity 的异步操作具有`ToUniTask(IProgress progress = null, ...)`的扩展方法。\n\n```csharp\nvar progress = Progress.Create(x => Debug.Log(x));\n\nvar request = await UnityWebRequest.Get(\"http://google.co.jp\")\n .SendWebRequest()\n .ToUniTask(progress: progress);\n```\n\n您不应该使用原生的`new System.Progress`，因为每次调用它都会产生堆内存分配。请改用`Cysharp.Threading.Tasks.Progress`。这个 progress 工厂类有两个方法，`Create`和`CreateOnlyValueChanged`。`CreateOnlyValueChanged`仅在进度值更新时调用。\n\n为调用者实现 IProgress 接口会更好，这样不会因使用 lambda 而产生堆内存分配。\n\n```csharp\npublic class Foo : MonoBehaviour, IProgress\n{\n public void Report(float value)\n {\n UnityEngine.Debug.Log(value);\n }\n\n public async UniTaskVoid WebRequest()\n {\n var request = await UnityWebRequest.Get(\"http://google.co.jp\")\n .SendWebRequest()\n .ToUniTask(progress: this);\n }\n}\n```\n\nPlayerLoop\n---\nUniTask 运行在自定义的[PlayerLoop](https://docs.unity3d.com/ScriptReference/LowLevel.PlayerLoop.html)中。UniTask 中基于 PlayerLoop 的方法（如`Delay`、`DelayFrame`、`asyncOperation.ToUniTask`等）接受这个`PlayerLoopTiming`。\n\n```csharp\npublic enum PlayerLoopTiming\n{\n Initialization = 0,\n LastInitialization = 1,\n\n EarlyUpdate = 2,\n LastEarlyUpdate = 3,\n\n FixedUpdate = 4,\n LastFixedUpdate = 5,\n\n PreUpdate = 6,\n LastPreUpdate = 7,\n\n Update = 8,\n LastUpdate = 9,\n\n PreLateUpdate = 10,\n LastPreLateUpdate = 11,\n\n PostLateUpdate = 12,\n LastPostLateUpdate = 13\n \n#if UNITY_2020_2_OR_NEWER\n TimeUpdate = 14,\n LastTimeUpdate = 15,\n#endif\n}\n```\n\n它表明了异步任务会在哪个时机运行，您可以查阅[PlayerLoopList.md](https://gist.github.com/neuecc/bc3a1cfd4d74501ad057e49efcd7bdae)以了解 Unity 的默认 PlayerLoop 以及注入的 UniTask 的自定义循环。\n\n`PlayerLoopTiming.Update`与协程中的`yield return null`类似，但它会在`ScriptRunBehaviourUpdate`时，Update（Update 和 uGUI 事件(button.onClick等）之前被调用，而 yield return null 是在`ScriptRunDelayedDynamicFrameRate`时被调用。`PlayerLoopTiming.FixedUpdate`类似于`WaitForFixedUpdate`。\n\n> `PlayerLoopTiming.LastPostLateUpdate`不等同于协程的`yield return new WaitForEndOfFrame()`。协程的 WaitForEndOfFrame 似乎在 PlayerLoop 完成后运行。一些需要协程结束帧的方法(`Texture2D.ReadPixels`，`ScreenCapture.CaptureScreenshotAsTexture`，`CommandBuffer`等)在 async/await 时无法正常工作。在这些情况下，请将 MonoBehaviour（用于运行协程）传递给`UniTask.WaitForEndOfFrame`。例如，`await UniTask.WaitForEndOfFrame(this);`是`yield return new WaitForEndOfFrame()`轻量级无堆内存分配的替代方案。\n\n> 注意：在 Unity 2023.1或更高的版本中，`await UniTask.WaitForEndOfFrame();`不再需要 MonoBehaviour。因为它使用了`UnityEngine.Awaitable.EndOfFrameAsync`。\n\n`yield return null`和`UniTask.Yield`相似但不同。`yield return null`总是返回下一帧但`UniTask.Yield`返回下一次调用。也就是说，`UniTask.Yield(PlayerLoopTiming.Update)`在 `PreUpdate`上调用，它返回同一帧。`UniTask.NextFrame()`保证返回下一帧，您可以认为它的行为与`yield return null`一致。\n\n> UniTask.Yield（不带 CancellationToken）是一种特殊类型，返回`YieldAwaitable`并在 YieldRunner 上运行。它是最轻量和最快的。\n\n`AsyncOperation`在原生生命周期返回。例如，await `SceneManager.LoadSceneAsync`在`EarlyUpdate.UpdatePreloading`时返回，在此之后，在`EarlyUpdate.ScriptRunDelayedStartupFrame`时调用已加载场景的`Start`方法。同样的，`await UnityWebRequest`在`EarlyUpdate.ExecuteMainThreadJobs`时返回。\n\n在 UniTask 中，直接 await 使用的是原生生命周期，而`WithCancellation`和`ToUniTask`使用的特定的生命周期。这通常不会有问题，但对于`LoadSceneAsync`，它会导致`Start`方法与 await 之后的逻辑的执行顺序错乱。所以建议不要使用`LoadSceneAsync.ToUniTask`。\n\n> 注意：在 Unity 2023.1或更高的版本中，当您使用新的`UnityEngine.Awaitable`方法（如`SceneManager.LoadSceneAsync`）时，请确保您的文件的 using 指令区域中包含`using UnityEngine;`。\n> 这可以通过避免使用`UnityEngine.AsyncOperation`版本来防止编译错误。\n\n在堆栈跟踪中，您可以检查它在 PlayerLoop 中的运行位置。\n\n\n\n默认情况下，UniTask 的 PlayerLoop 在`[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]`初始化。\n\n在 BeforeSceneLoad 中调用的方法，它们的执行顺序是不确定的，所以如果您想在其他 BeforeSceneLoad 方法中使用 UniTask，您应该尝试在此之前初始化好 PlayerLoop。\n\n```csharp\n// AfterAssembliesLoaded 表示将会在 BeforeSceneLoad 之前调用\n[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)]\npublic static void InitUniTaskLoop()\n{\n var loop = PlayerLoop.GetCurrentPlayerLoop();\n Cysharp.Threading.Tasks.PlayerLoopHelper.Initialize(ref loop);\n}\n```\n\n如果您导入了 Unity 的`Entities`包，则会在`BeforeSceneLoad`将自定义 PlayerLoop 重置为默认值，并注入 ECS 的循环。当 Unity 在 UniTask 的初始化方法执行之后调用了 ECS 的注入方法，UniTask 将不再起作用。\n\n为了解决这个问题，您可以在 ECS 初始化后重新初始化 UniTask PlayerLoop。\n\n```csharp\n// 获取 ECS Loop。\nvar playerLoop = ScriptBehaviourUpdateOrder.CurrentPlayerLoop;\n\n// 设置 UniTask PlayerLoop。\nPlayerLoopHelper.Initialize(ref playerLoop);\n```\n\n您可以通过调用`PlayerLoopHelper.IsInjectedUniTaskPlayerLoop()`来诊断 UniTask 的 PlayerLoop 是否准备就绪。并且`PlayerLoopHelper.DumpCurrentPlayerLoop`还会将所有当前 PlayerLoop 记录到控制台。\n\n```csharp\nvoid Start()\n{\n UnityEngine.Debug.Log(\"UniTaskPlayerLoop ready? \" + PlayerLoopHelper.IsInjectedUniTaskPlayerLoop());\n PlayerLoopHelper.DumpCurrentPlayerLoop();\n}\n```\n\n您可以通过移除未使用的 PlayerLoopTiming 注入来稍微优化循环成本。您可以在初始化时调用`PlayerLoopHelper.Initialize(InjectPlayerLoopTimings)`。\n\n```csharp\nvar loop = PlayerLoop.GetCurrentPlayerLoop();\nPlayerLoopHelper.Initialize(ref loop, InjectPlayerLoopTimings.Minimum); // Minimum 就是 Update | FixedUpdate | LastPostLateUpdate\n```\n\n`InjectPlayerLoopTimings`有三个预设，`All`，`Standard`（All 除 LastPostLateUpdate 外），`Minimum`（`Update | FixedUpdate | LastPostLateUpdate`）。默认为 All，您可以通过组合来自定义要注入的时机，例如`InjectPlayerLoopTimings.Update | InjectPlayerLoopTimings.FixedUpdate | InjectPlayerLoopTimings.PreLateUpdate`。\n\n使用未注入`PlayerLoopTiming`的[Microsoft.CodeAnalysis.BannedApiAnalyzers](https://github.com/dotnet/roslyn-analyzers/blob/master/src/Microsoft.CodeAnalysis.BannedApiAnalyzers/BannedApiAnalyzers.Help.md)可能会出错。例如，您可以像下列方式那样，为`InjectPlayerLoopTimings.Minimum`设置`BannedSymbols.txt`\n\n```txt\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.Initialization; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastInitialization; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.EarlyUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastEarlyUpdate; Isn't injected this PlayerLoop in this project.d\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastFixedUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.PreUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastPreUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.PreLateUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastPreLateUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.PostLateUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.TimeUpdate; Isn't injected this PlayerLoop in this project.\nF:Cysharp.Threading.Tasks.PlayerLoopTiming.LastTimeUpdate; Isn't injected this PlayerLoop in this project.\n```\n\n您可以将`RS0030`的严重性配置为错误。\n\n\n\nasync void 与 async UniTaskVoid 对比\n---\n`async void`是一个原生的 C# 任务系统，因此它不在 UniTask 系统上运行。也最好不要使用它。`async UniTaskVoid`是`async UniTask`的轻量级版本，因为它没有等待完成并立即向`UniTaskScheduler.UnobservedTaskException`报告错误。如果您不需要等待（即发即弃），那么使用`UniTaskVoid`会更好。不幸的是，要解除警告，您需要在尾部添加`Forget()`。\n\n```csharp\npublic async UniTaskVoid FireAndForgetMethod()\n{\n // do anything...\n await UniTask.Yield();\n}\n\npublic void Caller()\n{\n FireAndForgetMethod().Forget();\n}\n```\n\nUniTask 也有`Forget`方法，与`UniTaskVoid`类似且效果相同。如果您完全不需要使用`await`，那么使用`UniTaskVoid`会更高效。\n\n```csharp\npublic async UniTask DoAsync()\n{\n // do anything...\n await UniTask.Yield();\n}\n\npublic void Caller()\n{\n DoAsync().Forget();\n}\n```\n\n要使用注册到事件的异步 lambda，请不要使用`async void`。您可以使用`UniTask.Action` 或 `UniTask.UnityAction`来代替，这两者都通过`async UniTaskVoid` lambda 来创建委托。\n\n```csharp\nAction actEvent;\nUnityAction unityEvent; // UGUI 特供\n\n// 这样是不好的: async void\nactEvent += async () => { };\nunityEvent += async () => { };\n\n// 这样是可以的: 通过 lamada 创建 Action\nactEvent += UniTask.Action(async () => { await UniTask.Yield(); });\nunityEvent += UniTask.UnityAction(async () => { await UniTask.Yield(); });\n```\n\n`UniTaskVoid`也可以用在 MonoBehaviour 的`Start`方法中。\n\n```csharp\nclass Sample : MonoBehaviour\n{\n async UniTaskVoid Start()\n {\n // 异步初始化代码。\n }\n}\n```\n\nUniTaskTracker\n---\n对于检查（泄露的）UniTasks 很有用。您可以在`Window -> UniTask Tracker`中打开跟踪器窗口。\n\n\n\n- Enable AutoReload(Toggle) - 自动重新加载。\n- Reload - 重新加载视图（重新扫描内存中UniTask实例，并刷新界面）。\n- GC.Collect - 调用 GC.Collect。\n- Enable Tracking(Toggle) - 开始跟踪异步/等待 UniTask。性能影响：低。\n- Enable StackTrace(Toggle) - 在任务启动时捕获 StackTrace。性能影响：高。\n\nUniTaskTracker 仅用于调试用途，因为启用跟踪和捕获堆栈跟踪很有用，但会对性能产生重大影响。推荐的用法是只在查找任务泄漏时启用跟踪和堆栈跟踪，并在使用完毕后禁用它们。\n\n外部拓展\n---\n默认情况下，UniTask 支持 TextMeshPro（`BindTo(TMP_Text)`和像原生 uGUI `InputField` 那样的事件扩展，如`TMP_InputField`）、DOTween（`Tween`作为可等待的）和 Addressables（`AsyncOperationHandle`和`AsyncOperationHandle`作为可等待的）。\n\n它们被定义在了如`UniTask.TextMeshPro`，`UniTask.DOTween`，`UniTask.Addressables`等单独的 asmdef文件中。\n\n从包管理器中导入软件包时，会自动启用对 TextMeshPro 和 Addressables 的支持。\n但对于 DOTween 的支持，则需要从[DOTWeen assets](https://assetstore.unity.com/packages/tools/animation/dotween-hotween-v2-27676r)中导入并定义脚本定义符号`UNITASK_DOTWEEN_SUPPORT`后才能启用。\n\n```csharp\n// 动画序列\nawait transform.DOMoveX(2, 10);\nawait transform.DOMoveZ(5, 20);\n\n// 并行，并传递 cancellation 用于取消\nvar ct = this.GetCancellationTokenOnDestroy();\n\nawait UniTask.WhenAll(\n transform.DOMoveX(10, 3).WithCancellation(ct),\n transform.DOScale(10, 3).WithCancellation(ct));\n```\n\nDOTween 支持的默认行为（`await`，`WithCancellation`，`ToUniTask`） 会等待到 tween 被终止。它适用于 Complete(true/false) 和 Kill(true/false)。但是如果您想复用 tweens（`SetAutoKill(false)`），它就不能按预期工作。如果您想等待另一个时间点，Tween 中存在以下扩展方法，`AwaitForComplete`，`AwaitForPause`，`AwaitForPlay`，`AwaitForRewind`，`AwaitForStepComplete`。\n\nAsyncEnumerable 和 Async LINQ\n---\nUnity 2020.2 支持 C# 8.0，因此您可以使用`await foreach`。这是异步时代的新更新符号。\n\n```csharp\n// Unity 2020.2，C# 8.0\nawait foreach (var _ in UniTaskAsyncEnumerable.EveryUpdate().WithCancellation(token))\n{\n Debug.Log(\"Update() \" + Time.frameCount);\n}\n```\n\n在 C# 7.3 环境中，您可以使用`ForEachAsync`方法以几乎相同的方式工作。\n\n```csharp\n// C# 7.3(Unity 2018.3~)\nawait UniTaskAsyncEnumerable.EveryUpdate().ForEachAsync(_ =>\n{\n Debug.Log(\"Update() \" + Time.frameCount);\n}, token);\n```\n\n`UniTask.WhenEach`类似于 .NET 9 的`Task.WhenEach`，它可以使用新的方式来等待多个任务。\n\n```csharp\nawait foreach (var result in UniTask.WhenEach(task1, task2, task3))\n{\n // 结果的类型为 WhenEachResult。\n // 它包含 `T Result` or `Exception Exception`。\n // 您可以检查 `IsCompletedSuccessfully` 或 `IsFaulted` 以确定是访 `.Result` 还是 `.Exception`。\n // 如果希望在 `IsFaulted` 时抛出异常并在成功时获取结果，可以使用 `GetResult()`。\n Debug.Log(result.GetResult());\n}\n```\n\nUniTaskAsyncEnumerable 实现了异步 LINQ，类似于 LINQ 的`IEnumerable`或 Rx 的 `IObservable`。所有标准 LINQ 查询运算符都可以应用于异步流。例如，以下代码展示了如何将 Where 过滤器应用于每两次单击运行一次的按钮点击异步流。\n\n```csharp\nawait okButton.OnClickAsAsyncEnumerable().Where((x, i) => i % 2 == 0).ForEachAsync(_ =>\n{\n});\n```\n\n即发即弃（Fire and Forget）风格（例如，事件处理），您也可以使用`Subscribe`。\n\n```csharp\nokButton.OnClickAsAsyncEnumerable().Where((x, i) => i % 2 == 0).Subscribe(_ =>\n{\n});\n```\n\n在引入`using Cysharp.Threading.Tasks.Linq;`后，异步 LINQ 将被启用，并且`UniTaskAsyncEnumerable`在 asmdef 文件`UniTask.Linq`中定义。\n\n它更接近 UniRx（Reactive Extensions），但 UniTaskAsyncEnumerable 是基于 pull 的异步流，而 Rx 是基于 push 的异步流。请注意，尽管它们相似，但特性不同，细节也有所不同。\n\n`UniTaskAsyncEnumerable`是类似`Enumerable`的入口点。除了标准查询操作符之外，还为 Unity 提供了其他生成器，例如`EveryUpdate`、`Timer`、`TimerFrame`、`Interval`、`IntervalFrame`和`EveryValueChanged`。此外，还添加了 UniTask 原生的查询操作符，如`Append`，`Prepend`，`DistinctUntilChanged`，`ToHashSet`，`Buffer`，`CombineLatest`，`Do`，`Never`，`ForEachAsync`，`Pairwise`，`Publish`，`Queue`，`Return`，`SkipUntil`，`TakeUntil`，`SkipUntilCanceled`，`TakeUntilCanceled`，`TakeLast`，`Subscribe`。\n\n以 Func 作为参数的方法具有三个额外的重载，另外两个是`***Await`和`***AwaitWithCancellation`。\n\n```csharp\nSelect(Func selector)\nSelectAwait(Func> selector)\nSelectAwaitWithCancellation(Func> selector)\n```\n\n如果在 func 内部使用`async`方法，请使用`***Await`或`***AwaitWithCancellation`。\n\n如何创建异步迭代器：C# 8.0 支持异步迭代器（`async yield return`），但它只允许`IAsyncEnumerable`，当然也需要 C# 8.0。UniTask 支持使用`UniTaskAsyncEnumerable.Create`方法来创建自定义异步迭代器。\n\n```csharp\n// IAsyncEnumerable，C# 8.0 异步迭代器。（请不要这样使用，因为 IAsyncEnumerable 不被 UniTask 所控制）。\npublic async IAsyncEnumerable MyEveryUpdate([EnumeratorCancellation]CancellationToken cancelationToken = default)\n{\n var frameCount = 0;\n await UniTask.Yield();\n while (!token.IsCancellationRequested)\n {\n yield return frameCount++;\n await UniTask.Yield();\n }\n}\n\n// UniTaskAsyncEnumerable.Create 并用 `await writer.YieldAsync` 代替 `yield return`.\npublic IUniTaskAsyncEnumerable MyEveryUpdate()\n{\n // writer(IAsyncWriter) 有 `YieldAsync(value)` 方法。\n return UniTaskAsyncEnumerable.Create(async (writer, token) =>\n {\n var frameCount = 0;\n await UniTask.Yield();\n while (!token.IsCancellationRequested)\n {\n await writer.YieldAsync(frameCount++); // 代替 `yield return`\n await UniTask.Yield();\n }\n });\n}\n```\n\n可等待事件\n---\n所有 uGUI 组件都实现了`***AsAsyncEnumerable`，以实现对事件的异步流的转换。\n\n```csharp\nasync UniTask TripleClick()\n{\n // 默认情况下，使用了button.GetCancellationTokenOnDestroy 来管理异步生命周期\n await button.OnClickAsync();\n await button.OnClickAsync();\n await button.OnClickAsync();\n Debug.Log(\"Three times clicked\");\n}\n\n// 更高效的方法\nasync UniTask TripleClick()\n{\n using (var handler = button.GetAsyncClickEventHandler())\n {\n await handler.OnClickAsync();\n await handler.OnClickAsync();\n await handler.OnClickAsync();\n Debug.Log(\"Three times clicked\");\n }\n}\n\n// 使用异步 LINQ\nasync UniTask TripleClick(CancellationToken token)\n{\n await button.OnClickAsAsyncEnumerable().Take(3).Last();\n Debug.Log(\"Three times clicked\");\n}\n\n// 使用异步 LINQ\nasync UniTask TripleClick(CancellationToken token)\n{\n await button.OnClickAsAsyncEnumerable().Take(3).ForEachAsync(_ =>\n {\n Debug.Log(\"Every clicked\");\n });\n Debug.Log(\"Three times clicked, complete.\");\n}\n```\n\n所有 MonoBehaviour 消息事件均可通过`AsyncTriggers`转换成异步流，`AsyncTriggers`可通过引入`using Cysharp.Threading.Tasks.Triggers;`来启用。`AsyncTriggers`可以使用`GetAsync***Trigger`来创建，并将它作为 UniTaskAsyncEnumerable 来触发。\n\n```csharp\nvar trigger = this.GetOnCollisionEnterAsyncHandler();\nawait trigger.OnCollisionEnterAsync();\nawait trigger.OnCollisionEnterAsync();\nawait trigger.OnCollisionEnterAsync();\n\n// 每次移动触发。\nawait this.GetAsyncMoveTrigger().ForEachAsync(axisEventData =>\n{\n});\n```\n\n`AsyncReactiveProperty`，`AsyncReadOnlyReactiveProperty`是 UniTask 的 ReactiveProperty 版本。`BindTo`的`IUniTaskAsyncEnumerable`扩展方法，可以把异步流值绑定到 Unity 组件（Text/Selectable/TMP/Text）。\n\n```csharp\nvar rp = new AsyncReactiveProperty(99);\n\n// AsyncReactiveProperty 本身是 IUniTaskAsyncEnumerable，可以通过 LINQ 进行查询\nrp.ForEachAsync(x =>\n{\n Debug.Log(x);\n}, this.GetCancellationTokenOnDestroy()).Forget();\n\nrp.Value = 10; // 推送10给所有订阅者\nrp.Value = 11; // 推送11给所有订阅者\n\n// WithoutCurrent 忽略初始值\n// BindTo 绑定 stream value 到 unity 组件.\nrp.WithoutCurrent().BindTo(this.textComponent);\n\nawait rp.WaitAsync(); // 一直等待，直到下一个值被设置\n\n// 同样支持 ToReadOnlyAsyncReactiveProperty\nvar rp2 = new AsyncReactiveProperty(99);\nvar rorp = rp.CombineLatest(rp2, (x, y) => (x, y)).ToReadOnlyAsyncReactiveProperty(CancellationToken.None);\n```\n\n在序列中的异步处理完成之前，pull-based异步流不会获取下一个值。这可能会从按钮等推送类型的事件中溢出数据。\n\n```csharp\n// 在3s延迟结束前，无法获取 event\nawait button.OnClickAsAsyncEnumerable().ForEachAwaitAsync(async x =>\n{\n await UniTask.Delay(TimeSpan.FromSeconds(3));\n});\n```\n\n它（在防止双击方面）是有用的，但有时也并非都有用。\n\n使用`Queue()`方法在异步处理期间也会对事件进行排队。\n\n```csharp\n// 异步处理中对 message 进行排队\nawait button.OnClickAsAsyncEnumerable().Queue().ForEachAwaitAsync(async x =>\n{\n await UniTask.Delay(TimeSpan.FromSeconds(3));\n});\n```\n\n或使用即发即弃风格的`Subscribe`。\n\n```csharp\nbutton.OnClickAsAsyncEnumerable().Subscribe(async x =>\n{\n await UniTask.Delay(TimeSpan.FromSeconds(3));\n});\n```\n\nChannel\n---\n`Channel`与[System.Threading.Tasks.Channels](https://docs.microsoft.com/en-us/dotnet/api/system.threading.channels?view=netcore-3.1)相同，类似于 GoLang Channel。\n\n目前只支持多生产者、单消费者无界 Channel。它可以通过`Channel.CreateSingleConsumerUnbounded()`来创建。\n\n对于生产者(`.Writer`)，使用`TryWrite`来推送值，使用`TryComplete`来完成 Channel。对于消费者(`.Reader`)，使用`TryRead`、`WaitToReadAsync`、`ReadAsync`和`Completion`，`ReadAllAsync`来读取队列的消息。\n\n`ReadAllAsync`返回`IUniTaskAsyncEnumerable` 因此可以使用 LINQ 操作符。Reader 只允许单消费者，但可以使用`.Publish()`查询操作符来启用多播消息。例如，可以制作发布/订阅工具。\n\n```csharp\npublic class AsyncMessageBroker : IDisposable\n{\n Channel channel;\n\n IConnectableUniTaskAsyncEnumerable multicastSource;\n IDisposable connection;\n\n public AsyncMessageBroker()\n {\n channel = Channel.CreateSingleConsumerUnbounded();\n multicastSource = channel.Reader.ReadAllAsync().Publish();\n connection = multicastSource.Connect(); // Publish returns IConnectableUniTaskAsyncEnumerable.\n }\n\n public void Publish(T value)\n {\n channel.Writer.TryWrite(value);\n }\n\n public IUniTaskAsyncEnumerable Subscribe()\n {\n return multicastSource;\n }\n\n public void Dispose()\n {\n channel.Writer.TryComplete();\n connection.Dispose();\n }\n}\n```\n\n与 Awaitable 对比\n---\nUnity 6 引入了可等待类型[Awaitable](https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Awaitable.html)。简而言之，Awaitable 可以被认为是 UniTask 的一个子集，并且事实上，Awaitable的设计也受 UniTask 的影响。它应该能够处理基于 PlayerLoop 的 await，池化 Task，以及支持以类似的方式使用`CancellationToken`进行取消。随着它被包含在标准库中，您可能想知道是继续使用 UniTask 还是迁移到 Awaitable。以下是简要指南。\n\n首先，Awaitable 提供的功能与协程提供的功能相同。使用 await 代替`yield return`；`await NextFrameAsync()`代替`yield return null`；`WaitForSeconds`和`EndOfFrame`等价。然而，这只是两者之间的差异。就功能而言，它是基于协程的，缺乏基于 Task 的特性。在使用 async/await 的实际应用程序开发中，像`WhenAll`这样的操作是必不可少的。此外，UniTask 支持许多基于帧的操作（如`DelayFrame`）和更灵活的 PlayerLoopTiming 控制，这些在 Awaitable 中是不可用的。当然，它也没有跟踪器窗口。\n\n因此，我推荐在应用程序开发中使用 UniTask。UniTask 是 Awaitable 的超集，并包含了许多基本特性。对于库开发，如果您希望避免外部依赖，可以使用 Awaitable 作为方法的返回类型。因为 Awaitable 可以使用`AsUniTask`转换为 UniTask，所以支持在 UniTask 库中处理基于 Awaitable 的功能。即便是在库开发中，如果您不需要担心依赖关系，使用 UniTask 也会是您的最佳选择。\n\n单元测试\n---\nUnity 的`[UnityTest]`属性可以测试协程（IEnumerator）但不能测试异步。`UniTask.ToCoroutine`将 async/await 桥接到协程，以便您可以测试异步方法。\n\n```csharp\n[UnityTest]\npublic IEnumerator DelayIgnore() => UniTask.ToCoroutine(async () =>\n{\n var time = Time.realtimeSinceStartup;\n\n Time.timeScale = 0.5f;\n try\n {\n await UniTask.Delay(TimeSpan.FromSeconds(3), ignoreTimeScale: true);\n\n var elapsed = Time.realtimeSinceStartup - time;\n Assert.AreEqual(3, (int)Math.Round(TimeSpan.FromSeconds(elapsed).TotalSeconds, MidpointRounding.ToEven));\n }\n finally\n {\n Time.timeScale = 1.0f;\n }\n});\n```\n\nUniTask 自身的单元测试是使用 Unity Test Runner 和[Cysharp/RuntimeUnitTestToolkit](https://github.com/Cysharp/RuntimeUnitTestToolkit)编写的，以集成到 CI 中并检查 IL2CPP 是否正常工作。\n\n## 线程池的限制\n\n大多数 UniTask 方法在单个线程 (PlayerLoop) 上运行，只有`UniTask.Run`（等同于`Task.Run`）和`UniTask.SwitchToThreadPool`在线程池上运行。如果您使用线程池，它将无法与 WebGL 等平台兼容。\n\n`UniTask.Run`现在已弃用。您可以改用`UniTask.RunOnThreadPool`。并且还要考虑是否可以使用`UniTask.Create`或`UniTask.Void`。\n\n## IEnumerator.ToUniTask 的限制\n\n您可以将协程（IEnumerator）转换为 UniTask（或直接 await），但它有一些限制。\n\n- 不支持`WaitForEndOfFrame`，`WaitForFixedUpdate`，`Coroutine`\n- 生命周期与`StartCoroutine`不一样，它使用指定的`PlayerLoopTiming`，并且默认情况下，`PlayerLoopTiming.Update`在 MonoBehaviour 的`Update`和`StartCoroutine`的循环之前执行。\n\n如果您想要实现从协程到异步的完全兼容转换，请使用`IEnumerator.ToUniTask(MonoBehaviour coroutineRunner)`重载。它会在传入的 MonoBehaviour 实例中执行 StartCoroutine 并在 UniTask 中等待它完成。\n\n## 关于 UnityEditor\n\nUniTask 可以像编辑器协程一样在 Unity 编辑器上运行。但它有一些限制。\n\n- UniTask.Delay 的 DelayType.DeltaTime、UnscaledDeltaTime 无法正常工作，因为它们无法在编辑器中获取 deltaTime。因此在 EditMode 下运行时，会自动将 DelayType 更改为能等待正确的时间的`DelayType.Realtime`。\n- 所有 PlayerLoopTiming 都在`EditorApplication.update`生命周期上运行。\n- 带`-quit`的`-batchmode`不起作用，因为 Unity 不会执行 `EditorApplication.update` 并在一帧后退出。因此，不要使用`-quit`并使用`EditorApplication.Exit(0)`手动退出。\n\n与原生 Task API 对比\n---\nUniTask 有许多原生的类Task API。此表展示了两者相对应的 API。\n\n使用原生类型。\n\n| .NET 类型 | UniTask 类型 | \n|---------------------------| --- |\n| `IProgress` | --- |\n| `CancellationToken` | --- | \n| `CancellationTokenSource` | --- |\n\n使用 UniTask 类型。\n\n| .NET 类型 | UniTask 类型 | \n| --- | --- |\n| `Task`/`ValueTask` | `UniTask` |\n| `Task`/`ValueTask` | `UniTask` |\n| `async void` | `async UniTaskVoid` | \n| `+= async () => { }` | `UniTask.Void`, `UniTask.Action`, `UniTask.UnityAction` |\n| --- | `UniTaskCompletionSource` |\n| `TaskCompletionSource` | `UniTaskCompletionSource`/`AutoResetUniTaskCompletionSource` |\n| `ManualResetValueTaskSourceCore` | `UniTaskCompletionSourceCore` |\n| `IValueTaskSource` | `IUniTaskSource` |\n| `IValueTaskSource` | `IUniTaskSource` |\n| `ValueTask.IsCompleted` | `UniTask.Status.IsCompleted()` |\n| `ValueTask.IsCompleted` | `UniTask.Status.IsCompleted()` |\n| `new Progress` | `Progress.Create` |\n| `CancellationToken.Register(UnsafeRegister)` | `CancellationToken.RegisterWithoutCaptureExecutionContext` |\n| `CancellationTokenSource.CancelAfter` | `CancellationTokenSource.CancelAfterSlim` |\n| `Channel.CreateUnbounded(false){ SingleReader = true }` | `Channel.CreateSingleConsumerUnbounded` |\n| `IAsyncEnumerable` | `IUniTaskAsyncEnumerable` |\n| `IAsyncEnumerator` | `IUniTaskAsyncEnumerator` |\n| `IAsyncDisposable` | `IUniTaskAsyncDisposable` |\n| `Task.Delay` | `UniTask.Delay` |\n| `Task.Yield` | `UniTask.Yield` |\n| `Task.Run` | `UniTask.RunOnThreadPool` |\n| `Task.WhenAll` | `UniTask.WhenAll` |\n| `Task.WhenAny` | `UniTask.WhenAny` |\n| `Task.WhenEach` | `UniTask.WhenEach` |\n| `Task.CompletedTask` | `UniTask.CompletedTask` |\n| `Task.FromException` | `UniTask.FromException` |\n| `Task.FromResult` | `UniTask.FromResult` |\n| `Task.FromCanceled` | `UniTask.FromCanceled` |\n| `Task.ContinueWith` | `UniTask.ContinueWith` |\n| `TaskScheduler.UnobservedTaskException` | `UniTaskScheduler.UnobservedTaskException` |\n\n池化配置\n---\nUniTask 通过积极缓存异步 promise 对象实现零堆内存分配（有关技术细节，请参阅博客文章[UniTask v2 — 适用于 Unity 的零堆内存分配的async/await，支持异步 LINQ](https://medium.com/@neuecc/unitask-v2-zero-allocation-async-await-for-unity-with-asynchronous-linq-1aa9c96aa7dd)）。默认情况下，它缓存所有 promise，但您可以通过调用`TaskPool.SetMaxPoolSize`方法来自定义每种类型的最大缓存大小。`TaskPool.GetCacheSizeInfo`返回池中当前缓存的对象。\n\n```csharp\nforeach (var (type, size) in TaskPool.GetCacheSizeInfo())\n{\n Debug.Log(type + \":\" + size);\n}\n```\n\nProfiler 下的堆内存分配\n---\n在 UnityEditor 中，能从 profiler 中看到编译器生成的 AsyncStateMachine 的堆内存分配，但它只出现在Debug（development）构建中。C# 编译器在Debug 构建时将 AsyncStateMachine 生成为类，而在Release 构建时将其生成为结构。\n\nUnity 从2020.1版本开始支持代码优化选项（位于右下角）。\n\n\n\n在开发构建中，您可以通过将 C# 编译器优化设置为 release 模式来移除 AsyncStateMachine 的堆内存分配。此优化选项也可以通过`Compilation.CompilationPipeline-codeOptimization`和`Compilation.CodeOptimization`来设置。\n\nUniTaskSynchronizationContext\n---\nUnity 的默认 SynchronizationContext(`UnitySynchronizationContext`) 在性能方面表现不佳。UniTask 绕过`SynchronizationContext`(和`ExecutionContext`) 因此 UniTask 不使用它，但如果存在`async Task`，则仍然使用它。`UniTaskSynchronizationContext`是`UnitySynchronizationContext`性能更好的替代品。\n\n```csharp\npublic class SyncContextInjecter\n{\n [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]\n public static void Inject()\n {\n SynchronizationContext.SetSynchronizationContext(new UniTaskSynchronizationContext());\n }\n}\n```\n\n这是一个可选的选择，并不总是推荐；`UniTaskSynchronizationContext`性能不如`async UniTask`，并且不是完整的 UniTask 替代品。它也不保证与`UnitySynchronizationContext`完全兼容\n\nAPI 文档\n---\nUniTask 的 API 文档托管在[cysharp.github.io/UniTask](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.html)，使用[DocFX](https://dotnet.github.io/docfx/)和[Cysharp/DocfXTemplate](https://github.com/Cysharp/DocfxTemplate)生成。\n\n例如，UniTask 的工厂方法可以在[UniTask#methods](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.UniTask.html#methods-1)中查阅。UniTaskAsyncEnumerable 的工厂方法和扩展方法可以在[UniTaskAsyncEnumerable#methods](https://cysharp.github.io/UniTask/api/Cysharp.Threading.Tasks.Linq.UniTaskAsyncEnumerable.html#methods-1)中查阅。\n\nUPM 包\n---\n### 通过 git URL 安装\n\n需要支持 git 包路径查询参数的 Unity 版本（Unity >= 2019.3.4f1，Unity >= 2020.1a21）。您可以在包管理器中添加`https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask`\n\n\n\n\n\n或在`Packages/manifest.json`中添加`\"com.cysharp.unitask\": \"https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask\"` 。\n\nUniTask 使用`*.*.*`发布标签来指定版本，因此如果您要设置指定版本，您可以在后面添加像`#2.1.0`这样的版本标签。例如`https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask#2.1.0` 。\n\n\n关于 .NET Core\n---\n对于 .NET Core，请使用 NuGet。\n\n> PM> Install-Package [UniTask](https://www.nuget.org/packages/UniTask)\n\n.NET Core 版本的 UniTask 是 Unity 版本的 UniTask 的子集，它移除了依赖 PlayerLoop 的方法。\n\n相比于原生 Task 和 ValueTask，它能以更高的性能运行，但在使用时应注意忽略 ExecutionContext 和 SynchronizationContext。因为它忽略了 ExecutionContext，`AsyncLocal`也不起作用。\n\n如果您在内部使用 UniTask，但将 ValueTask 作为外部 API 提供，您可以编写如下代码（受[PooledAwait](https://github.com/mgravell/PooledAwait)启发）。\n\n```csharp\npublic class ZeroAllocAsyncAwaitInDotNetCore\n{\n public ValueTask DoAsync(int x, int y)\n {\n return Core(this, x, y);\n\n static async UniTask Core(ZeroAllocAsyncAwaitInDotNetCore self, int x, int y)\n {\n // do anything...\n await Task.Delay(TimeSpan.FromSeconds(x + y));\n await UniTask.Yield();\n\n return 10;\n }\n }\n}\n\n// UniTask 不会返回到原生 SynchronizationContext，但可以使用 `ReturnToCurrentSynchronizationContext`来让他返回\npublic ValueTask TestAsync()\n{\n await using (UniTask.ReturnToCurrentSynchronizationContext())\n {\n await UniTask.SwitchToThreadPool();\n // do anything..\n }\n}\n```\n\n.NET Core 版本的 UniTask 是为了让用户在与 Unity 共享代码时（例如使用[CysharpOnion](https://github.com/Cysharp/MagicOnion/)），能够将 UniTask 用作接口。.NET Core 版本的 UniTask 使得代码共享更加顺畅。\n\n[Cysharp/ValueTaskSupplement](https://github.com/Cysharp/ValueTaskSupplement)提供了一些实用方法，如 WhenAll，这些方法等效于 UniTask。\n\n许可证\n---\n此库采用MIT许可证\n"
},
{
"path": "UniTask.NetCore.sln",
"content": "\nMicrosoft Visual Studio Solution File, Format Version 12.00\n# Visual Studio Version 17\nVisualStudioVersion = 17.0.31606.5\nMinimumVisualStudioVersion = 10.0.40219.1\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"UniTask.NetCoreTests\", \"src\\UniTask.NetCoreTests\\UniTask.NetCoreTests.csproj\", \"{B3E311A4-70D8-4131-9965-C073A99D201A}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"UniTask.NetCore\", \"src\\UniTask.NetCore\\UniTask.NetCore.csproj\", \"{16EE20D0-7FB1-483A-8467-A5EEDBF1F5BF}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"UniTask.NetCoreSandbox\", \"src\\UniTask.NetCoreSandbox\\UniTask.NetCoreSandbox.csproj\", \"{3915E72E-33E0-4A14-A6D8-872702200E58}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"UniTask.Analyzer\", \"src\\UniTask.Analyzer\\UniTask.Analyzer.csproj\", \"{0AC6F052-A255-4EE3-9E05-1C02D49AB1C2}\"\nEndProject\nGlobal\n\tGlobalSection(SolutionConfigurationPlatforms) = preSolution\n\t\tDebug|Any CPU = Debug|Any CPU\n\t\tRelease|Any CPU = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(ProjectConfigurationPlatforms) = postSolution\n\t\t{B3E311A4-70D8-4131-9965-C073A99D201A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{B3E311A4-70D8-4131-9965-C073A99D201A}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{B3E311A4-70D8-4131-9965-C073A99D201A}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{B3E311A4-70D8-4131-9965-C073A99D201A}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{16EE20D0-7FB1-483A-8467-A5EEDBF1F5BF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{16EE20D0-7FB1-483A-8467-A5EEDBF1F5BF}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{16EE20D0-7FB1-483A-8467-A5EEDBF1F5BF}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{16EE20D0-7FB1-483A-8467-A5EEDBF1F5BF}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{3915E72E-33E0-4A14-A6D8-872702200E58}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{3915E72E-33E0-4A14-A6D8-872702200E58}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{3915E72E-33E0-4A14-A6D8-872702200E58}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{3915E72E-33E0-4A14-A6D8-872702200E58}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{0AC6F052-A255-4EE3-9E05-1C02D49AB1C2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{0AC6F052-A255-4EE3-9E05-1C02D49AB1C2}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{0AC6F052-A255-4EE3-9E05-1C02D49AB1C2}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{0AC6F052-A255-4EE3-9E05-1C02D49AB1C2}.Release|Any CPU.Build.0 = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(SolutionProperties) = preSolution\n\t\tHideSolutionNode = FALSE\n\tEndGlobalSection\n\tGlobalSection(ExtensibilityGlobals) = postSolution\n\t\tSolutionGuid = {90F78FCC-7CD4-4E88-A3DB-873F481F8C8B}\n\tEndGlobalSection\nEndGlobal\n"
},
{
"path": "docs/.gitignore",
"content": "###############\n# folder #\n###############\n/**/DROP/\n/**/TEMP/\n/**/packages/\n/**/bin/\n/**/obj/\n_site\n_DocfxTemplate"
},
{
"path": "docs/api/.gitignore",
"content": "###############\n# temp file #\n###############\n*.yml\n.manifest\n"
},
{
"path": "docs/docfx.json",
"content": "{\n \"metadata\": [\n {\n \"src\": [\n {\n \"files\": [\n \"UniTask/Library/ScriptAssemblies/UniTask*.dll\"\n ],\n \"exclude\": [\n \"UniTask/Library/ScriptAssemblies/UniTask.Tests.dll\",\n \"UniTask/Library/ScriptAssemblies/UniTask.Tests.Editor.dll\"\n ],\n \"src\": \"../src\"\n }\n ],\n \"dest\": \"api\",\n \"disableGitFeatures\": false,\n \"disableDefaultFilter\": false\n }\n ],\n \"build\": {\n \"globalMetadata\": {\n \"_disableContribution\": true,\n \"_appTitle\": \"UniTask\"\n },\n \"content\": [\n {\n \"files\": [\n \"api/**.yml\",\n \"api/index.md\"\n ]\n },\n {\n \"files\": [\n \"articles/**.md\",\n \"articles/**/toc.yml\",\n \"toc.yml\",\n \"*.md\"\n ]\n }\n ],\n \"resource\": [\n {\n \"files\": [\n \"images/**\"\n ]\n }\n ],\n \"overwrite\": [\n {\n \"files\": [\n \"apidoc/**.md\"\n ],\n \"exclude\": [\n \"obj/**\",\n \"_site/**\"\n ]\n }\n ],\n \"dest\": \"_site\",\n \"globalMetadataFiles\": [],\n \"fileMetadataFiles\": [],\n \"template\": [\n \"_DocfxTemplate/templates/default-v2.5.2\",\n \"_DocfxTemplate/templates/cysharp\"\n ],\n \"postProcessors\": [],\n \"markdownEngineName\": \"markdig\",\n \"noLangKeyword\": false,\n \"keepFileLink\": false,\n \"cleanupCacheHistory\": false\n }\n}\n"
},
{
"path": "docs/index.md",
"content": "---\ntitle: Home\n---\n# UniTask\n\nProvides an efficient async/await integration to Unity.\n\nhttps://github.com/Cysharp/UniTask\n"
},
{
"path": "docs/toc.yml",
"content": "- name: API Documentation\n href: api/\n homepage: api/Cysharp.Threading.Tasks.html\n\n- name: Repository\n href: https://github.com/Cysharp/UniTask\n homepage: https://github.com/Cysharp/UniTask\n\n- name: Releases\n href: https://github.com/Cysharp/UniTask/releases\n homepage: https://github.com/Cysharp/UniTask/releases"
},
{
"path": "src/UniTask/Assets/Editor/EditorRunnerChecker.cs",
"content": "#if UNITY_EDITOR\n\nusing Cysharp.Threading.Tasks;\nusing System;\nusing System.IO;\nusing System.Linq;\nusing UnityEditor;\nusing UnityEngine;\nusing UnityEngine.Networking;\n\npublic static class EditorRunnerChecker\n{\n [MenuItem(\"Tools/UniTaskEditorRunnerChecker\")]\n public static void RunUniTaskAsync()\n {\n RunCore().Forget();\n }\n\n static async UniTaskVoid RunCore()\n {\n Debug.Log(\"Start\");\n\n //var r = await UnityWebRequest.Get(\"https://bing.com/\").SendWebRequest().ToUniTask();\n //Debug.Log(r.downloadHandler.text.Substring(0, 100));\n //await UniTask.Yield();\n\n await UniTask.DelayFrame(30);\n\n Debug.Log(\"End\");\n }\n}\n\n#endif"
},
{
"path": "src/UniTask/Assets/Editor/EditorRunnerChecker.cs.meta",
"content": "fileFormatVersion: 2\nguid: e51b78c06cb410f42b36e0af9de3b065\nMonoImporter:\n externalObjects: {}\n serializedVersion: 2\n defaultReferences: []\n executionOrder: 0\n icon: {instanceID: 0}\n userData: \n assetBundleName: \n assetBundleVariant: \n"
},
{
"path": "src/UniTask/Assets/Editor/PackageExporter.cs",
"content": "#if UNITY_EDITOR\n\nusing System;\nusing System.IO;\nusing System.Linq;\nusing UnityEditor;\nusing UnityEngine;\n\npublic static class PackageExporter\n{\n [MenuItem(\"Tools/Export Unitypackage\")]\n public static void Export()\n {\n var root = \"Plugins/UniTask\";\n var version = GetVersion(root);\n\n var fileName = string.IsNullOrEmpty(version) ? \"UniTask.unitypackage\" : $\"UniTask.{version}.unitypackage\";\n var exportPath = \"./\" + fileName;\n\n var path = Path.Combine(Application.dataPath, root);\n var assets = Directory.EnumerateFiles(path, \"*\", SearchOption.AllDirectories)\n .Where(x => Path.GetExtension(x) == \".cs\" || Path.GetExtension(x) == \".asmdef\" || Path.GetExtension(x) == \".json\" || Path.GetExtension(x) == \".meta\")\n .Select(x => \"Assets\" + x.Replace(Application.dataPath, \"\").Replace(@\"\\\", \"/\"))\n .ToArray();\n\n UnityEngine.Debug.Log(\"Export below files\" + Environment.NewLine + string.Join(Environment.NewLine, assets));\n\n AssetDatabase.ExportPackage(\n assets,\n exportPath,\n ExportPackageOptions.Default);\n\n UnityEngine.Debug.Log(\"Export complete: \" + Path.GetFullPath(exportPath));\n }\n\n static string GetVersion(string root)\n {\n var version = Environment.GetEnvironmentVariable(\"UNITY_PACKAGE_VERSION\");\n var versionJson = Path.Combine(Application.dataPath, root, \"package.json\");\n\n if (File.Exists(versionJson))\n {\n var v = JsonUtility.FromJson(File.ReadAllText(versionJson));\n\n if (!string.IsNullOrEmpty(version))\n {\n if (v.version != version)\n {\n var msg = $\"package.json and env version are mismatched. UNITY_PACKAGE_VERSION:{version}, package.json:{v.version}\";\n\n if (Application.isBatchMode)\n {\n Console.WriteLine(msg);\n Application.Quit(1);\n }\n\n throw new Exception(\"package.json and env version are mismatched.\");\n }\n }\n\n version = v.version;\n }\n\n return version;\n }\n\n public class Version\n {\n public string version;\n }\n}\n\n#endif"
},
{
"path": "src/UniTask/Assets/Editor/PackageExporter.cs.meta",
"content": "fileFormatVersion: 2\nguid: af97405af79afbb4e9f7f49f30088474\nMonoImporter:\n externalObjects: {}\n serializedVersion: 2\n defaultReferences: []\n executionOrder: 0\n icon: {instanceID: 0}\n userData: \n assetBundleName: \n assetBundleVariant: \n"
},
{
"path": "src/UniTask/Assets/Editor.meta",
"content": "fileFormatVersion: 2\nguid: 99c8676e874bf0343b421d3527868f16\nfolderAsset: yes\nDefaultImporter:\n externalObjects: {}\n userData: \n assetBundleName: \n assetBundleVariant: \n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor/SplitterGUILayout.cs",
"content": "#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member\n\nusing System;\nusing System.Linq;\nusing System.Reflection;\nusing UnityEditor;\nusing UnityEngine;\n\nnamespace Cysharp.Threading.Tasks.Editor\n{\n // reflection call of UnityEditor.SplitterGUILayout\n internal static class SplitterGUILayout\n {\n static BindingFlags flags = BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static;\n\n static Lazy splitterStateType = new Lazy(() =>\n {\n var type = typeof(EditorWindow).Assembly.GetTypes().First(x => x.FullName == \"UnityEditor.SplitterState\");\n return type;\n });\n\n static Lazy splitterStateCtor = new Lazy(() =>\n {\n var type = splitterStateType.Value;\n return type.GetConstructor(flags, null, new Type[] { typeof(float[]), typeof(int[]), typeof(int[]) }, null);\n });\n\n static Lazy splitterGUILayoutType = new Lazy(() =>\n {\n var type = typeof(EditorWindow).Assembly.GetTypes().First(x => x.FullName == \"UnityEditor.SplitterGUILayout\");\n return type;\n });\n\n static Lazy beginVerticalSplit = new Lazy(() =>\n {\n var type = splitterGUILayoutType.Value;\n return type.GetMethod(\"BeginVerticalSplit\", flags, null, new Type[] { splitterStateType.Value, typeof(GUILayoutOption[]) }, null);\n });\n\n static Lazy endVerticalSplit = new Lazy(() =>\n {\n var type = splitterGUILayoutType.Value;\n return type.GetMethod(\"EndVerticalSplit\", flags, null, Type.EmptyTypes, null);\n });\n\n public static object CreateSplitterState(float[] relativeSizes, int[] minSizes, int[] maxSizes)\n {\n return splitterStateCtor.Value.Invoke(new object[] { relativeSizes, minSizes, maxSizes });\n }\n\n public static void BeginVerticalSplit(object splitterState, params GUILayoutOption[] options)\n {\n beginVerticalSplit.Value.Invoke(null, new object[] { splitterState, options });\n }\n\n public static void EndVerticalSplit()\n {\n endVerticalSplit.Value.Invoke(null, Type.EmptyTypes);\n }\n }\n}\n\n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor/SplitterGUILayout.cs.meta",
"content": "fileFormatVersion: 2\nguid: 40ef2e46f900131419e869398a8d3c9d\nMonoImporter:\n externalObjects: {}\n serializedVersion: 2\n defaultReferences: []\n executionOrder: 0\n icon: {instanceID: 0}\n userData: \n assetBundleName: \n assetBundleVariant: \n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor/UniTask.Editor.asmdef",
"content": "{\n \"name\": \"UniTask.Editor\",\n \"references\": [\n \"UniTask\"\n ],\n \"includePlatforms\": [\n \"Editor\"\n ],\n \"excludePlatforms\": [],\n \"allowUnsafeCode\": false,\n \"overrideReferences\": false,\n \"precompiledReferences\": [],\n \"autoReferenced\": false,\n \"defineConstraints\": [],\n \"versionDefines\": [],\n \"noEngineReferences\": false\n}"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor/UniTask.Editor.asmdef.meta",
"content": "fileFormatVersion: 2\nguid: 4129704b5a1a13841ba16f230bf24a57\nAssemblyDefinitionImporter:\n externalObjects: {}\n userData: \n assetBundleName: \n assetBundleVariant: \n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor/UniTaskTrackerTreeView.cs",
"content": "#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member\n\nusing UnityEngine;\nusing UnityEditor;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Reflection;\nusing System;\nusing UnityEditor.IMGUI.Controls;\nusing Cysharp.Threading.Tasks.Internal;\nusing System.Text;\nusing System.Text.RegularExpressions;\n\nnamespace Cysharp.Threading.Tasks.Editor\n{\n public class UniTaskTrackerViewItem : TreeViewItem\n {\n static Regex removeHref = new Regex(\"(.+)\", RegexOptions.Compiled);\n\n public string TaskType { get; set; }\n public string Elapsed { get; set; }\n public string Status { get; set; }\n\n string position;\n public string Position\n {\n get { return position; }\n set\n {\n position = value;\n PositionFirstLine = GetFirstLine(position);\n }\n }\n\n public string PositionFirstLine { get; private set; }\n\n static string GetFirstLine(string str)\n {\n var sb = new StringBuilder();\n for (int i = 0; i < str.Length; i++)\n {\n if (str[i] == '\\r' || str[i] == '\\n')\n {\n break;\n }\n sb.Append(str[i]);\n }\n\n return removeHref.Replace(sb.ToString(), \"$1\");\n }\n\n public UniTaskTrackerViewItem(int id) : base(id)\n {\n\n }\n }\n\n public class UniTaskTrackerTreeView : TreeView\n {\n const string sortedColumnIndexStateKey = \"UniTaskTrackerTreeView_sortedColumnIndex\";\n\n public IReadOnlyList CurrentBindingItems;\n\n public UniTaskTrackerTreeView()\n : this(new TreeViewState(), new MultiColumnHeader(new MultiColumnHeaderState(new[]\n {\n new MultiColumnHeaderState.Column() { headerContent = new GUIContent(\"TaskType\"), width = 20},\n new MultiColumnHeaderState.Column() { headerContent = new GUIContent(\"Elapsed\"), width = 10},\n new MultiColumnHeaderState.Column() { headerContent = new GUIContent(\"Status\"), width = 10},\n new MultiColumnHeaderState.Column() { headerContent = new GUIContent(\"Position\")},\n })))\n {\n }\n\n UniTaskTrackerTreeView(TreeViewState state, MultiColumnHeader header)\n : base(state, header)\n {\n rowHeight = 20;\n showAlternatingRowBackgrounds = true;\n showBorder = true;\n header.sortingChanged += Header_sortingChanged;\n\n header.ResizeToFit();\n Reload();\n\n header.sortedColumnIndex = SessionState.GetInt(sortedColumnIndexStateKey, 1);\n }\n\n public void ReloadAndSort()\n {\n var currentSelected = this.state.selectedIDs;\n Reload();\n Header_sortingChanged(this.multiColumnHeader);\n this.state.selectedIDs = currentSelected;\n }\n\n private void Header_sortingChanged(MultiColumnHeader multiColumnHeader)\n {\n SessionState.SetInt(sortedColumnIndexStateKey, multiColumnHeader.sortedColumnIndex);\n var index = multiColumnHeader.sortedColumnIndex;\n var ascending = multiColumnHeader.IsSortedAscending(multiColumnHeader.sortedColumnIndex);\n\n var items = rootItem.children.Cast();\n\n IOrderedEnumerable orderedEnumerable;\n switch (index)\n {\n case 0:\n orderedEnumerable = ascending ? items.OrderBy(item => item.TaskType) : items.OrderByDescending(item => item.TaskType);\n break;\n case 1:\n orderedEnumerable = ascending ? items.OrderBy(item => double.Parse(item.Elapsed)) : items.OrderByDescending(item => double.Parse(item.Elapsed));\n break;\n case 2:\n orderedEnumerable = ascending ? items.OrderBy(item => item.Status) : items.OrderByDescending(item => item.Elapsed);\n break;\n case 3:\n orderedEnumerable = ascending ? items.OrderBy(item => item.Position) : items.OrderByDescending(item => item.PositionFirstLine);\n break;\n default:\n throw new ArgumentOutOfRangeException(nameof(index), index, null);\n }\n\n CurrentBindingItems = rootItem.children = orderedEnumerable.Cast().ToList();\n BuildRows(rootItem);\n }\n\n protected override TreeViewItem BuildRoot()\n {\n var root = new TreeViewItem { depth = -1 };\n\n var children = new List();\n\n TaskTracker.ForEachActiveTask((trackingId, awaiterType, status, created, stackTrace) =>\n {\n children.Add(new UniTaskTrackerViewItem(trackingId) { TaskType = awaiterType, Status = status.ToString(), Elapsed = (DateTime.UtcNow - created).TotalSeconds.ToString(\"00.00\"), Position = stackTrace });\n });\n\n CurrentBindingItems = children;\n root.children = CurrentBindingItems as List;\n return root;\n }\n\n protected override bool CanMultiSelect(TreeViewItem item)\n {\n return false;\n }\n\n protected override void RowGUI(RowGUIArgs args)\n {\n var item = args.item as UniTaskTrackerViewItem;\n\n for (var visibleColumnIndex = 0; visibleColumnIndex < args.GetNumVisibleColumns(); visibleColumnIndex++)\n {\n var rect = args.GetCellRect(visibleColumnIndex);\n var columnIndex = args.GetColumn(visibleColumnIndex);\n\n var labelStyle = args.selected ? EditorStyles.whiteLabel : EditorStyles.label;\n labelStyle.alignment = TextAnchor.MiddleLeft;\n switch (columnIndex)\n {\n case 0:\n EditorGUI.LabelField(rect, item.TaskType, labelStyle);\n break;\n case 1:\n EditorGUI.LabelField(rect, item.Elapsed, labelStyle);\n break;\n case 2:\n EditorGUI.LabelField(rect, item.Status, labelStyle);\n break;\n case 3:\n EditorGUI.LabelField(rect, item.PositionFirstLine, labelStyle);\n break;\n default:\n throw new ArgumentOutOfRangeException(nameof(columnIndex), columnIndex, null);\n }\n }\n }\n }\n\n}\n\n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor/UniTaskTrackerTreeView.cs.meta",
"content": "fileFormatVersion: 2\nguid: 52e2d973a2156674e8c1c9433ed031f7\nMonoImporter:\n externalObjects: {}\n serializedVersion: 2\n defaultReferences: []\n executionOrder: 0\n icon: {instanceID: 0}\n userData: \n assetBundleName: \n assetBundleVariant: \n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor/UniTaskTrackerWindow.cs",
"content": "#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member\n\nusing UnityEngine;\nusing UnityEditor;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Reflection;\nusing System;\nusing UnityEditor.IMGUI.Controls;\nusing Cysharp.Threading.Tasks.Internal;\n\nnamespace Cysharp.Threading.Tasks.Editor\n{\n public class UniTaskTrackerWindow : EditorWindow\n {\n static int interval;\n\n static UniTaskTrackerWindow window;\n\n [MenuItem(\"Window/UniTask Tracker\")]\n public static void OpenWindow()\n {\n if (window != null)\n {\n window.Close();\n }\n\n // will called OnEnable(singleton instance will be set).\n GetWindow(\"UniTask Tracker\").Show();\n }\n\n static readonly GUILayoutOption[] EmptyLayoutOption = new GUILayoutOption[0];\n\n UniTaskTrackerTreeView treeView;\n object splitterState;\n\n void OnEnable()\n {\n window = this; // set singleton.\n splitterState = SplitterGUILayout.CreateSplitterState(new float[] { 75f, 25f }, new int[] { 32, 32 }, null);\n treeView = new UniTaskTrackerTreeView();\n TaskTracker.EditorEnableState.EnableAutoReload = EditorPrefs.GetBool(TaskTracker.EnableAutoReloadKey, false);\n TaskTracker.EditorEnableState.EnableTracking = EditorPrefs.GetBool(TaskTracker.EnableTrackingKey, false);\n TaskTracker.EditorEnableState.EnableStackTrace = EditorPrefs.GetBool(TaskTracker.EnableStackTraceKey, false);\n }\n\n void OnGUI()\n {\n // Head\n RenderHeadPanel();\n\n // Splittable\n SplitterGUILayout.BeginVerticalSplit(this.splitterState, EmptyLayoutOption);\n {\n // Column Tabble\n RenderTable();\n\n // StackTrace details\n RenderDetailsPanel();\n }\n SplitterGUILayout.EndVerticalSplit();\n }\n\n #region HeadPanel\n\n public static bool EnableAutoReload => TaskTracker.EditorEnableState.EnableAutoReload;\n public static bool EnableTracking => TaskTracker.EditorEnableState.EnableTracking;\n public static bool EnableStackTrace => TaskTracker.EditorEnableState.EnableStackTrace;\n static readonly GUIContent EnableAutoReloadHeadContent = EditorGUIUtility.TrTextContent(\"Enable AutoReload\", \"Reload automatically.\", (Texture)null);\n static readonly GUIContent ReloadHeadContent = EditorGUIUtility.TrTextContent(\"Reload\", \"Reload View.\", (Texture)null);\n static readonly GUIContent GCHeadContent = EditorGUIUtility.TrTextContent(\"GC.Collect\", \"Invoke GC.Collect.\", (Texture)null);\n static readonly GUIContent EnableTrackingHeadContent = EditorGUIUtility.TrTextContent(\"Enable Tracking\", \"Start to track async/await UniTask. Performance impact: low\", (Texture)null);\n static readonly GUIContent EnableStackTraceHeadContent = EditorGUIUtility.TrTextContent(\"Enable StackTrace\", \"Capture StackTrace when task is started. Performance impact: high\", (Texture)null);\n\n // [Enable Tracking] | [Enable StackTrace]\n void RenderHeadPanel()\n {\n EditorGUILayout.BeginVertical(EmptyLayoutOption);\n EditorGUILayout.BeginHorizontal(EditorStyles.toolbar, EmptyLayoutOption);\n\n if (GUILayout.Toggle(EnableAutoReload, EnableAutoReloadHeadContent, EditorStyles.toolbarButton, EmptyLayoutOption) != EnableAutoReload)\n {\n TaskTracker.EditorEnableState.EnableAutoReload = !EnableAutoReload;\n }\n\n if (GUILayout.Toggle(EnableTracking, EnableTrackingHeadContent, EditorStyles.toolbarButton, EmptyLayoutOption) != EnableTracking)\n {\n TaskTracker.EditorEnableState.EnableTracking = !EnableTracking;\n }\n\n if (GUILayout.Toggle(EnableStackTrace, EnableStackTraceHeadContent, EditorStyles.toolbarButton, EmptyLayoutOption) != EnableStackTrace)\n {\n TaskTracker.EditorEnableState.EnableStackTrace = !EnableStackTrace;\n }\n\n GUILayout.FlexibleSpace();\n\n if (GUILayout.Button(ReloadHeadContent, EditorStyles.toolbarButton, EmptyLayoutOption))\n {\n TaskTracker.CheckAndResetDirty();\n treeView.ReloadAndSort();\n Repaint();\n }\n\n if (GUILayout.Button(GCHeadContent, EditorStyles.toolbarButton, EmptyLayoutOption))\n {\n GC.Collect(0);\n }\n\n EditorGUILayout.EndHorizontal();\n EditorGUILayout.EndVertical();\n }\n\n #endregion\n\n #region TableColumn\n\n Vector2 tableScroll;\n GUIStyle tableListStyle;\n\n void RenderTable()\n {\n if (tableListStyle == null)\n {\n tableListStyle = new GUIStyle(\"CN Box\");\n tableListStyle.margin.top = 0;\n tableListStyle.padding.left = 3;\n }\n\n EditorGUILayout.BeginVertical(tableListStyle, EmptyLayoutOption);\n\n this.tableScroll = EditorGUILayout.BeginScrollView(this.tableScroll, new GUILayoutOption[]\n {\n GUILayout.ExpandWidth(true),\n GUILayout.MaxWidth(2000f)\n });\n var controlRect = EditorGUILayout.GetControlRect(new GUILayoutOption[]\n {\n GUILayout.ExpandHeight(true),\n GUILayout.ExpandWidth(true)\n });\n\n\n treeView?.OnGUI(controlRect);\n\n EditorGUILayout.EndScrollView();\n EditorGUILayout.EndVertical();\n }\n\n private void Update()\n {\n if (EnableAutoReload)\n {\n if (interval++ % 120 == 0)\n {\n if (TaskTracker.CheckAndResetDirty())\n {\n treeView.ReloadAndSort();\n Repaint();\n }\n }\n }\n }\n\n #endregion\n\n #region Details\n\n static GUIStyle detailsStyle;\n Vector2 detailsScroll;\n\n void RenderDetailsPanel()\n {\n if (detailsStyle == null)\n {\n detailsStyle = new GUIStyle(\"CN Message\");\n detailsStyle.wordWrap = false;\n detailsStyle.stretchHeight = true;\n detailsStyle.margin.right = 15;\n }\n\n string message = \"\";\n var selected = treeView.state.selectedIDs;\n if (selected.Count > 0)\n {\n var first = selected[0];\n var item = treeView.CurrentBindingItems.FirstOrDefault(x => x.id == first) as UniTaskTrackerViewItem;\n if (item != null)\n {\n message = item.Position;\n }\n }\n\n detailsScroll = EditorGUILayout.BeginScrollView(this.detailsScroll, EmptyLayoutOption);\n var vector = detailsStyle.CalcSize(new GUIContent(message));\n EditorGUILayout.SelectableLabel(message, detailsStyle, new GUILayoutOption[]\n {\n GUILayout.ExpandHeight(true),\n GUILayout.ExpandWidth(true),\n GUILayout.MinWidth(vector.x),\n GUILayout.MinHeight(vector.y)\n });\n EditorGUILayout.EndScrollView();\n }\n\n #endregion\n }\n}\n\n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor/UniTaskTrackerWindow.cs.meta",
"content": "fileFormatVersion: 2\nguid: 5bee3e3860e37484aa3b861bf76d129f\nMonoImporter:\n externalObjects: {}\n serializedVersion: 2\n defaultReferences: []\n executionOrder: 0\n icon: {instanceID: 0}\n userData: \n assetBundleName: \n assetBundleVariant: \n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Editor.meta",
"content": "fileFormatVersion: 2\nguid: 275b87293edc6634f9d72387851dbbdf\nfolderAsset: yes\nDefaultImporter:\n externalObjects: {}\n userData: \n assetBundleName: \n assetBundleVariant: \n"
},
{
"path": "src/UniTask/Assets/Plugins/UniTask/Runtime/AsyncLazy.cs",
"content": "#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member\n\nusing System;\nusing System.Threading;\n\nnamespace Cysharp.Threading.Tasks\n{\n public class AsyncLazy\n {\n static Action