(* source: h:\modula\defs\QueueADT.DEF    v1.0a             revised: 88.07.22
   author: G.Greene, AGCS D/429 (NS/TS), 312/681-7783       created: 88.07.22

   function:
    This is the interface for a package which exports an Abstract Data Type
    for queues.

   history:
    88.07.22  1.0a  initial release.
*)


DEFINITION MODULE  QueueADT;


FROM  SYSTEM  IMPORT  BYTE;


TYPE
  Queues;



(*  Create a new (empty) queue specified by the parameter.

**  NB!!!  This procedure MUST be invoked for a queue before any other
    procedure in this module can be used on that queue.  The result of
    failing to do so is likely to be disasterous.  In addition, this
    procedure should not be invoked with an existing queue:  the storage
    associated with that queue would be lost.  To empty an existing queue,
    use EmptyTheQueue;  to deallocate ("destroy") an existing queue, use
    DestroyQueue.
*)

  PROCEDURE  CreateQueue (
            (*out*)  VAR  queue: Queues );



(*  Empty the queue specified by the parameter of its contents.  If the
    queue has been destroyed, this procedure will do nothing.
*)

  PROCEDURE  EmptyTheQueue (
           (*in/out*)  VAR  queue: Queues );



(*  Destroy the queue specified by the parameter, deallocating all the storage
    associated with it.  If invoked for a previously destroyed queue, this
    procedure will do nothing.  A queue destroyed by this procedure will be
    ignored by most of the other procedures.  The specific action each will
    take is indicated in its description.  One exception:  CreateQueue will
    reinstate a queue which has been destroyed.
*)

  PROCEDURE  DestroyQueue (
          (*in/out*)  VAR  queue: Queues );

(*                                                                        [2]
 source: h:\modula\defs\QueueADT.DEF    v1.0a             revised: 88.07.22 *)


(*  Return TRUE if the queue specified by the parameter is currently empty,
    or if the queue has been destroyed.  Return FALSE only if the queue
    exists and has at least one entry.
*)

  PROCEDURE  isEmpty (
              (*in*)  queue: Queues ):  BOOLEAN;



(*  Return the number of elements in the queue specified by the parameter.
    This procedure will return zero for an empty queue, or for a queue which
    has been destroyed.
*)

  PROCEDURE  QueueSize (
                (*in*)  queue:  Queues ):  CARDINAL;

(*                                                                        [3]
 source: h:\modula\defs\QueueADT.DEF    v1.0a             revised: 88.07.22 *)


(*  Enqueue the data specified in the first parameter at the back of the
    queue specified by the second parameter.  No action will be taken for a
    destroyed queue.
*)

  PROCEDURE   FIFOEnqueue (
                   (*in*)  data:   ARRAY  OF BYTE;
                   (*in*)  queue:  Queues );



(*  Enqueue the data specified in the first parameter into the priority queue
    specified by the second parameter.  The entry's priority is taken to be
    the first word of the data, interpreted as CARDINAL.  Zero is the highest
    priority;  lower priorities have higher CARDINAL values.  Thus the queue
    yields entries in increasing value of the priority.  This ordering was
    chosen to accommodate time-based queues.  Entries with the same priority
    are enqueued in order of receipt (FIFO).
*)

  PROCEDURE   PriorityEnqueue (
                       (*in*)  data:   ARRAY  OF BYTE;
                       (*in*)  queue:  Queues );



(*  Dequeue, to the data area specified by the first parameter, the front
    element of the queue specified by the second parameter.   If the queue
    is empty (or has been destroyed), the third parameter will be set FALSE;
    it is also set FALSE if the size of the front data element in the queue
    does not match the size of the data area to receive it.  Otherwise, the
    third parameter is set TRUE, indicating that the first parameter has
    valid data.  If the third parameter is FALSE, the queue has not been
    changed.
*)

  PROCEDURE  Dequeue (
         (*out*) VAR  data:    ARRAY  OF BYTE;
         (*in*)       queue:   Queues;
         (*out*) VAR  DataOK:  BOOLEAN );

(*                                                                        [4]
 source: h:\modula\defs\QueueADT.DEF    v1.0a             revised: 88.07.22 *)


(*  Copy, to the data area specified by the first parameter, an element of the
    queue specified by the second parameter.   The element to copy is the one
    specified by the third parameter (the front element is numbered zero).
    If the queue is empty (or has been destroyed), the fourth parameter will
    be set FALSE;  it is also set FALSE if the size of the front data element
    in the queue does not match the size of the data area to receive it, or
    if there is no such element.  Otherwise, the fourth parameter is set TRUE,
    indicating that the first parameter has valid data.  No change is made to
    to the queue in any case.  This procedure can be used as part of code to
    dump the contents of a queue--for example, LOOPing using the value of the
    fourth parameter as an EXIT condition.
*)

  PROCEDURE  ReadElement (
             (*out*) VAR  data:    ARRAY  OF BYTE;
             (*in*)       queue:   Queues;
             (*in*)       element: CARDINAL;
             (*out*) VAR  DataOK:  BOOLEAN );

END  QueueADT.
