util/Scheduler.js

  1. /**
  2.  * Scheduler.
  3.  *
  4.  * @author Alain Pitiot
  5.  * @version 2022.2.3
  6.  * @copyright (c) 2017-2020 Ilixa Ltd. (http://ilixa.com) (c) 2020-2022 Open Science Tools Ltd. (https://opensciencetools.org)
  7.  * @license Distributed under the terms of the MIT License
  8.  */
  10. /**
  11.  * <p>A scheduler helps run the main loop by managing scheduled functions,
  12.  * called tasks, after each frame is displayed.</p>
  13.  *
  14.  * <p>
  15.  * Tasks are either another [Scheduler]{@link Scheduler}, or a
  16.  * JavaScript functions returning one of the following codes:
  17.  * <ul>
  18.  * <li>Scheduler.Event.NEXT: Move onto the next task *without* rendering the scene first.</li>
  19.  * <li>Scheduler.Event.FLIP_REPEAT: Render the scene and repeat the task.</li>
  20.  * <li>Scheduler.Event.FLIP_NEXT: Render the scene and move onto the next task.</li>
  21.  * <li>Scheduler.Event.QUIT: Quit the scheduler.</li>
  22.  * </ul>
  23.  * </p>
  24.  *
  25.  * <p> It is possible to create sub-schedulers, e.g. to handle loops.
  26.  * Sub-schedulers are added to a parent scheduler as a normal
  27.  * task would be by calling [scheduler.add(subScheduler)]{@link Scheduler#add}.</p>
  28.  *
  29.  * <p> Conditional branching is also available:
  30.  * [scheduler.addConditionalBranches]{@link Scheduler#addConditional}</p>
  31.  */
  32. export class Scheduler
  33. {
  34. 	/**
  35. 	 * @memberof module:util
  36. 	 * @param {module:core.PsychoJS} psychoJS - the PsychoJS instance
  37. 	 */
  38. 	constructor(psychoJS)
  39. 	{
  40. 		this._psychoJS = psychoJS;
  42. 		this._taskList = [];
  43. 		this._currentTask = undefined;
  44. 		this._argsList = [];
  45. 		this._currentArgs = undefined;
  47. 		this._stopAtNextUpdate = false;
  48. 		this._stopAtNextTask = false;
  50. 		this._status = Scheduler.Status.STOPPED;
  51. 	}
  53. 	/**
  54. 	 * Get the status of the scheduler.
  55. 	 *
  56. 	 * @returns {Scheduler#Status} the status of the scheduler
  57. 	 */
  58. 	get status()
  59. 	{
  60. 		return this._status;
  61. 	}
  63. 	/**
  64. 	 * Task to be run by the scheduler.
  65. 	 *
  66. 	 * @callback Scheduler~Task
  67. 	 * @param {*} [args] optional arguments
  68. 	 */
  69. 	/**
  70. 	 * Schedule a new task.
  71. 	 *
  72. 	 * @param {Scheduler~Task | Scheduler} task - the task to be scheduled
  73. 	 * @param {...*} args - arguments for that task
  74. 	 */
  75. 	add(task, ...args)
  76. 	{
  77. 		this._taskList.push(task);
  78. 		this._argsList.push(args);
  79. 	}
  81. 	/**
  82. 	 * Condition evaluated when the task is run.
  83. 	 *
  84. 	 * @callback Scheduler~Condition
  85. 	 * @return {boolean}
  86. 	 */
  87. 	/**
  88. 	 * Schedule a series of task or another, based on a condition.
  89. 	 *
  90. 	 * <p>Note: the tasks are [sub-schedulers]{@link Scheduler}.</p>
  91. 	 *
  92. 	 * @param {Scheduler~Condition} condition - the condition
  93. 	 * @param {Scheduler} thenScheduler - the [Scheduler]{@link Scheduler} to be run if the condition is satisfied
  94. 	 * @param {Scheduler} elseScheduler - the [Scheduler]{@link Scheduler} to be run if the condition is not satisfied
  95. 	 */
  96. 	addConditional(condition, thenScheduler, elseScheduler)
  97. 	{
  98. 		const self = this;
  99. 		let task = function()
  100. 		{
  101. 			if (condition())
  102. 			{
  103. 				self.add(thenScheduler);
  104. 			}
  105. 			else
  106. 			{
  107. 				self.add(elseScheduler);
  108. 			}
  110. 			return Scheduler.Event.NEXT;
  111. 		};
  113. 		this.add(task);
  114. 	}
  116. 	/**
  117. 	 * Start this scheduler.
  118. 	 *
  119. 	 * <p>Note: tasks are run after each animation frame.</p>
  120. 	 */
  121. 	async start()
  122. 	{
  123. 		const self = this;
  124. 		const update = async (timestamp) =>
  125. 		{
  126. 			// stop the animation if need be:
  127. 			if (self._stopAtNextUpdate)
  128. 			{
  129. 				self._status = Scheduler.Status.STOPPED;
  130. 				return;
  131. 			}
  133. 			// self._psychoJS.window._writeLogOnFlip();
  135. 			// run the next scheduled tasks until a scene render is requested:
  136. 			const state = await self._runNextTasks();
  137. 			if (state === Scheduler.Event.QUIT)
  138. 			{
  139. 				self._status = Scheduler.Status.STOPPED;
  140. 				return;
  141. 			}
  143. 			// store frame delta for `Window.getActualFrameRate()`
  144. 			const lastTimestamp = self._lastTimestamp === undefined ? timestamp : self._lastTimestamp;
  146. 			self._lastDelta = timestamp - lastTimestamp;
  147. 			self._lastTimestamp = timestamp;
  149. 			// render the scene in the window:
  150. 			self._psychoJS.window.render();
  152. 			// request a new frame:
  153. 			requestAnimationFrame(update);
  154. 		};
  156. 		// start the animation:
  157. 		requestAnimationFrame(update);
  158. 	}
  160. 	/**
  161. 	 * Stop this scheduler.
  162. 	 */
  163. 	stop()
  164. 	{
  165. 		this._status = Scheduler.Status.STOPPED;
  166. 		this._stopAtNextTask = true;
  167. 		this._stopAtNextUpdate = true;
  168. 	}
  170. 	/**
  171. 	 * Run the next scheduled tasks, in sequence, until a rendering of the scene is requested.
  172. 	 *
  173. 	 * @name Scheduler#_runNextTasks
  174. 	 * @private
  175. 	 * @return {Scheduler#Event} the state of the scheduler after the last task ran
  176. 	 */
  177. 	async _runNextTasks()
  178. 	{
  179. 		this._status = Scheduler.Status.RUNNING;
  181. 		let state = Scheduler.Event.NEXT;
  182. 		while (state === Scheduler.Event.NEXT)
  183. 		{
  184. 			// check if we need to quit:
  185. 			if (this._stopAtNextTask)
  186. 			{
  187. 				return Scheduler.Event.QUIT;
  188. 			}
  190. 			// if there is no current task, we look for the next one in the list or quit if there is none:
  191. 			if (typeof this._currentTask == "undefined")
  192. 			{
  193. 				// a task is available in the taskList:
  194. 				if (this._taskList.length > 0)
  195. 				{
  196. 					this._currentTask = this._taskList.shift();
  197. 					this._currentArgs = this._argsList.shift();
  198. 				}
  199. 				// the taskList is empty: we quit
  200. 				else
  201. 				{
  202. 					this._currentTask = undefined;
  203. 					this._currentArgs = undefined;
  204. 					return Scheduler.Event.QUIT;
  205. 				}
  206. 			}
  207. 			else
  208. 			{
  209. 				// we are repeating a task
  210. 			}
  212. 			// if the current task is a function, we run it:
  213. 			if (this._currentTask instanceof Function)
  214. 			{
  215. 				state = await this._currentTask(...this._currentArgs);
  216. 			}
  217. 			// otherwise, we assume that the current task is a scheduler and we run its tasks until a rendering
  218. 			// of the scene is required.
  219. 			// note: "if (this._currentTask instanceof Scheduler)" does not work because of CORS...
  220. 			else
  221. 			{
  222. 				state = await this._currentTask._runNextTasks();
  223. 				if (state === Scheduler.Event.QUIT)
  224. 				{
  225. 					// if the experiment has not ended, we move onto the next task:
  226. 					if (!this._psychoJS.experiment.experimentEnded)
  227. 					{
  228. 						state = Scheduler.Event.NEXT;
  229. 					}
  230. 				}
  231. 			}
  233. 			// if the current task's return status is FLIP_REPEAT, we will re-run it, otherwise
  234. 			// we move onto the next task:
  235. 			if (state !== Scheduler.Event.FLIP_REPEAT)
  236. 			{
  237. 				this._currentTask = undefined;
  238. 				this._currentArgs = undefined;
  239. 			}
  240. 		}
  242. 		return state;
  243. 	}
  244. }
  246. /**
  247.  * Events.
  248.  *
  249.  * @enum {Symbol}
  250.  * @readonly
  251.  */
  252. Scheduler.Event = {
  253. 	/**
  254. 	 * Move onto the next task *without* rendering the scene first.
  255. 	 */
  256. 	NEXT: Symbol.for("NEXT"),
  258. 	/**
  259. 	 * Render the scene and repeat the task.
  260. 	 */
  261. 	FLIP_REPEAT: Symbol.for("FLIP_REPEAT"),
  263. 	/**
  264. 	 * Render the scene and move onto the next task.
  265. 	 */
  266. 	FLIP_NEXT: Symbol.for("FLIP_NEXT"),
  268. 	/**
  269. 	 * Quit the scheduler.
  270. 	 */
  271. 	QUIT: Symbol.for("QUIT"),
  272. };
  274. /**
  275.  * Status.
  276.  *
  277.  * @enum {Symbol}
  278.  * @readonly
  279.  */
  280. Scheduler.Status = {
  281. 	/**
  282. 	 * The Scheduler is running.
  283. 	 */
  284. 	RUNNING: Symbol.for("RUNNING"),
  286. 	/**
  287. 	 * The Scheduler is stopped.
  288. 	 */
  289. 	STOPPED: Symbol.for("STOPPED"),
  290. };