task_schedule

Definition: task_schedule(integer task_id, object schedule)
Description: Schedule task_id to run using the specified scheduling parameter.

task_id: a task identifier returned by task_create(), or 1|0 to schedule the main program/scheduler itself.

If schedule is a positive atom, it tells the task scheduler how many times it should run the time-shared task identified by task_id in one burst before it considers running other tasks.

If schedule is a sequence, it must be a 2-element sequence {min, max}, with both values greater than or equal to 0, which specifies the minimum and maximum times in seconds to wait before running the real-time task identified by task_id.
Also, min and max set the time interval for subsequent runs of task_id, unless overridden by another call to task_schedule() or task_suspend().
Comments: The task scheduler (see builtins\VM\pTask.e, an auto-include) uses the specified scheduling parameter as a guide when scheduling that task.

It may not always be possible to achieve the desired number of consecutive runs, or the desired time frame.
For instance, a task might take so long before yielding control, that another task misses it’s desired time window.

Real-time tasks have a higher priority. Time-shared tasks are only run when no real-time task is ready to execute. A task can switch back and forth between real-time and time-shared. It all depends on the last call to task_schedule() for that task. The scheduler never runs a real-time task before the start of its time frame (min), and it tries to avoid missing the deadline (max).

For precise timing, you can specify the same value for min and max. However, specifying a range of times gives the scheduler some flexibility, allowing it to schedule tasks more efficiently, and avoid non-productive delays. When the scheduler must delay, it calls sleep() to let the operating system run other programs.

The min and max values can be fractional. If the min value is smaller than the resolution of the scheduler’s clock (currently 0.01 seconds) then accurate time scheduling cannot be performed, but the scheduler will try to run the task several times in a row to approximate what is desired. For example, if you ask for a min time of 0.002 seconds, then the scheduler will try to run your task .01/.002 = 5 times in a row before waiting for the clock to "click" ahead by .01. During the next 0.01 seconds it will run your task (up to) another 5 times, provided your task can be completed 5 times in one clock period.

At program start-up there is a single task running. Its task_id is 1, and initially it is a time-shared task set to 1 run per task_yield(). For compatibility with OpenEuphoria, task 1 can also be referenced using a task_id of 0. No other task can run until task 1 executes a task_yield().

If task 1 (top-level) runs off the end of the main file, the whole program terminates, regardless of what other tasks may still be active.

If the scheduler finds that no task is active, i.e. no task will ever run again (not even task 1), it terminates the program with an exit code of 0, similar to abort(0).
Example 1:
-- Task t1 will be executed up to 10 times in a row before
-- other time-shared tasks are given control. If a real-time
-- task needs control, t1 will lose control to the real-time task.
task_schedule(t1, 10) 
Example 2:
-- Task t2 will be scheduled to run some time between 4 and 5 seconds
-- from now. Barring any rescheduling of t2, it will continue to
-- execute every 4 to 5 seconds thereafter.
task_schedule(t2, {4, 5})
See Also: task_create, task_yield, task_suspend, task_self