home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 9 / 09.iso / l / l044 / 4.ddi / ONLINE.ZIP / BUFFERS.DOC next >
Encoding:
Text File  |  1990-10-23  |  4.5 KB  |  114 lines
  1.                              BUFFERS
  2.                              -------
  3.  
  4. This unit implements a simple movable memory manager, primarily 
  5. for use with the EDITORS unit. This unit sets aside a fixed
  6. amount of memory to manage at the end of the normal heap, the
  7. size of which is determined by BufHeapSize (in paragraphs).
  8. Memory is allocated through calls to NewBuffer and SetBufferSize.
  9. The advantage to movable memory managers is no memory is wasted
  10. due to fragmentation since the memory can move. Unfortunately,
  11. unless great care is taken, only one pointer to this memory can
  12. exist.
  13.  
  14. As with most movable memory managers, BUFFERS allocates the
  15. memory to what is referred to as a master pointer. The master
  16. pointer is kept up-to-date as to the current location of the
  17. buffer and is modified whenever the memory is moved. It is
  18. assumed that this pointer, the pointer passed to the NewBuffer
  19. procedure, is the only pointer that is pointing to the memory. If
  20. a copy is made, either through an assignment or if the pointer is
  21. passed as a parameter, the copy will not be updated. Typically
  22. when a copy is necessary a pointer to the master pointer is used
  23. instead. For example
  24.  
  25.   CopyPtr = @MstrPtr;
  26.  
  27. When the copy is used, it is dereferenced twice, as in
  28.  
  29.   CopyPtr^^ := {Some value};
  30.  
  31. so that all references to the memory allocated go through the
  32. master pointer. Note, since very few allocations can meet these
  33. requirements, this unit is not intended to replace Turbo Pascal's
  34. heap manager for general heap allocation needs.
  35.  
  36. Care should be taken when using pointers allocated with BUFFERS.
  37. It is bad practice to assume that a copy of the master pointer is
  38. valid. Such assumptions can lead to sporadic and very difficult-
  39. to-reproduce bugs. Typically, only the master pointer itself is 
  40. ever used, as is done in EDITORS.
  41.  
  42. BUFFERS is a simple movable memory manager in that it does not
  43. try to minimize the movement of buffers when a buffer is
  44. deallocated or resized. Buffers are positioned in the buffer area
  45. in the order they are allocated. When a buffer is resized, the
  46. buffers above it are moved up or down to accommodate the change.
  47. Since this movement takes time, it is assumed that the user of
  48. this unit will take great pains to minimize the resizing of
  49. buffers.
  50.  
  51.  
  52.                             Variables
  53.                             ---------
  54.  
  55. BufHeapSize: Word = 0;
  56.  
  57.   The amount of memory, in paragraphs, to be managed by this
  58.   unit. This variable must be set before calling InitBuffers.
  59.  
  60. BufHeapPtr: Word = 0;
  61.  
  62.   The segment marking the beginning of buffer memory.
  63.  
  64. BufHeapEnd: Word = 0;
  65.  
  66.   The segment marking the end of buffer memory.
  67.  
  68.  
  69.                     Procedures and Functions
  70.                     ------------------------
  71.  
  72. procedure InitBuffers;
  73.  
  74.   Allocates a block of memory from the end of the heap to be used
  75.   for buffers. The size of this block is determined by the value
  76.   of BufHeapSize (in paragraphs) when this routine is called.
  77.  
  78. procedure DoneBuffers;
  79.  
  80.   Returns to the heap the memory allocated by InitBuffers.
  81.  
  82. procedure NewBuffer(var P: Pointer);
  83.  
  84.   Allocates a buffer to the given pointer. The given pointer
  85.   becomes the master pointer to the allocated buffer and a
  86.   reference to the pointer's location is stored. The pointer will
  87.   be updated whenever the position of the buffer changes. The
  88.   buffer size is initially zero an can be adjusted by a call to
  89.   SetBufferSize. If a buffer is deallocated, or the size of a
  90.   buffer changes, the position of all the buffers allocated after
  91.   this one change. Each buffer has an overhead of 16 bytes (one
  92.   paragraph) which is used to store the size of the buffer and
  93.   the location of its master pointer.
  94.  
  95. procedure DisposeBuffer(P: Pointer);
  96.  
  97.   Deallocates the buffer allocated to the given pointer. The memory
  98.   allocated can now be used by other buffers. This pointer must
  99.   point to a buffer allocated with a call to NewBuffer. Disposing
  100.   of a buffer will cause the master pointer of all buffers allocated
  101.   after this buffer to change.
  102.  
  103. function GetBufferSize(P: Pointer): Word;
  104.  
  105.   Returns the size of the buffer allocated to this pointer. This
  106.   pointer must be a pointer allocated with NewBuffer.
  107.  
  108. function SetBufferSize(P: Pointer; Size: Word): Boolean;
  109.  
  110.   Increases or decreases the size of the given buffer. This
  111.   pointer must have been allocated with NewBuffer. Changing the 
  112.   size of a buffer will cause the master pointer of buffers
  113.   allocated after this one to change.
  114.