home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 534.lha / vmalloc_v1.2 / vmalloc.doc.pp / vmalloc.doc
Encoding:
Text File  |  1991-08-08  |  8.0 KB  |  251 lines
  1.  
  2. Virtual Memory library
  3.  
  4. V0.0 (The virtuosity is V0.0. The code is v1.2)
  5.  
  6. by David Le Blanc (david@mlb.geomechanics.csiro.au)
  7.  
  8. Functions in this library are designed for efficient use of a large number
  9. of memory allocation within or without memory constraints.
  10.  
  11. =================== FILE STORAGE IMPLEMENTATION. ========================
  12.  
  13. A single flat file is created and managed, in no special format.
  14.  
  15. ======================== MEMORY MANAGEMENT. =============================
  16.  
  17. After initialising, memory may be asked for with the function
  18. VM_AllocMem(). This function partitions off a chunk of file (whether 
  19. appending to the file, or re-using a previously free'd block).
  20.  
  21. Before using the memory, you must make sure it is mapped to physical
  22. memory. Doing this involves the VM_Lock() call, which will allocate
  23. memory and read the necessary file segment if needed.
  24.  
  25. Once you are finished, you allow the VM routines to take control of the
  26. block by releasing it with the VM_UnLock() function call.
  27.  
  28. While a segment is Lock'ed, it is guaranteed to NOT be flushed from memory
  29. while the inverse if NOT true. An UnLock'ed segment may remain in
  30. memory for as long as the VM routines feel it may be in use.
  31.  
  32. Refinements. To explain the last statement, let me explain what happens
  33. when a Lock is UnLocked. The lock is placed on a 'Reserved' list, where
  34. it remains. If the list has grown to a maximum (currently 10 locks)
  35. the the oldest lock is flushed for real, (writing it to disk if needed),
  36. and marked INVALID.
  37.  
  38. Since without an MMU it is impossible to know whether a particular memmory
  39. address has been changed, the function VM_ReadOnly() may be called on a
  40. lock to indicate that it is not going to be modified, and hence will
  41. not be written back to disk when flushed.
  42.  
  43. The file allocation functions are very smart about where to squeeze blocks
  44. into a file. A request for a block will be placed into the smallest hole
  45. larger than the requested size. Freeing a block will automatically merge
  46. it with adjacent free blocks in the free pool.
  47.  
  48. You may test the effectiveness of the reserved list method of caching
  49. by setting the maximum list length to zero, and checking just how much
  50. longer it takes to execute.
  51.  
  52. If you write a program with this, changing the value of the maximum
  53. reserved list can greatly affect program performance, and should either
  54. be tuned to your program, or left open for the user to adjust depending
  55. on memory capacity and disk speed.
  56.  
  57. This implementation makes it a tiny bit hard to manage linked lists unless
  58. you remember that it is acceptable to use pointers to the actual locks
  59. instead of the memory. Hence as you follow the list, you should call
  60. next = VM_Lock(ll->Next), then Unlock(ll). Depending on the size of the
  61. list, it may or may not spend a lot of time accessing the disk.
  62.  
  63. Due to the overhead in terms of LOCKS and Reserved list caches etc, it
  64. would be very unwise to use this system for allocating blocks of under
  65. say about 2k. (3meg of 2K blocks approx 1500 blocks, hence the overhead
  66. would be about 1500*sizeof(lock) (+ 10 * 2k reserved list). or just over
  67. 60K overhead. (for 3meg, not too bad... Just use large memory allocations)
  68.  
  69. OH ALMOST FORGOT. These routines are hard wired to use my resource tracking
  70.                   library 'track.library'. You MUST declare TrackBase, and
  71.           open track.library to be able to use these functions.
  72.           (You also require track.h for prototypes (supplied))
  73.           For more info on track.library, mail me, or look for
  74.           tracklib.lzh on AB20.
  75.           NOTE that the track.library support is for debugging
  76.           purposes, and can be removed painlessly.
  77.  
  78. NOTE: The idea and functionality of the caching is stolen from the paging
  79.       algorithm used by the good old VAX. As locks are used then freed,
  80.       they go to the head of the 'reserved' list. Only the oldest lock is
  81.       actually ever flushed. This allows for a amount of time saving where
  82.       an unlocked memory allocation is re-locked within a certain amount of
  83.       time, ie before it is ever actually written to disk, hence saving the
  84.       cost of memory allocations, seeking, writing and reading. Note that 
  85.       it is a given that the caching code executes at LEAST and order of
  86.       magnitude faster than a single disk access.
  87.  
  88. ============================ DISCLAIMER. ================================
  89.  
  90. I DO NOT GUARANTEE THAT THIS CODE WORKS PERFECTLY AS PERFORMED, although
  91. If you find problems be sure to throw them at me. 
  92.  
  93. I ACCEPT NO RESPONSIBILITY FOR DAMAGE CAUSED DIRECTLY OR INDIRECTLY BY
  94. THIS CORRECT OR INCORRECT USE OF THIS PACKAGE.
  95.  
  96. If you can read the source code, then I had better stop writing comments.
  97.  
  98. =========================== LIMITATIONS. ================================
  99.  
  100. Currently the only limitations are that a single memory segment MUST fit
  101. within your physical memory, AND that memory can be allocated whether
  102. there is filesystem space to hold it or not!
  103.  
  104. ========================== IMPLEMENTATION. ==============================
  105.  
  106. =========================================================================
  107.  
  108. FUNCTION
  109.  
  110.     struct VM_Construct *VM_Open(char *VM_Filename) ;
  111.  
  112. INPUTS
  113.  
  114.     VM_Filename : filename to use as the virtual memory file.
  115.  
  116. RETURNS
  117.  
  118.     A pointer to a VM_Construct structure. 
  119.  
  120. NOTES
  121.  
  122.     This will fail if it runs out of memory, or the file cannot be
  123.     created. A NULL pointer is returned on failure.
  124.  
  125. =========================================================================
  126.  
  127. FUNCTION
  128.  
  129.     ULONG VM_Close(struct VM_Construct *VM_C) ;
  130.  
  131. INPUTS
  132.  
  133.     The VM_Construct structure returned from VM_Open().
  134.  
  135. RETURNS
  136.  
  137.     An Error is returned (-1).
  138.  
  139. NOTES
  140.  
  141.     This function will return FAIL if it cannot flush all locks on
  142.     the reserved list, and close the file.
  143.  
  144. =========================================================================
  145.  
  146. FUNCTION
  147.  
  148.     struct VM_Lock *VM_AllocMem(struct VM_Construct *VM_C, LONG Size) ;
  149.  
  150. INPUTS
  151.  
  152.     VM_C : The VM_Construct structure returned from VM_Open().
  153.     Size : The size of the memory segment wanted.
  154.  
  155. RETURNS
  156.  
  157.     struct VM_Lock. A pointer to a lock structure that can be used 
  158.     with VM_Lock() and VM_UnLock().
  159.  
  160. NOTES
  161.  
  162.     This will fail on a lack of memory.
  163.  
  164. =========================================================================
  165.  
  166. FUNCTION
  167.  
  168.     ULONG VM_FreeMem(struct VM_Lock *VM_L) ;
  169.  
  170. INPUTS
  171.  
  172.     VM_L : The VM_Lock structure returned by VM_AllocMem()
  173.  
  174. RETURNS
  175.  
  176.     Zero is returned on success.
  177.  
  178. NOTES
  179.  
  180.     This function may fail (and return -1) if it is unable to flush
  181.     the lock. It will, in general, UnLock any currently Lock'ed locks
  182.     before freeing them.
  183.  
  184. =========================================================================
  185.  
  186. FUNCTION
  187.  
  188.     void *VM_Lock(struct VM_Lock *VM_L) ;
  189.  
  190. INPUTS
  191.  
  192.     VM_L : The VM_Lock structure returned by VM_AllocMem()
  193.  
  194. RETURNS
  195.  
  196.     A (void *) pointer to the memory that has been allocated and locked
  197.     for you!
  198.  
  199.     Note, this pointer is equivalent to VM_L->VM_Addr (Now don't you go
  200.     and use VM_L->VM_Addr without first locking it! That would be
  201.     naughty)
  202.  
  203. NOTES
  204.  
  205.     The will fail if memory is not available for the segment, or if the
  206.     seek to the correct position in the file (or the read) fails.
  207.  
  208. =========================================================================
  209.  
  210. FUNCTION
  211.  
  212.     ULONG VM_UnLock(struct VM_Lock *VM_L) ;
  213.  
  214. INPUTS
  215.  
  216.     VM_L : The VM_Lock structure returned by VM_AllocMem()
  217.  
  218. RETURNS
  219.  
  220.     Zero is returned on success.
  221.  
  222. NOTES
  223.  
  224.     This function will fail if it tries to flush a lock (either the one
  225.     you passed, or an old one from the reserved list) and cannot seek
  226.     or write successfully.
  227.  
  228. =========================================================================
  229.  
  230. FUNCTION
  231.  
  232.     void VM_ReadOnly(struct VM_Lock *VM_L) ;
  233.  
  234. INPUTS
  235.  
  236.     VM_L : The VM_Lock structure returned by VM_AllocMem()
  237.  
  238. RETURNS
  239.  
  240.     None.
  241.  
  242. NOTES
  243.  
  244.     This function sets the 'ReadOnly' flag in the lock, so that when the
  245.     lock is next UnLocked it will not be written to file. Note that the
  246.     lock may still be placed on the reserved list, to prevent it being
  247.     re-read.
  248.  
  249. =========================================================================
  250.  
  251.