TEXT   31
ABQ module
Guest on 7th February 2023 01:49:25 PM


  1. Introduction
  2. ------------
  3.  
  4. _`.intro`: This is the design of the ABQ module, which implements a
  5. fixed-length queue of small objects.
  6.  
  7. _`.readership`: This document is intended for any MM developer.
  8.  
  9. _`.name`: The name ABQ originally stood for "Available Block Queue" as
  10. the module is used by the MVT pool.
  11.  
  12.  
  13. Requirements
  14. ------------
  15.  
  16. _`.req.push`: Clients can efficiently push new elements onto the queue.
  17.  
  18. _`.req.pop`: Clients can efficiently pop elements from the queue.
  19.  
  20. _`.req.empty`: Clients can efficiently test whether the queue is empty.
  21.  
  22. _`.req.abstract`: The ABQ module does not know anything about the
  23. elements in the queue other than their size.
  24.  
  25. _`.req.delete`: Clients can delete elements from the queue. (Note: not necessarily efficiently.)
  26.  
  27. _`.req.iterate`: Clients can iterate over elements in the queue.
  28.  
  29.  
  30. Interface
  31. ---------
  32.  
  33. ``typedef ABQStruct *ABQ``
  34.  
  35. ``ABQ`` is the type of a queue. It is an alias for ``ABQStruct *``.
  36. ``ABQStruct`` is defined in the header so that it can be inlined in
  37. client structures: clients must not depend on its implementation
  38. details.
  39.  
  40. ``void ABQInit(Arena arena, ABQ abq, void *owner, Count elements, Size elementSize)``
  41.  
  42. Initialize the queue ``abq``. The parameter ``arena`` is the arena
  43. whose control pool should be used to allocate the memory for the
  44. queue; ``owner`` is passed to ``MeterInit()`` for the statistics;
  45. ``elements`` is the maximum number of elements that can be stored in
  46. the queue; and ``elementSize`` is the size of each element.
  47.  
  48. ``void ABQFinish(Arena arena, ABQ abq)``
  49.  
  50. Finish ``abq`` and free all resources associated with it.
  51.  
  52. ``Bool ABQPush(ABQ abq, void *element)``
  53.  
  54. If the queue is full, leave it unchanged and return ``FALSE``.
  55. Otherwise, push ``element`` on to the queue and return ``TRUE``.
  56.  
  57. ``Bool ABQPop(ABQ abq, void *elementReturn)``
  58.  
  59. If the queue is empty, return ``FALSE``. Otherwise, copy the first
  60. element on the queue into the memory pointed to by ``elementReturn``,
  61. remove the element from the queue, and return ``TRUE``.
  62.  
  63. ``Bool ABQPeek(ABQ abq, void *elementReturn)``
  64.  
  65. If the queue is empty, return ``FALSE``. Otherwise, copy the first
  66. element on the queue into the memory pointed to by ``elementReturn``
  67. and return ``TRUE``. (This is the same as ``ABQPop()`` except that
  68. the queue is unchanged.)
  69.  
  70. ``Bool ABQIsEmpty(ABQ abq)``
  71.  
  72. If the queue is empty, return ``TRUE``, otherwise return ``FALSE``.
  73.  
  74. ``Bool ABQIsFull(ABQ abq)``
  75.  
  76. If the queue is full, return ``TRUE``, otherwise return ``FALSE``.
  77.  
  78. ``Count ABQDepth(ABQ abq)``
  79.  
  80. Return the number of elements in the queue.
  81.  
  82. ``typedef Bool (*ABQVisitor)(Bool *deleteReturn, void *element, void *closure)``
  83.  
  84. A callback function for ``ABQIterate()``. The parameter ``element`` is
  85. an element in the queue, and ``closure`` is the value originally
  86. passed to ``ABQIterate()``. This function must set ``*deleteReturn``
  87. to ``FALSE`` if ``element`` must be kept in the queue, or ``TRUE`` if
  88. ``element`` must be deleted from the queue.  It must return ``TRUE``
  89. if the iteration must continue, or ``FALSE`` if the iteration must
  90. stop after processing ``element``.
  91.  
  92. ``void ABQIterate(ABQ abq, ABQVisitor visitor, void *closure)``
  93.  
  94. Call ``visitor`` for each element in the queue, passing the element
  95. and ``closure``. See ``ABQVisitor`` for details.
Raw Paste

Login or Register to edit or fork this paste. It's free.