Coroutines #2982

mtszkarbowiak · 2024-10-11T16:27:36Z

Observations:

Enumerator methods may not be used, because they can't yield to C++.
C++ 20 coroutines may not be used, because they are C++ 20 after all.

This quickly suggest homebrew Flax-specific solution. Unfortunately, Flax API limits require using chain of methods to set up stages of the coroutine. Thus, they are not as sexy as Unity enumerator method-based coroutines, but share the same API in both managed and native scripts. CRs are welcome!

Oh please, and since now on, please stop suggesting people to use TPL. Using other threads just for what are coroutines is ridiculous. (Implementing our own single-threaded scheduler for async tasks does not count.)

https://discord.com/channels/437989205315158016/509056735844106251/1295414677672693803

Source/Engine/Level/Level.cpp

Source/Engine/Level/Scene/SceneTicking.cpp

Source/Engine/Scripting/Coroutines/CoroutineSuspendPoint.h

mtszkarbowiak · 2024-10-18T20:38:39Z

While working on the manual, I realized the name CoroutineSequence is better than CoroutineBuilder. I want the users to have clear understanding of linear nature of this solution. If the change didn't break anything, I'll mark the PR as ready.

FlaxEngine/FlaxDocs#165

mafiesto4

Sorry for late review. I've got some feedback. I can do some changes while merging.

mafiesto4 · 2025-03-02T20:25:09Z

Source/Engine/Level/Scene/Scene.h

@@ -9,6 +9,7 @@
 #include "SceneRendering.h"
 #include "SceneTicking.h"
 #include "SceneNavigation.h"
+#include "Engine/Scripting/Coroutines/CoroutineExecutor.h"


Use forward decl instead includes (compile time issue).

mafiesto4 · 2025-03-02T20:25:45Z

Source/Engine/Scripting/Script.h

 #include "ScriptingObject.h"
+#include "ScriptingObjectReference.h"
+#include "Coroutines/CoroutineHandle.h"
+#include "Coroutines/CoroutineSequence.h"


Use forward decl instead includes (compile time issue).

mafiesto4 · 2025-03-02T20:27:44Z

Source/Engine/Scripting/Script.h

+    /// This method uses shared per-scene executor. The order of execution is not guaranteed.
+    /// </remarks>
+    API_FUNCTION()
+    ScriptingObjectReference<CoroutineHandle> ExecuteCoroutineOnce(ScriptingObjectReference<CoroutineSequence> sequence) const;


This can use CoroutineSequence* raw pointer. Caller owns or knows the object lifetime and this actually moves the ownership into the executor.

mafiesto4 · 2025-03-02T20:42:37Z

Source/Engine/Scripting/Coroutines/CoroutineExecutor.h

