home *** CD-ROM | disk | FTP | other *** search
/ RBBS in a Box Volume 1 #2 / RBBS_vol1_no2.iso / add2 / tavram.zip / TAVRAM.DOC < prev    next >
Text File  |  1989-06-01  |  16KB  |  379 lines
  1.  
  2.              Documentation for TaVram.PAS - Turbo Pascal Unit
  3.                   Virtual Heap Manager for Turbo Pascal
  4.  
  5.                     (tested under Turbo Pascal v5.0)
  6.  
  7.            Copyright 1989 - By Thomas Astin - All rights reserved.
  8.  
  9.  
  10. Thomas Astin  (Compuserve 73407,3427)
  11. 3451 Vinton Ave. Unit 9
  12. Los Angeles,   CA  90034
  13.  
  14.  
  15. This unit's story
  16. -----------------
  17. After seeing lots of talk on BPROGA (Compuserve) about virtual heap managers
  18. I decided the best way for me to understand what all the talk was about was
  19. to attempt creation of my own virtual heap manager for Turbo Pascal.
  20. TaVram is the result.
  21.  
  22. As limited and simple as it is, after writing TaVram I had a much better
  23. understanding of what is involved in basic virtual heap management. I
  24. uploaded it in hopes that it will help some other TP user learn the
  25. same basics that I did.  Have fun!
  26.  
  27.                 =Tom=
  28.  
  29.  
  30. How to use TaVram
  31. -----------------
  32. Understand that you need Kim Kokkonen's HEAP.ARC available on the BPROGA
  33. forum on Compuserve.  It contains the GrabHeap unit and alot of other nifty
  34. routines that let you write programs that have more control over heap
  35. management (by intercepting TP's normal operation, etc). For more
  36. information on these routines see the documentation files contained in
  37. HEAP.ARC. Also, there is a vital patch to the TPC compiler that makes
  38. your program call a user defined ISR for all dereferncing. Not compiling
  39. your program with this patched compiler renders TaVram useless.
  40.  
  41. TaVram is very easy to use.  Just include it in your Uses statement as
  42. follows:
  43.  
  44. Uses
  45.   TpCrt,
  46.   ThisUnit,
  47.   TaVram;      { <---- included in uses }
  48.  
  49.  
  50. TaVram's initialization code will open two files VRAM.$$$ and VFREE.$$$
  51. that are used to store a virtual heap and a virtual free list respectively.
  52. At the start of the program virtual heap management is OFF by default.  It
  53. can be started by issuing a VRamOn which is an Inline macro that sets
  54. UseVram (a boolean) to True.
  55.  
  56. From this point (after VRamOn) any calls to New will allocate data space
  57. on the virtual heap.  This does NOT necessarily mean that data is not
  58. allocated on the real heap (in fact, it is).  It just means that
  59. if the real heap space runs empty that TaVram will start "paging out" the
  60. least used data to the virtual heap file (VRAM.$$$).  Also any
  61. dereferences are routed to TaVram's special dereferencing routine.  The
  62. dereferencing routine handles any "paging in" (from VRAM.$$$) that is
  63. necessary. It can also tell if a pointer is not a TaVram pointer by a
  64. special signature used in the segment portion of the pointer.
  65.  
  66. There are several interfaced items in TaVram that deserve an explaination
  67. at this point but first let me define some phrases that might make reading
  68. the explainations a little easier.  These definitions are TaVram specific
  69. and are not necessarily those of the industry.
  70.  
  71.         VRam Heap Pointer  : A pointer that contains a VRam signature and
  72.                              a valid handle.  It is a pointer that has been
  73.                              allocated while VRamOn is in effect.  When
  74.                              this term is used it also refers to the data
  75.                              being pointed to.
  76.  
  77.         Real Heap          : TP's normal heap as you know it.
  78.  
  79.         Virtual Heap       : Those VRam Heap Pointers on the real heap
  80.                              and in the virtual heap file.
  81.  
  82.         Paging out,
  83.         Paged out          : The act of taking data from normal RAM and
  84.                              placing it in virtual RAM (in this case, a
  85.                              disk file) in order to free up Real Heap.
  86.  
  87.         Paging in,
  88.         Paged in           : The act of taking data from virtual RAM (in
  89.                              this case, a disk file) and placing it on
  90.                              the Real Heap to enable the program to
  91.                              make use of the data.
  92.  
  93.  
  94.         VRamHeapFile,
  95.         VRAM.$$$           : The disk file that contains portions of the
  96.                              virtual heap that have been "paged out."
  97.  
  98.  
  99.         Free List          : A list of enties that describe free areas
  100.                              of a heap, whether virtual or real.
  101.  
  102.         VRamFreeFile,
  103.         VFREE.$$$          : The disk file that contains the free list of
  104.                              VRAM.$$$
  105.  
  106.  
  107.  
  108.  
  109.  
  110. ==============================================================================
  111. UseVRam : Boolean  (default is False)
  112. ------------------------------------------------------------------------------
  113. See VRamOn.
  114.  
  115.  
  116. ==============================================================================
  117. procedure VRamOn;
  118. ------------------------------------------------------------------------------
  119. Turns the UseVRam flag ON.  This will enable VRam allocation until a VRamOff
  120. is encountered.  Any New operation will allocate the pointer as a VRam Heap
  121. Pointer.  Doing a UseVRam:=True has the same effect as VRamOn;
  122.  
  123.  
  124. Var
  125.   SP1,
  126.   SP2 : ^String;
  127. begin
  128.   .
  129.   .
  130.   .
  131.   VRamOn;
  132.   New(SP1);   {SP1 is VRam Heap Pointer containing a signature in the Segment
  133.                portion and a handle in the offset portion}
  134.   VRamOff;
  135.   New(SP2);   {SP2 is a normal TP pointer containing the address of data}
  136.   .
  137.   .
  138.   .
  139. end.
  140.  
  141.  
  142. ==============================================================================
  143. procedure VRamOff; (Default)
  144. ------------------------------------------------------------------------------
  145. Turns the UseVRam flag off.  This will enable TP's normal real heap management
  146. as opposed to TaVRam heap managment.  Use it when you want to allocate a
  147. pointer and guarantee that the data never leaves memory.  UseVRam:=False has
  148. the same effect as VRamOff. This is the default becuase initialization
  149. routines that allocate heap space would end up using VRam allocation
  150. routines and they may not work in these circumstances.  It really depends
  151. on how the Unit allocating the pointers uses the pointers (see "Watch Out"
  152. below).
  153.  
  154.  
  155. ==============================================================================
  156. function VRamPageOutOldest : Boolean;
  157. ------------------------------------------------------------------------------
  158. This function will page out the least used data from the heap to the virtual
  159. heap file (VRAM.$$$).  It will only page out VRam Heap Pointers allocated
  160. with VRamOn (or UseVRam:=True).
  161.  
  162.  
  163. ==============================================================================
  164. procedure VRamPageOutFreeMem(Size : Word);
  165. ------------------------------------------------------------------------------
  166. This will call VRamPageOutOldset until Size bytes are available on the heap.
  167. It is governed by several factors.  Those factors being PageVRam,
  168. VRamMaxHeapToUse, and MaxAvail.  The best way to explain this is to have
  169. you view the source code of the procedure VRamPageOutFreeMem in the Unit
  170. TaVram.  The WHILE statement shows the governing factors.
  171.  
  172.  
  173. ==============================================================================
  174. procedure VRamGetMem(var P: Pointer; Size: Word);
  175. ------------------------------------------------------------------------------
  176. This is the routine called instead of TP's normal GetMem.  If VRamOn is in
  177. effect then virtual heap routines will be used to allocate the pointer's data
  178. area.  If VRamOff is in effect then the normal TP GetMem is called.  In
  179. either case, if there is not enough real heap available for the new pointer
  180. then paging will occur if VRamPageOn is in effect or PageVRam:=True.
  181.  
  182.  
  183. ==============================================================================
  184. procedure VRamFreeMem(var P : Pointer; Size: Word);
  185. ------------------------------------------------------------------------------
  186. This procedure is called instead TP's FreeMem.  If the pointer being
  187. deallocated is a VRam Heap Pointer then virtual deallocation routines are
  188. called.  If it is a normal TP pointer (allocated with VRamOff) then TP's
  189. FreeMem is called.
  190.  
  191.  
  192. ==============================================================================
  193. PageVRam : Boolean  (default is True)
  194. ------------------------------------------------------------------------------
  195. See VRamPageOn and VRamPageOff.
  196.  
  197.  
  198. ==============================================================================
  199. procedure VRamPageOn;  (default)
  200. ------------------------------------------------------------------------------
  201. Turns ON the virtual paging flag PageVRam. Calling this has the same effect
  202. as PageVRam:=True.  Use this to allow VRamPageOutFreeMem to page out VRam Heap
  203. Pointers from the heap to VRamHeapFile.  At first this might not make sense
  204. because if you didn't want to page out items then you would simply not call
  205. VRamPageOutFreeMem.  However, the other virtual heap management routines
  206. in TaVram call VRamPageOutFreeMem whenever they need to page out anything to
  207. gain more real heap space. If you want to force the paging out of the oldest
  208. item without care of the PageVram flag then just use the function
  209. VRamPageOutOldest - it is not governed.
  210.  
  211.  
  212. ==============================================================================
  213. procedure VRamPageOff;
  214. ------------------------------------------------------------------------------
  215. Turns OFF the virtual paging flag PageVRam.  Calling this has the same effect
  216. as PageVRam:=False.  This will inhibit TaVRams automatic paging out of the
  217. oldest VRam heap items.
  218.  
  219.  
  220. ==============================================================================
  221. AdjustHeapPtrAfterFreeMem : Boolean  (Default = True)
  222. ------------------------------------------------------------------------------
  223. This flag tells TaVram whether or not to merge VRam Free List entries, if
  224. possible, after each deallocation of a VRam Heap Pointer.  You might call
  225. it mild compression.
  226.  
  227.  
  228. ==============================================================================
  229. VRamMaxHeapToUse : LongInt (Default = 700000)
  230. ------------------------------------------------------------------------------
  231. This is the maximum heap that TaVram should use.  By default it is set to
  232. utilize all available heap. If you use the default then you will have to
  233. adjust TP's FreeMin to insure that there is enough heap for the free
  234. list to expand.  Otherwise deallocating a pointer that requires a free list
  235. entry will cause a TP runtime error to occur if there is no real heap left
  236. (see misc info below).
  237.  
  238.  
  239. ==============================================================================
  240. VRamHeapUsed : LongInt (Default = 0)
  241. ------------------------------------------------------------------------------
  242. This is the current amount of heap (in bytes) being used by TaVram for VRam
  243. Heap Pointers.  It, of course, starts at 0.
  244.  
  245.  
  246. ==============================================================================
  247. function VRamLock(P : Pointer) : Boolean;
  248. ------------------------------------------------------------------------------
  249. This function lets you put a lock on the pointer passed to it. Locking it will
  250. prevent it from being paged out until it is unlocked with VRamUnlock.  This
  251. function will return False if the Pointer is not a VRam Heap Pointer or the
  252. handle is not found on the heap.  The later case can usually be solved by
  253. simply dereferencing the pointer.  Doing so will force it to be paged in.
  254.  
  255.  
  256. ==============================================================================
  257. function VRamUnLock(P : Pointer) : Boolean;
  258. ------------------------------------------------------------------------------
  259. This function lets you release a lock previously placed on a VRam Heap
  260. Pointer.
  261.  
  262.  
  263. ==============================================================================
  264.  
  265.  
  266. Miscellanious Information
  267. -------------------------
  268. In order to use TaVram compile your program with the {$P+} ($P is a
  269. directive available with the patched TPC compiler) directive in
  270. sections of code where virtual heap management is to be used.  It is
  271. suggested to use {$P+} for your entire program and then use VRamOn
  272. and VRamOff in sections where you want to turn its use ON and OFF.
  273. Dereferencing a VRam Heap Pointer with VRamOff will still work as long as
  274. the section of code where the dereference takes place is compiled with the
  275. patched $P+ directive.
  276.  
  277. Once again, you should also adjust TP's FreeMin to keep a minimum amount of
  278. memory for TP's Free List.  You should do this especially if you are not
  279. going to use the VRamMaxHeapToUse variable.  Not doing so in this situation
  280. will result in a runtime error if you max out the heap and try to free
  281. memory because there will be no more heap for the free list.
  282.  
  283.  
  284. Conditional Defines
  285. -------------------
  286. You'll notice that in the source code for TaVram there are some conditional
  287. defines located at the top.  For the most part you don't really have to
  288. be concerned with these.  Here is a brief explaination of each.
  289.  
  290.      DEBUG      : When defined TaVram will NOT erase the two files
  291.                   VRAM.$$$ and VFREE.$$$.  By default it is not
  292.                   defined.
  293.  
  294.      USEINLINE  : When defined TaVram will use he experimental Inline
  295.                   code for the function VRamHandleOnHeap. By default
  296.                   it is not defined.  USELONG will not work when this
  297.                   is defined.
  298.  
  299.      USELONG    : When defined TaVram will use a LongInt for the
  300.                   usage counter rather than a Word.  By default it
  301.                   is not defined. When USEINLINE is defined this will
  302.                   be automatically UNDEFined.
  303.  
  304.      ERRORMSG   : When defined TaVram will include error messages
  305.                   within the program.  This takes up memory so one
  306.                   might want to undefine it to minimize memory
  307.                   usage.  By default it is defined.
  308.  
  309.  
  310.  
  311. Errors
  312. ------
  313. At this point errors are just halted with one message.  If there is alot
  314. of response to improve TaVram then more effort will be put into error
  315. messages, etc.  Also keep in mind that runtime errors are not trapped and
  316. the program will halt with the normal TP runtime error message.  If you
  317. experience a runtime error and cannot find the cause then just drop me
  318. a line on CIS and I will do my best to assist you (who knows, it might
  319. be a bug <g>).
  320.  
  321. Some reasons why TaVram will abort are as follows:
  322.  
  323.     1. Attempt to deallocate an invalid pointer (ie: nil pointer).
  324.  
  325.     2. Attempt to page out a VRam item and there is none to page out.
  326.  
  327.     3. Attempt to allocate a virtual pointer has failed.
  328.  
  329.     4. Attempt to allocate a virtual free list entry has failed.
  330.  
  331.  
  332. Watch Out!
  333. ----------
  334. Make sure you're careful when you dereference a VRam Heap Pointer that
  335. is part of a record that you're are also dereferencing (or any other
  336. situation that is similar).
  337.  
  338. For example
  339.  
  340.    type
  341.      Prec : ^MyRec;
  342.      MyRec = record
  343.        DumVar : Integer;
  344.        PR : Prec
  345.      end;
  346.    var
  347.      MyRecPtr : Prec;
  348.    begin
  349.      New(MyRecPtr);
  350.      New(MyRecPtr^.PR);
  351.      .
  352.      .
  353.      .
  354.      with MyRecPtr^ do begin  { page in MyRecPtr }
  355.        PR^.DumVar:=DumVar;    { if MyRecPtr gets paged out when
  356.                                 MyRecPtr.PR gets paged in then
  357.                                 MyRecPtr.DumVar won't be there
  358.                                 anymore!}
  359.      end;
  360.      .
  361.      .
  362.      .
  363.    end;
  364.  
  365.  
  366.  
  367. Demo Programs
  368. -------------
  369. I have included two demo-programs.  One is a simple text demo and the
  370. other is basically the same as the text demo except it offers a graphic
  371. view of what is going on.  Make sure you have ample disk space available
  372. for these demos (around 1/2 a meg should be safe).  If you have a floppy
  373. based system then you might want to shorten the array size in the demos
  374. so less VRam Heap is used (disk space).
  375.  
  376.  
  377. Good luck and have fun!
  378.  
  379.