Task Manager
© September 2005 by Michael A. Nelson
mikestar13@sbcglobal.net
WHAT IS TASK MANAGER?
Task Manager is a non-OOP library derived from the forthcoming Method Euphoria 2.0.0 Task Manager package in the Method Euphoria Standard Class Library. The timing code is adapted from Rapid Deployment Software's Langwar Euphoria demo.
Task Manager provides cooperative multi-tasking for Euphoria programs. Tasks may be created with priorites from 0 (lowest) to 10 (highest). The time to start running the task is specifed, as well as how often to repeat the task (if at all).
Task Manager runs each task at the appropriate time, running higher priority tasks before lower priority tasks if several are ready at the same time.
Tasks are Euphoria functions. To create a task, define the function that performs the action for the task and pass its routine id to new_task. Task Manager will then run the task at the appropriate time. The function must return a sequence which is to be passed to the function the next time the task is run. (Task Manager will convert an atom return to a 1-element sequence.)
ALPHABETICAL LISTING OF GLOBAL ROUTINES AND CONSTANTS
The syntax convention for routines is to show the return value (for functions and
types) and the parameters as type names with digits to distinguish them:
object1, integer2, sequence3, etc. The type name "task" is an integer id for a task as returned by new_task.
current_task
- Variety
- function
- Syntax
- task1=current_task()
- Description
- Returns the task id of the currently executing task, or 0 if there is none.
get_activate
- Variety
- function
- Syntax
- atom1=get_activate(task1)
- Description
- Returns the time at which task1 will be run next, or TASK_INACTIVE if the task is inactive.
get_message
- Variety
- function
- Syntax
- object1=get_message(task1)
- Description
- Returns the message for task1. Each task has a message variable which can be used as the programmer sees fit--Task Manager does not use or alter it. This might be used for error handling or inter-task communication. If task1's message variable has never been set, it will be 0.
get_parameters
- Variety
- function
- Syntax
- sequence1=get_parameters(task1)
- Description
- During the run of task1, returns the parameters which were passed to the task; otherewise returns the parameters that will be passed to the next run of the task1.
get_priority
- Variety
- function
- Syntax
- integer1=get_priority(task1)
- Description
- Returns the priority of task1.
get_repeat
- Variety
- function
- Syntax
- atom1=get_repeat(task1)
- Description
- Returns the interval in seconds at which task1 is to be rerun. A return value of TASK_ONCE indicates that task1 is only to run once, TASK_NO_WAIT indicates that task1 is to be rerun as soon as possible after it finishes.
get_time
- Variety
- function
- Syntax
- atom1=get_time()
- Description
- Returns the time in seconds since the start of the program. For WIN32 and Linux/Free BSD this is identical to Euphoria's time function. For DOS32, get_time wraps time to handle DOS's 24-hour wraparound.
new_task
- Variety
- function
- Syntax
- task1=new_task(integer1,integer2,atom1,atom2,sequence1)
- Description
- Creates a new task. Integer1 is the routine id of the task's function. Integer2 is the task's priority, see set_priority. Atom1 is the time to activate the task, see set_activate. Atom2 is the interval at which the task is to be repeated, see set_repeat. Sequence1 is a list of parameters to pass to the function the first time the task is run. It is the programmer's responsibility to assume that they are the correct number and type. Returns an integer handle to identify the task.
next_task
- Variety
- procedure
- Syntax
- next_task()
- Description
- Runs the next task which is ready to run, if any. Normally next_task would be called periodically in a loop. See below for details of task scheduling. If next_task is called from within a fucntion which implements a task, acts as a no-op; this prevents certain problems with task recursion.
reschedule
- Variety
- procedure
- Syntax
- reschedule(task1,integer1,atom1,atom2,sequence1)
- Description
- Reschedules task1. Integer1 is the task's priority, see set_priority. Atom1 is the time to activate the task, see set_activate. Atom2 is the interval at which the task is to be repeated, see set_repeat. Sequence1 is a list of parameters to pass to the function the first time the task is run. It is the programmer's responsibility to assume that they are the correct number and type.
set_activate
- Variety
- procedure
- Syntax
- set_activate(task1,atom1)
- Description
- Sets the time at which task1 will be run next. The time is given in seconds after the present moment, ranging from 0 to 1 day (86400 seconds). The value TASK_INACTIVE (-1) or any other value outside the range of 0 to 86400 results in task1 being inactive: it will not be run until a new activation time is assigned.
set_message
- Variety
- procedure
- Syntax
- set_message(task1,object1)
- Description
- Sets the message for task1 to object1. Each task has a message variable which can be used as the programmer sees fit--Task Manager does not use or alter it. This might be used for error handling or inter-task communication.
set_priority
- Variety
- procedure
- Syntax
- set_priority(task1,intewger1)
- Description
- Sets the priority of task1 to integer1, which must be in the range of 0 (lowest priority) to 10 (highest priority).
set_repeat
- Variety
- proceduere
- Syntax
- set_repeat(task1,atom1)
- Description
- Sets the interval in seconds at which task1 is to be rerun to atom1. The value canj range from 0 to 1 day (86400 seconds). The value TASK_ONCE (-1) or any other value outside the range of 0 to 86400 results iin the task only being run once, until rescheduled.
task
- Variety
- type
- Syntax
- boolean1=task(object1)
- Description
- Determines whether object1 is a valid task handle.
TASK_INACTIVE
- Variety
- constant
- Description
- The value -1. When passed to new_task, reschedule, or set_activate, causes the task to be inactive.
TASK_MAX_INTERVAL
- Variety
- constant
- Description
- The value 86400 (the number of seconds in 1 day). When passed to new_task, reschedule, or set_activate, or set_repeat causes the task to be run one day from the current time, or to be rerun daily, as the case may be.
TASK_MAX_PRIORITY
- Variety
- constant
- Description
- The value 10. When passed to new_task, reschedule, or set_priority, causes the task to have the highest priority.
TASK_MIN_PRIORITY
- Variety
- constant
- Description
- The value 0. When passed to new_task, reschedule, or set_priority, causes the task to have the lowest priority.
TASK_NO_WAIT
- Variety
- constant
- Description
- The value 0. When passed to new_task, reschedule, or set_repeat, causes the task to be scheduled to rerun immediately after it returns.
TASK_NORMAL_PRIORITY
- Variety
- constant
- Description
- The value 5. When passed to new_task, reschedule, or set_priority, causes the task to have noraml or average priority.
TASK_NOW
- Variety
- constant
- Description
- The value 0. When passed to new_task, reschedule, or set_activate, causes the task to be scheduled to run immediately.
TASK_ONCE
- Variety
- constant
- Description
- The value -1. When passed to new_task, reschedule, or set_repeat, causes the task to be scheduled to run only once.
INTERNAL OPERATION OF THE TASK SCHEDULER
The task scheduler is run every time next_task is called. If there is a list of tasks from a previous call, the task scheduler runs the highest priority task and removes it from the list.
If the list is empty, the task scheduler forms a new list by checking each task's activation time to determine if a task is ready to run. Any task ready to run of sufficient priority is added to the list. If any tasks ready to run are found, the highest priority task is run and removed from the list.
The first time a new list is formed, only tasks with priority 10 are considered. The second time a new list is formed, tasks with priority 9 or 10 are considered, and so on until the eleventh time a new list is formed when all tasks are considered. When a new list is formed for the twelfth time, the cycle starts again and only tasks with priority 10 are considered.
When two or more tasks of the same priority are added to the list at the same time, the task with the lower task id is run first.