+    /// Adds a coroutine to the executor to be executed multiple times.
+    /// </summary>
+    API_FUNCTION()
+    ScriptingObjectReference<CoroutineHandle> ExecuteRepeats(


Rename to ExecuteRepeated to match ExecuteLooped

mafiesto4 · 2025-03-02T20:43:55Z

Source/Engine/Scripting/Coroutines/CoroutineExecutor.h

+    /// <summary>
+    /// Returns the number of coroutines currently being executed.
+    /// </summary>
+    API_FUNCTION()


API_PROPERTY

mafiesto4 · 2025-03-02T20:45:03Z

Source/Engine/Scripting/Coroutines/CoroutineHandle.h

+/// <summary>
+/// Reference to a coroutine that can be used to control its execution.
+/// </summary>
+API_CLASS(Sealed) class FLAXENGINE_API CoroutineHandle final : public ScriptingObject


I think this should be a struct for more lightweight and prevent dynamic memory allocations.

mafiesto4 · 2025-03-02T21:01:39Z

Source/Engine/Scripting/Coroutines/CoroutineSequence.h

+/// Stores code to be executed once previous step is completed.
+/// </summary>
+/// <remarks>
+/// This class is used due to limitations of Flax API.


If function takes Function<void()> as parameter then it will be passed as C# delegate to be invoked from C++. So this CoroutineRunnable is not needed.

Last time I tried it didn't work. Gonna try it again.

mafiesto4 · 2025-03-02T21:26:34Z

Source/Engine/Scripting/Coroutines/CoroutineSequence.h

+    private:
+        void Clear();
+        void EmplaceCopy(const Step& other);
+        void EmplaceMove(Step&& other) noexcept;


I think memory management for such structure is overenginnering. It can be data-only (maybe with frames delta, seconds delay and suspension point as union). Only CoroutineSequence and CoroutineExecutor use it.

mafiesto4 · 2025-03-02T21:32:59Z

Source/Engine/Scripting/Coroutines/CoroutineSequence.h

+    ScriptingObjectReference<CoroutineSequence> ThenRunFunc(const Function<void()>& runnable);
+
+    /// <summary> QOL wrapper for waiting until predicate in native scripts. </summary>
+    ScriptingObjectReference<CoroutineSequence> ThenWaitUntilFunc(const Function<void(bool&)>& predicate);


It can be Function<bool()> and API_FUNCTION so C# can pass Action directly.

mafiesto4 · 2025-03-02T21:39:55Z

Source/Engine/Scripting/Coroutines/CoroutineExecutor.cpp

+    execution.ContinueCoroutine(CoroutineSuspendPoint::Update, Delta{ 0.0f, 0 });
+    _executions.Add(MoveTemp(execution));
+
+    ScriptingObjectReference<CoroutineHandle> handle = NewObject<CoroutineHandle>();


CoroutineHandle as struct would not leak memory and be faster to use.

As I remember I thought API structs must not have ScriptableObjectReference. If it is supported, then I can change it.

Previously `ExecuteRepeated`

mtszkarbowiak added 8 commits October 9, 2024 20:26

Coroutine suspension points

4a912ca

Coroutines API draft

a710988

Coroutines draft cd.

2ee2d22

Coroutine step constructors

fded794

Coroutine step builders

245f705

Coroutine builder accessors

bbc35d8

Coroutines example 2

a30218a

Coroutines execution

edc2a53

mafiesto4 added enhancement New feature or request core scripting labels Oct 11, 2024

mtszkarbowiak added 9 commits October 12, 2024 01:38

Coroutine docs

6a5a397

Coroutine repreats

5ab17a0

Coroutines repeated execution sanity check

d00bc6d

Coroutine suspension accumulation

0294f33

Coroutine suspension point enum refactor

124cc0a

Coroutine execution point filtering

325dbb5

Coroutine wait for suspension point

9a9d573

Coroutine time accumulators injection

1ccfb15

Coroutine time accumulation test

dcad850

mtszkarbowiak force-pushed the feat/coroutines-v2 branch from c40ad58 to dcad850 Compare October 13, 2024 01:06

mtszkarbowiak added 9 commits October 14, 2024 02:10

Coroutine waiting until with tests

b0475b7

Coroutine handle

099d85b

Coroutine execution handle tests

26434b8

Coroutine handle source executor

c593b49

Coroutine handle ID field name conflict fix

242b5ed

Merge branch 'FlaxEngine:master' into feat/coroutines-v2

3b8842c

Coroutines docs

ae03fe2

Coroutines builder native captures

735edfd

Coroutines tests rewritten to C++

6695b29

https://discord.com/channels/437989205315158016/509056735844106251/1295414677672693803

mtszkarbowiak force-pushed the feat/coroutines-v2 branch from ba67544 to fce485a Compare October 16, 2024 17:13

mtszkarbowiak added 2 commits October 17, 2024 02:45

Executing coroutine from script error fix

9817557

Coroutines events subscribed to ticks

e07c384

mtszkarbowiak force-pushed the feat/coroutines-v2 branch from 1bc0af0 to e07c384 Compare October 17, 2024 10:00

mtszkarbowiak added 4 commits October 17, 2024 20:31

Late update tick getter fix

02a3696

Accumulation point injection, scene accumulation fix

e72e425

Merge branch 'FlaxEngine:master' into feat/coroutines-v2

034b35b

Coroutines tests fix

e5b8cc4

mafiesto4 requested changes Oct 17, 2024

View reviewed changes

mafiesto4 added this to the 1.10 milestone Oct 17, 2024

mtszkarbowiak added 3 commits October 17, 2024 21:44

Style fix

c0b8da9

Ticks elements array elements access method revert

33afeba

Coroutines debugging leftovers fix

cc261c6

mtszkarbowiak force-pushed the feat/coroutines-v2 branch from 414cd8a to cc261c6 Compare October 17, 2024 19:50

mtszkarbowiak added 4 commits October 17, 2024 22:00

Scene ticking array elements access method revert

72ed635

Coroutines executor array elements access update

182e8d7

Style fix

2ddecc3

Coroutine wait for suspension point

728ee36

mafiesto4 approved these changes Oct 18, 2024

View reviewed changes

mtszkarbowiak added 2 commits October 18, 2024 22:26

Coroutine sequence naming fix

a876213

Coroutine sequence naming fix cd.

4a0e137

mtszkarbowiak marked this pull request as ready for review October 18, 2024 21:22

mafiesto4 reviewed Mar 2, 2025

View reviewed changes

mtszkarbowiak added 5 commits March 4, 2025 01:35

Forward declarations

200a2c6

Count of coroutines API type fix

6dcd2e6

Style fix

4c1061b

Manual inlining

7ade50c

ExecuteRepeated naming fix

39e0e3f

Previously `ExecuteRepeated`

mafiesto4 removed this from the 1.10 milestone Mar 11, 2025

Coroutines #2982

Are you sure you want to change the base?

Coroutines #2982

Conversation

mtszkarbowiak commented Oct 11, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mtszkarbowiak commented Oct 18, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mafiesto4 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mtszkarbowiak commented Oct 11, 2024 •

edited

Loading

mtszkarbowiak commented Oct 18, 2024 •

edited

Loading