(**********************************************************************

    :Program.    Queue.def
    :Contents.   Generic data type: Queue (FIFO-list)
    :Author.     Michael Frieß [mif]
    :Address.    Kernerstr. 22a, 7000 Stuttgart 1, Germany
    :Copyright.  Public Domain, (C) Copyright 1988 by Michael Frieß
    :Language.   Modula-2
    :Translator. M2Amiga A+L V3.2d
    :Imports.    TaskMemory [bne]
    :History.    V1.0 [mif] 14.Sep.1988
    :History.    V1.1 [bne] 5.Feb.1989 (+ QueueAllocProc, Init() changed)
    :Remark.     Hi Micha! Although I've added error checking, my V1.1 code
    :Remark.     length is only 72% of yours (1514 : 1090 bytes)! [bne]
    :History.    V1.2 [bne] 5.Feb.1989 (+ Get, Remove)

**********************************************************************)

DEFINITION MODULE Queue;

FROM SYSTEM   IMPORT BYTE, ADDRESS;

TYPE    queue; (* opaque type! *)
     (* queue is a simple FIFO-list (First-In-First-Out) *)

VAR     QueueAllocProc:PROCEDURE(VAR ADDRESS,LONGINT);
        QueueDeallocProc:PROCEDURE(VAR ADDRESS);
(* Defaults are TaskMemory.Allocate() + TaskMemory.Deallocate() *)

PROCEDURE Init (VAR q:queue):BOOLEAN;
(* :output.   q = use this variable, when you call queue-procedures
   :result.   TRUE if OK, FALSE if an error occured
   :semantic. Initialize queue q for further use
*)

PROCEDURE Write (q:queue; Data : ARRAY OF BYTE):BOOLEAN;
(* :input.    q    = data is to be written in this queue
   :input.    data = data to be written
   :result.   FALSE, if there wasn't enough free memory, otherwise TRUE
   :semantic. a new element is appended at end of queue q
   :semantic. containing the given data.
*)

PROCEDURE Read (q:queue; VAR Data : ARRAY OF BYTE);
(* :input.    q    = read of this queue
   :output.   Data = contents of first element in queue
   :semantic. The contents of the first element is read into Data
   :semantic. and first element is deleted from queue.
*)

PROCEDURE Get (q:queue; VAR DataPtr:ADDRESS);
(* :input.    q: properly initialised not empty (!) queue
   :output.   DataPtr: pointer to the Data of the first element in queue
   :semantic. Returns a pointer to the first element
   :semantic. without removing it from queue.
*)

PROCEDURE Remove (q:queue);
(* :input.    q: properly initialised not empty (!) queue
   :semantic. Removes the first element of queue and frees its memory
   :note.     You can use this after Get() or to skip an element
   :note.     WARNING: After Remove(), the DataPtr of Get() isn't valid
   :note.     anymore because the element is deallocated!
*)

PROCEDURE Empty (q:queue) : BOOLEAN;
(* :input.    q = queue
   :return.   TRUE  : queue is empty
   :return.   FALSE : otherwise
   :semantic. returns, whether queue is empty or not.
*)

PROCEDURE Discard (VAR q:queue);
(* :input.    q = queue
   :semantic. Memory allocated for queue q is given back to
   :semantic. operating system.
*)

END Queue.