home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pmos2002.zip / DEF / QUEUES.DEF < prev    next >
Text File  |  1996-09-16  |  5KB  |  88 lines
  1. DEFINITION MODULE Queues;
  2.  
  3.         (********************************************************)
  4.         (*                                                      *)
  5.         (*              Generic queue module.                   *)
  6.         (*                                                      *)
  7.         (*  Programmer:         P. Moylan                       *)
  8.         (*  Last edited:        16 September 1996               *)
  9.         (*  Status:             OK                              *)
  10.         (*                                                      *)
  11.         (********************************************************)
  12.  
  13. (************************************************************************)
  14. (*                                                                      *)
  15. (*  A non-obvious decision to be made in the design of a module like    *)
  16. (*  this is whether to work directly with the caller's data, or with    *)
  17. (*  pointers to the data.  In the present case, this means deciding     *)
  18. (*  whether to implement queues of user data or queues of pointers.     *)
  19. (*  The former choice is superior in terms of clarity and ease of use,  *)
  20. (*  but requires the physical copying of data between the queue and     *)
  21. (*  the caller's data structure.  The latter choice is more efficient,  *)
  22. (*  but requires the caller to be concerned with allocation and         *)
  23. (*  deallocation of data space.  With some languages we would not be    *)
  24. (*  faced with this delicate choice, but Modula-2 has relatively poor   *)
  25. (*  support for generic data structures.                                *)
  26. (*                                                                      *)
  27. (*  For this module, the decision has been to support the more          *)
  28. (*  efficient but less elegant arrangement: to add something to the     *)
  29. (*  queue, the caller supplies a pointer to the data, which might       *)
  30. (*  require that the caller allocate some space for that data.  When    *)
  31. (*  an item is removed from the queue, what is returned is again a      *)
  32. (*  pointer to the data.  That is, the actual data live in a data       *)
  33. (*  space which is under the control of the user.  This implies that    *)
  34. (*  the caller can - but should not - modify queued data.  This         *)
  35. (*  solution is not as clean as it might have been, but is justified    *)
  36. (*  by the need of some callers of this module for a low-overhead       *)
  37. (*  solution.                                                           *)
  38. (*                                                                      *)
  39. (*  Note, however, that the caller is not required to supply space for  *)
  40. (*  the "bookkeeping" information such as the pointers which link the   *)
  41. (*  queue elements together.  That level of detail is hidden inside     *)
  42. (*  this module, as it should be.                                       *)
  43. (*                                                                      *)
  44. (*  Critical section protection is also provided; that is, a queue      *)
  45. (*  may safely be used by multiple tasks.                               *)
  46. (*                                                                      *)
  47. (************************************************************************)
  48.  
  49. FROM SYSTEM IMPORT
  50.     (* type *)  ADDRESS;
  51.  
  52. TYPE Queue;     (* is private *)
  53.  
  54. PROCEDURE CreateQueue (VAR (*OUT*) Q: Queue);
  55.  
  56.     (* Creates a new queue, initially empty.    *)
  57.  
  58. PROCEDURE DestroyQueue (Q: Queue);
  59.  
  60.     (* Destroys queue Q, thus freeing up the space it occupied.  Any    *)
  61.     (* data still on the queue are lost.  After this call, no further   *)
  62.     (* operations should be performed on the queue.                     *)
  63.  
  64. PROCEDURE AddToQueue (Q: Queue;  DataPointer: ADDRESS);
  65.  
  66.     (* Places a new element at the tail of queue Q.  The caller has an  *)
  67.     (* obligation to ensure that DataPointer^ remains in existence      *)
  68.     (* for as long as it remains on the queue.                          *)
  69.  
  70. PROCEDURE TakeFromQueue (Q: Queue): ADDRESS;
  71.  
  72.     (* Removes and returns a pointer to the datum at the head of the    *)
  73.     (* queue.  If the queue is empty, waits until data available.       *)
  74.  
  75. PROCEDURE TakeFromQueueTimed (Q: Queue;  TimeLimit: CARDINAL): ADDRESS;
  76.  
  77.     (* Like TakeFromQueue, but waits no longer than TimeLimit           *)
  78.     (* milliseconds.  Returns NIL if the time limit expires.  Choose    *)
  79.     (* TimeLimit=0 for a non-blocking check of the queue.               *)
  80.  
  81. PROCEDURE Empty (Q: Queue): BOOLEAN;
  82.  
  83.     (* Returns TRUE iff Q is empty.  Warning: if more than one task is  *)
  84.     (* using this queue, there is no guarantee as to how long the queue *)
  85.     (* will remain empty.                                               *)
  86.  
  87. END Queues.
  88.