Package RASCAL.TaskManager

Description	Task &TaskManager related types and methods.
Author	bbracke
Date	2005/11/21 20:14:33
Revision	1.1

Clauses

Quick access : Clauses - Generics - Definitions - Subprograms

Context clauses
Interfaces.C
System
System.Unsigned_Types
RASCAL.OS

Use clauses
Interfaces.C
System
System.Unsigned_Types
RASCAL.OS

Definitions

Quick access : Clauses - Generics - Definitions - Subprograms

Types
*Name*	*Declaration*
Task_Type_Pointer	access Task_type
Task_List_Type	array (natural) of Task_Type
An array with a Task_Type for each task.
Task_List_Pointer	access Task_List_Type
Message_Quit_Pointer	access Message_Quit
Message_PreQuit_Pointer	access Message_PreQuit
Message_SaveDesktop_Pointer	access Message_SaveDesktop
Message_Shutdown_Pointer	access Message_Shutdown
Message_TaskInitialise_Pointer	access Message_TaskInitialise
Message_TaskCloseDown_Pointer	access Message_TaskCloseDown
Message_SlotSize_Pointer	access Message_SlotSize
Message_SetSlot_Pointer	access Message_SetSlot
Message_TaskNameRQ_Pointer	access Message_TaskNameRQ
Message_TaskNameIs_Pointer	access Message_TaskNameIs
Message_TaskStarted_Pointer	access Message_TaskStarted
Reason_PollWordNonZero_Pointer	access Reason_PollWordNonZero
Reason_NullReason_Pointer	access Reason_NullReason

Task_Type	record
Type used by Enumerate_Task to return information about each task.
*Component*	*Type*	*Default*
Flags	System.Unsigned_Types.Unsigned
Slot_Size	Integer
Name	Address
Handle	Integer

Message_Quit	record
On receiving this message the task should tidy up, call Wimp_CloseDown and OS_Exit.
*Component*	*Type*	*Default*
Header	Message_Event_Header

AMEL_Message_Quit	abstract tagged record
inheritance from	Message_EventListener (Message_Event_Quit)
*Component*	*Type*	*Default*
Event	Message_Quit_Pointer

Message_PreQuit	record
This message is broadcasted when Ctrl-Shift F12 is pressed. It is also sent to a specific task, when the user tries to quit it from the task display menu. If you have no objections to being killed, then ignore this message, and you will eventually receive a Quit message. If you object to being killed (unsaved data..), you should acknowledge this message, and then open a dialogue box asking the user what to do. If the user chooses to quit and the 'flag' was zero, you are supposed to restart the closedown sequence by emitting a Ctrl-Shift F12 (508), using Wimp_ProcessKey.
*Component*	*Type*	*Default*
Flag	Integer
Header	Message_Event_Header

AMEL_Message_PreQuit	abstract tagged record
inheritance from	Message_EventListener (Message_Event_PreQuit)
*Component*	*Type*	*Default*
Event	Message_PreQuit_Pointer

Message_SaveDesktop	record
This message is broadcasted by the task manager when the user has selected "Save boot file", or on exit from desktop if the system variable SaveDesk$File has a value (a pathname..).
*Component*	*Type*	*Default*
Flags	System.Unsigned_Types.Unsigned
File_Handle	System.Unsigned_Types.Unsigned
Header	Message_Event_Header

AMEL_Message_SaveDesktop	abstract tagged record
inheritance from	Message_EventListener (Message_Event_SaveDesktop)
*Component*	*Type*	*Default*
Event	Message_SaveDesktop_Pointer

Message_Shutdown	record
This message is broadcast when TaskManager_Shutdown is called with bit 3 of R0 set, to indicate a forced shutdown, for example due to power failure.
*Component*	*Type*	*Default*
Flags	System.Unsigned_Types.Unsigned
Header	Message_Event_Header

