DEFINITION MODULE TaskControl;

        (****************************************************************)
        (*                                                              *)
        (*   Data structures internal to the kernel of the operating    *)
        (*     system; the dispatcher of the operating system; and      *)
        (*                  related procedures.                         *)
        (*                                                              *)
        (*      Programmer:     P. Moylan                               *)
        (*      Last edited:    4 November 1997                         *)
        (*      Status:         Seems to be working                     *)
        (*                                                              *)
        (****************************************************************)

IMPORT OS2;
FROM SYSTEM IMPORT ADDRESS;

(************************************************************************)
(*                                                                      *)
(*                         END-USER PROCEDURES                          *)
(*                                                                      *)
(************************************************************************)

CONST MaxPriority = 15;

TYPE
    PriorityLevel = [0..MaxPriority];
    NameString = ARRAY [0..15] OF CHAR;
    PROC1 = PROCEDURE (ADDRESS);

PROCEDURE CreateTask (StartAddress: PROC;  taskpriority: PriorityLevel;
                                                taskname: NameString);

    (* Must be called to introduce a task to the system. The first      *)
    (* parameter, which should be the name of a procedure containing    *)
    (* the task code, gives the starting address.  The second parameter *)
    (* is the task's base priority.  If this task has a higher priority *)
    (* than its creator, it will run immediately.  Otherwise, it        *)
    (* becomes ready.                                                   *)

    (* A task terminates itself either by an explicit call to TaskExit, *)
    (* or simply by falling out of the bottom of its code.              *)
    (* There is no provision for tasks to kill other tasks.  Suicide    *)
    (* is legal, but murder is not.                                     *)

PROCEDURE CreateTask1 (StartAddress: PROC1;  taskpriority: PriorityLevel;
                                   taskname: NameString;  param: ADDRESS);

    (* Like CreateTask, but allows the passing of a single parameter    *)
    (* "param" to the task.                                             *)

PROCEDURE TaskExit;

    (* Removes the currently running task from the system, and performs *)
    (* a task switch to the next ready task.                            *)

    (* There is normally no need for a task to call this procedure,     *)
    (* because it is automatically called when the task code "falls out *)
    (* the bottom" by executing its final procedure return.             *)

(************************************************************************)
(*                                                                      *)
(*                LOCKS FOR CRITICAL SECTION PROTECTION                 *)
(*                                                                      *)
(*  Note that we distinguish between a Lock and a Semaphore.            *)
(*  A Semaphore is a general semaphore - whose operations are defined   *)
(*  in module Semaphores - which can be used for general inter-task     *)
(*  interlocking.  A Lock is similar to a binary semaphore (with a      *)
(*  more efficient implementation than a Semaphore), but may be used    *)
(*  only in a strictly nested fashion and is therefore useful only      *)
(*  for critical section protection.                                    *)
(*                                                                      *)
(************************************************************************)

TYPE Lock;      (* is private *)

PROCEDURE CreateLock (VAR (*OUT*) L: Lock);

    (* Creates a new lock. *)

PROCEDURE DestroyLock (VAR (*INOUT*) L: Lock);

    (* Disposes of a lock. *)

PROCEDURE Obtain (L: Lock);

    (* Obtains lock L, waiting if necessary. *)

PROCEDURE Release (L: Lock);

    (* Releases lock L - which might unblock some other task. *)

PROCEDURE ReleaseAllLocks;

    (* Releases all locks held by the current task.  Application-level  *)
    (* tasks normally won't need to call this procedure; it is          *)
    (* provided to support the system shutdown function and for things  *)
    (* like "emergency abort" operations.                               *)

(*
PROCEDURE DumpLockState (L: Lock);

    (* Writes information about L to the dump file. *)
*)

(************************************************************************)
(*                  PROCEDURES PRIVATE TO THE KERNEL                    *)
(************************************************************************)

TYPE TaskID = OS2.TID;

PROCEDURE CurrentTaskID(): TaskID;

    (* Returns the TaskID of the calling task. *)

PROCEDURE SuspendMe (id: TaskID;  TimeLimit: CARDINAL): BOOLEAN;

    (* Suspends the caller.  A TRUE result indicates that the time      *)
    (* limit expired.                                                   *)

PROCEDURE ResumeTask (id: TaskID): BOOLEAN;

    (* Resumes a task specified by its thread ID.  The function result  *)
    (* is normally TRUE, but is FALSE if the task couldn't be resumed   *)
    (* (usually because that task no longer exists).                    *)

END TaskControl.

