🛠️🐜 Antkeeper superbuild with dependencies included https://antkeeper.com
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

208 lines
6.6 KiB

  1. # Crash Course: cooperative scheduler
  2. <!--
  3. @cond TURN_OFF_DOXYGEN
  4. -->
  5. # Table of Contents
  6. * [Introduction](#introduction)
  7. * [The process](#the-process)
  8. * [Adaptor](#adaptor)
  9. * [The scheduler](#the-scheduler)
  10. <!--
  11. @endcond TURN_OFF_DOXYGEN
  12. -->
  13. # Introduction
  14. Sometimes processes are a useful tool to work around the strict definition of a
  15. system and introduce logic in a different way, usually without resorting to the
  16. introduction of other components.
  17. `EnTT` offers a minimal support to this paradigm by introducing a few classes
  18. that users can use to define and execute cooperative processes.
  19. # The process
  20. A typical process must inherit from the `process` class template that stays true
  21. to the CRTP idiom. Moreover, derived classes must specify what's the intended
  22. type for elapsed times.
  23. A process should expose publicly the following member functions whether
  24. required (note that it isn't required to define a function unless the derived
  25. class wants to _override_ the default behavior):
  26. * `void update(Delta, void *);`
  27. It's invoked once per tick until a process is explicitly aborted or it
  28. terminates either with or without errors. Even though it's not mandatory to
  29. declare this member function, as a rule of thumb each process should at
  30. least define it to work properly. The `void *` parameter is an opaque pointer
  31. to user data (if any) forwarded directly to the process during an update.
  32. * `void init();`
  33. It's invoked when the process joins the running queue of a scheduler. This
  34. happens as soon as it's attached to the scheduler if the process is a top
  35. level one, otherwise when it replaces its parent if the process is a
  36. continuation.
  37. * `void succeeded();`
  38. It's invoked in case of success, immediately after an update and during the
  39. same tick.
  40. * `void failed();`
  41. It's invoked in case of errors, immediately after an update and during the
  42. same tick.
  43. * `void aborted();`
  44. It's invoked only if a process is explicitly aborted. There is no guarantee
  45. that it executes in the same tick, this depends solely on whether the
  46. process is aborted immediately or not.
  47. Derived classes can also change the internal state of a process by invoking
  48. `succeed` and `fail`, as well as `pause` and `unpause` the process itself. All
  49. these are protected member functions made available to be able to manage the
  50. life cycle of a process from a derived class.
  51. Here is a minimal example for the sake of curiosity:
  52. ```cpp
  53. struct my_process: entt::process<my_process, std::uint32_t> {
  54. using delta_type = std::uint32_t;
  55. void update(delta_type delta, void *) {
  56. remaining -= std::min(remaining, delta);
  57. // ...
  58. if(!remaining) {
  59. succeed();
  60. }
  61. }
  62. private:
  63. delta_type remaining{1000u};
  64. };
  65. ```
  66. ## Adaptor
  67. Lambdas and functors can't be used directly with a scheduler for they are not
  68. properly defined processes with managed life cycles.<br/>
  69. This class helps in filling the gap and turning lambdas and functors into
  70. full featured processes usable by a scheduler.
  71. The function call operator has a signature similar to the one of the `update`
  72. function of a process but for the fact that it receives two extra arguments to
  73. call whenever a process is terminated with success or with an error:
  74. ```cpp
  75. void(Delta delta, void *data, auto succeed, auto fail);
  76. ```
  77. Parameters have the following meaning:
  78. * `delta` is the elapsed time.
  79. * `data` is an opaque pointer to user data if any, `nullptr` otherwise.
  80. * `succeed` is a function to call when a process terminates with success.
  81. * `fail` is a function to call when a process terminates with errors.
  82. Both `succeed` and `fail` accept no parameters at all.
  83. Note that usually users shouldn't worry about creating adaptors at all. A
  84. scheduler creates them internally each and every time a lambda or a functor is
  85. used as a process.
  86. # The scheduler
  87. A cooperative scheduler runs different processes and helps managing their life
  88. cycles.
  89. Each process is invoked once per tick. If it terminates, it's removed
  90. automatically from the scheduler and it's never invoked again. Otherwise it's
  91. a good candidate to run one more time the next tick.<br/>
  92. A process can also have a child. In this case, the parent process is replaced
  93. with its child when it terminates and only if it returns with success. In case
  94. of errors, both the parent process and its child are discarded. This way, it's
  95. easy to create chain of processes to run sequentially.
  96. Using a scheduler is straightforward. To create it, users must provide only the
  97. type for the elapsed times and no arguments at all:
  98. ```cpp
  99. entt::scheduler<std::uint32_t> scheduler;
  100. ```
  101. It has member functions to query its internal data structures, like `empty` or
  102. `size`, as well as a `clear` utility to reset it to a clean state:
  103. ```cpp
  104. // checks if there are processes still running
  105. const auto empty = scheduler.empty();
  106. // gets the number of processes still running
  107. entt::scheduler<std::uint32_t>::size_type size = scheduler.size();
  108. // resets the scheduler to its initial state and discards all the processes
  109. scheduler.clear();
  110. ```
  111. To attach a process to a scheduler there are mainly two ways:
  112. * If the process inherits from the `process` class template, it's enough to
  113. indicate its type and submit all the parameters required to construct it to
  114. the `attach` member function:
  115. ```cpp
  116. scheduler.attach<my_process>("foobar");
  117. ```
  118. * Otherwise, in case of a lambda or a functor, it's enough to provide an
  119. instance of the class to the `attach` member function:
  120. ```cpp
  121. scheduler.attach([](auto...){ /* ... */ });
  122. ```
  123. In both cases, the return value is an opaque object that offers a `then` member
  124. function to use to create chains of processes to run sequentially.<br/>
  125. As a minimal example of use:
  126. ```cpp
  127. // schedules a task in the form of a lambda function
  128. scheduler.attach([](auto delta, void *, auto succeed, auto fail) {
  129. // ...
  130. })
  131. // appends a child in the form of another lambda function
  132. .then([](auto delta, void *, auto succeed, auto fail) {
  133. // ...
  134. })
  135. // appends a child in the form of a process class
  136. .then<my_process>();
  137. ```
  138. To update a scheduler and therefore all its processes, the `update` member
  139. function is the way to go:
  140. ```cpp
  141. // updates all the processes, no user data are provided
  142. scheduler.update(delta);
  143. // updates all the processes and provides them with custom data
  144. scheduler.update(delta, &data);
  145. ```
  146. In addition to these functions, the scheduler offers an `abort` member function
  147. that can be used to discard all the running processes at once:
  148. ```cpp
  149. // aborts all the processes abruptly ...
  150. scheduler.abort(true);
  151. // ... or gracefully during the next tick
  152. scheduler.abort();
  153. ```