AMEL_Message_Shutdown	abstract tagged record
inheritance from	Message_EventListener (Message_Event_Shutdown)
*Component*	*Type*	*Default*
Event	Message_Shutdown_Pointer

Message_TaskInitialise	record
This message is broadcast when a task calls Wimp_Initialise. The fields are set so that it appears to originate from the new task. The Task Manager uses this message to identify the task's name. These names are stored in a table which can be queried using TaskManager_TaskNameFromHandle.
*Component*	*Type*	*Default*
Task_Name	Char_Array (1..228)
Slot_Size	System.Unsigned_Types.Unsigned
CAO	System.Unsigned_Types.Unsigned
Task_Handle	System.Unsigned_Types.Unsigned
Header	Message_Event_Header

AMEL_Message_TaskInitialise	abstract tagged record
inheritance from	Message_EventListener (Message_Event_TaskInitialise)
*Component*	*Type*	*Default*
Event	Message_TaskInitialise_Pointer

Message_TaskCloseDown	record
This message is broadcast when a task calls Wimp_CloseDown. The fields are set so that it appears to originate from the dying task.
*Component*	*Type*	*Default*
Task_Handle	System.Unsigned_Types.Unsigned
Header	Message_Event_Header

AMEL_Message_TaskCloseDown	abstract tagged record
inheritance from	Message_EventListener (Message_Event_TaskCloseDown)
*Component*	*Type*	*Default*
Event	Message_TaskCloseDown_Pointer

Message_SlotSize	record
This message is broadcast after Wimp_SlotSize is called. It is mainly used by the task manager to update its display. This message should not be acknowledged.
*Component*	*Type*	*Default*
Next_Size	System.Unsigned_Types.Unsigned
Slot_Size	System.Unsigned_Types.Unsigned
Task_Handle	System.Unsigned_Types.Unsigned
Header	Message_Event_Header

AMEL_Message_SlotSize	abstract tagged record
inheritance from	Message_EventListener (Message_Event_SlotSize)
*Component*	*Type*	*Default*
Event	Message_SlotSize_Pointer

Message_SetSlot	record
This message is broadcast when the user tries to alter a task's slot size by dragging the "memorybar" in the task manager. If a task can cope with this, it should first check the taskhandle, acknowledge the message and then call Wimp_SlotSize. This message is also sent by the task manager when the task is started. If this, or any later message, is not acknowledged, the task will get a green memorybar in the task manager (instead of a red one) and will not receive this message again; it will not be possible for the user to alter the task's slotsize.
*Component*	*Type*	*Default*
Task_Handle	System.Unsigned_Types.Unsigned
Slot_Size	System.Unsigned_Types.Unsigned
Header	Message_Event_Header

AMEL_Message_SetSlot	abstract tagged record
inheritance from	Message_EventListener (Message_Event_SetSlot)
*Component*	*Type*	*Default*
Event	Message_SetSlot_Pointer

Message_TaskNameRQ	record
This message can be used if your task want to find out the name of another task. Broadcast this message with correct handle, and the task mamager will respond with a TaskNameIs message. RISC OS 3 provides TaskManager_TaskNameFromHandle, which should be used in preference.
*Component*	*Type*	*Default*
Task_Handle	System.Unsigned_Types.Unsigned
Header	Message_Event_Header

AMEL_Message_TaskNameRQ	abstract tagged record
inheritance from	Message_EventListener (Message_Event_TaskNameRQ)
*Component*	*Type*	*Default*
Event	Message_TaskNameRQ_Pointer

Message_TaskNameIs	record
This message is sent by the task manager in response to a TaskNameRq message. RISC OS 3 provides TaskManager_TaskNameFromHandle, which should be used in preference.
*Component*	*Type*	*Default*
Task_Name	Char_Array (1..232)
Slot_Size	System.Unsigned_Types.Unsigned
Task_Handle	System.Unsigned_Types.Unsigned
Header	Message_Event_Header

