Class Documentation

Name:Task
Version:1.0
ID:ID_TASK
Status:Stable
Category:System
Include:system/task.h
Date:October 2002
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2002. All rights reserved.



Description

Tasks are one of the most basic features used for program execution in most operating systems. In the Pandora Engine, Task objects are created to represent each individual process within the system. You can inspect any Task object to reveal information the program's Author, Copyright, Location and other details. You can spawn new Tasks by using the standard object creation and initialisation procedures.

If you want to execute a compiled program, set the Location field to point to the executable file before initialising the Task. You may pass arguments to the executable by setting the ArgsList field. Once the Task object is successfully initiialised, use the Activate action to run the executable. If the file is run successfully, a new Task object will be spawned that represents the executable (which means it is safe to destroy your Task object immediately afterwards). If the Activate action returns with ERR_Okay then the executable program was run successfully.

If you want to find the Task that belongs to your current execution process, use the CurrentTask() function to retrieve it.

If you want to send messages to a Task, you need to gain access to the Task object and then read the MessageQueue field. This will return a message queue ID that you can then use to send messages to the Task via the SendMessage() function.

Actions

The Task class supports the following actions:

Activate  Activating a Task object will execute it.
GetUnlistedField  Retrieves unlisted field values.
SetUnlistedField  Unlisted fields are supported by the Task class for the storage of program variables.

Methods

The Task class implements the following methods:

AddTaskArgument  Adds new arguments to the ArgsList field.
ExpungeTask  Forces a Task to expunge unused code.
Quit  Sends a quit message to a task.

Structure

The Task object consists of the following public fields:

Actions  Used to gain direct access to a Task's actions.
Args  Command line arguments (string format).
ArgsList  Command line arguments (list format).
Author  Describes the person that wrote the program.
Copyright  Copyright/licensing details.
Date  The date that the program was last updated or compiled.
Location  Location to load an executable file from.
MessageQueue  Read this field to acquire a Task's message queue ID.
Name  Name of the Task.
Output  Defines the object that will receive printed output from a Task.
Path  The current path being used by a task object.
Short  Short description of the program/task.
Action:Activate
Short:Activating a Task object will execute it.

Activating a Task causes it to run the executable file referred to in the Location field. Once the program file has been executed the Task object effectively becomes useless, so it is recommended that you immediately free Task objects after activating them.

If you need to contact the Task that was created from the execution process, you will need to search for it in order to initiate contact.

Result
ERR_Okay  The execution process was successful.
ERR_FieldNotSet  The Location field has not been set.
ERR_Failed  The execution process failed.

Method:AddTaskArgument()
Short:Adds new arguments to the ArgsList field.
Arguments:
STRING Argument  The name of the argument that you want to add.

This method provides a simple way of adding new arguments to the ArgsList field. All you need to do is provide the name of the new argument that you want to add to the end of the list.

Result
ERR_Okay  The argument was added to the ArgsList array.
ERR_Args  Invalid arguments were specified.
ERR_GetField  The ArgsList field could not be retrieved.
ERR_AllocMemory  Memory for the new ArgsList could not be allocated.

Method:ExpungeTask()
Short:Forces a Task to expunge unused code.

Calling the Expunge method of a Task object forces it to free all of the unused code that has been cached over the course of normal operation. This involves sending expunge messages to all of the modules that have been used by the Task. Those that are still in use will remain in memory.

If the Expunge method is called on the System Task, it will ask all Tasks in the system to expunge unused code. You can find the System Task object by searching for the "SystemTask" name.


Method:Quit()
Short:Sends a quit message to a task.

The Quit method can be used as a convenient way of sending a task a quit message. This will normally result in the destruction of the task, so long as it is still functioning correctly and has been coded to respond to the MSGID_QUIT message type. It is perfectly legal for a task to ignore a quit message if it is programmed to stay alive, so if you need to kill a task outright then remove it with the Free action.


Field:Actions
Short:Used to gain direct access to a Task's actions.
Type:APTR *
Status:Get

This field provides direct access to the actions of a Task. You can use it in the development of an executable program to hook into the Pandora Engine's action system. This allows you to create a program that blends in seamlessly with the system's object oriented design. In some cases this is a necessity, for example, use of some functions will require you to hook into the ActionNotify action.