AMEL_Message_TaskNameIs	abstract tagged record
inheritance from	Message_EventListener (Message_Event_TaskNameIs)
*Component*	*Type*	*Default*
Event	Message_TaskNameIs_Pointer

Message_TaskStarted	record
This message is sent by the Filer once it has started up all of the desktop filers so that the Task Manager can 'renumber' it. This is done so that during the SaveDesktop sequence the Filer's own commands can be performed after any network logons.
*Component*	*Type*	*Default*
Header	Message_Event_Header

AMEL_Message_TaskStarted	abstract tagged record
inheritance from	Message_EventListener (Message_Event_TaskStarted)
*Component*	*Type*	*Default*
Event	Message_TaskStarted_Pointer

Reason_PollWordNonZero	record
This message is returned when the poll word becomes non-zero. If bit 23 of the Wimp_Poll mask is set then this may be before messages and redraw requests have been returned (for example Message_ModeChange) which allows tasks to make updates to data which affect the contents of windows before the windows have been redrawn with out of date contents. With the bit clear this message is received at lower priority than user messages and redraw requests.
*Component*	*Type*	*Default*
PollWord	System.Unsigned_Types.Unsigned
PollWord_Address	System.Unsigned_Types.Unsigned

AWEL_Reason_PollWordNonZero	abstract tagged record
inheritance from	Wimp_EventListener (Reason_Event_PollWordNonZero, -1, -1)
*Component*	*Type*	*Default*
Event	Reason_PollWordNonZero_Pointer

Reason_NullReason	null record

AWEL_Reason_NullReason	abstract tagged record
inheritance from	Wimp_EventListener (Reason_Event_NullReason, -1, -1)
*Component*	*Type*	*Default*
Event	Reason_NullReason_Pointer

Exceptions
Unknown_Task

Pragmas
Convention	(C, Task_Type)
Convention	(C, Message_Quit)
Convention	(C, Message_PreQuit)
Convention	(C, Message_SaveDesktop)
Convention	(C, Message_Shutdown)
Convention	(C, Message_TaskInitialise)
Convention	(C, Message_TaskCloseDown)
Convention	(C, Message_SlotSize)
Convention	(C, Message_SetSlot)
Convention	(C, Message_TaskNameRQ)
Convention	(C, Message_TaskNameIs)
Convention	(C, Message_TaskStarted)
Convention	(C, Reason_PollWordNonZero)
Convention	(C, Reason_NullReason)

Subprograms

Quick access : Clauses - Generics - Definitions - Subprograms

Start_Task	function
*Return*	Integer
This SWI creates a new task, and executes the given *command. The SWI returns to you when new task exits, or calls Wimp_Poll. Note that you can only call this SWI from USR mode, and only if you are a 'live' task (ie. gained control from Wimp_Initialise or Wimp_Poll.

*Parameter name*	*Type*	*Mode*	*Default*
Command	String	in

Get_Task_List	function
*Return*	Task_List_Type
Return array with information about all current tasks.

Enumerate_Task	function
*Return*	integer
Enumerates through all running tasks.

*Parameter name*	*Type*	*Mode*	*Default*
Buffer	Task_Type	in
Index	integer	in	0

Get_TaskName	function
*Return*	String
Finds the taskname of task with the 'Handle'.

*Parameter name*	*Type*	*Mode*	*Default*
Handle	integer	in

Get_TaskHandle	function
*Return*	Integer
Finds a task given its name and returns the task's handle.

*Parameter name*	*Type*	*Mode*	*Default*
Name	String	in

Is_Task	function
*Return*	boolean
Is the task 'Name' running ?

*Parameter name*	*Type*	*Mode*	*Default*
Name	String	in

Nr_Of_Tasks	function
*Return*	Natural
Returns the number of tasks

Get_WindowOwner	function
*Return*	Integer
Returns the wimphandle of the task owning the window.

*Parameter name*	*Type*	*Mode*	*Default*
Window	Wimp_Handle_Type	in
Icon	Icon_Handle_Type	in