The Actions field itself points to a list of action routines that are arranged into a lookup table, sorted by action ID. You can hook into an action simply by writing to its index in the table with a pointer to the routine that you want to use for that action. For example:

   if (AccessObject(CurrentTask(), 5000, &Task) IS ERR_Okay) {
      GetField(Task, FID_Actions, FT_POINTER, &Actions);
      Actions[AC_ActionNotify] = PROGRAM_ActionNotify;
      ReleaseObject(Task);
   }

The synopsis of the routines that you use for hooking into the action list must match the following:

   ERROR PROGRAM_ActionNotify(OBJECTPTR Task, APTR Args);

It is recommended that you refer to the Action Support Guide before hooking into any action that you have not written code for before.


Field:Args
Short:Command line arguments (string format).
Type:STRING
Status:Set

If you would like to set the command line arguments for a new Task using a single string, define the arguments through this field. The string that you pass will be disassembled and the arguments will be added to the ArgsList field.


Field:ArgsList
Short:Command line arguments (list format).
Type:STRING *
Status:Get/Set

If a program is written to accept user arguments, then this field is the place to obtain them. The arguments are listed in a string based array that is terminated with a NULL pointer. Thus if the user enters the following into a command-line:

   1> YourProgram PREFS MyPrefs -file "athene:documents/readme.txt"

Then you will get:

   STRING Args[] = {
      "PREFS",
      "MyPrefs",
      "-file",
      "athene:documents/readme.txt",
      NULL
   };

If the user did not supply any command line arguments, this field will be set to NULL.


Field:Author
Short:Describes the person that wrote the program.
Type:STRING
Status:Read/Init

This field gives information about the author of the program/task. If the author is not determinable from the Location, this field will usually be set to NULL.


Field:Copyright
Short:Copyright/licensing details.
Type:STRING
Status:Read/Init

The developer of the program can set copyright details which will appear in this string. The copyright should include the company name, year of copyright and any extra details. The string should be brief and to the point, i.e. under 80 characters.


Field:Date
Short:The date that the program was last updated or compiled.
Type:STRING
Status:Read/Init

The Date usually specifies the date on which the program was compiled for public release. It is up to the developer of the program to set this string correctly and keep it current.

The correct specification for this string is "Day Month Year" or "Month Year" as in the following examples:

   "14 February 1998"
   "6 May 1997"
   "January 2000"

Please do not use shorthand dates such as "14/2/98". Do not include the time or any other information besides that which is outlined here.


Field:Location
Short:Location to load an executable file from.
Type:STRING
Status:Read/Init

When a Task object is activated, this field will be checked for a valid filename. If the file is found, the excutable code will be loaded from this source. The source must be in an executable format recognised by the native platform.


Field:MessageQueue
Short:Read this field to acquire a Task's message queue ID.
Type:MEMORYID
Status:Read

If you need the ID of a Task's message queue, read this field to obtain it. Once you have a Task's message queue ID, you can use it to send messages to the Task. For information on messaging, refer to the GetMessage(), ProcessMessages() and SendMessage() functions.


Field:Name
Short:Name of the Task.
Type:STRING
Status:Read/Init

This field specifies the name of the Task or program that has been initialised. It is up to the developer of the program to set the Name which will appear in this field. If there is no name for the Task then the system may assign a randomly generated name.


Field:Output
Short:Defines the object that will receive printed output from a Task.
Type:OBJECTID
Status:Read/Write

This field defines the object that a Task should print text and data to; effectively providing a similar service to that of 'stdout' in the POSIX standard. The object referred to by this field must be capable of receiving information via data channels.

If output from the Task is not required, this field can be left at a setting of NULL.


Field:Path
Short:The current path being used by a task object.
Type:STRING
Status:Get/Set

A task may specify a current "operating path" that determines where it should load files from when an absolute path is not specified for file access. The following example demonstrates an absolute filename:

   athene:documents/readme.txt

This is a relative filename:

   my/files/readme.txt

In the second instance, if the task's current path was "user:documents/" then the filesystem would expand the filename to "user:documents/my/files/readme.txt".


Field:Short
Short:Short description of the program/task.
Type:STRING
Status:Read/Init

This field allows for the specification of a short description for the Task. The description should be under 80 characters (one sentence). The description is typically useful for occasions where the user is debugging the system or trying to get a quick overview of what tasks are currently running. By creating a useful description, you can ease system maintenance for the user.