home *** CD-ROM | disk | FTP | other *** search
/ Windoware / WINDOWARE_1_6.iso / winutil / mlocal / mlocal.txt < prev    next >
Text File  |  1991-03-16  |  10KB  |  302 lines
  1. Legal Stuff...
  2.  
  3.  
  4. SOFTWARE LICENSE
  5.  
  6. You can use the routines in MLOCAL.ZIP royalty free if you 
  7. pay me $59.95. If you don't pay me, you can't use them.
  8.  
  9. "Use" means as you would "use" any other Copyrighted 
  10. software of this nature.
  11.  
  12. If there is a bug or any other problem with the routines 
  13. contained in MLOCAL.ZIP, and it damages you legally (or 
  14. otherwise) in any way its your problem not mine. You get 
  15. the source so you are liable!
  16.  
  17. If you find a bug let me know about it and I'll fix it and 
  18. upload a new version.
  19.  
  20.  
  21. Send to:  Dan Quigley
  22.           17219 NE 32nd Street
  23.           Redmond, WA 98052 
  24.           USA
  25.  
  26. For support or bug reports call:  (206) 885-9694
  27.  
  28.  
  29. Fun Stuff...
  30.  
  31.  
  32. MULTIPLE LOCAL HEAPS
  33.  
  34. The routines in MLOCAL.ZIP work on the principle that 
  35. Windows local heap management routines use the current 
  36. selector or (real mode segment) in the DS register, as the 
  37. "base" segment for its objects. You will note that most all 
  38. the routines change the DS register just prior to the 
  39. "normal" LocalXXXX call.
  40.  
  41. The only difference these routines have from their Windows 
  42. KERNEL counterparts is that they use sizeof(DWORD) handles 
  43. and the MultLocalLock() routine returns a far pointer. You 
  44. can expect the same behavior normally associated with the 
  45. Windows functions.
  46.  
  47. Applications that use MDI will find these routines 
  48. especially useful as they allow a separate "local" heap for 
  49. each MDI child. I have included an example of how this can 
  50. be done (see MLTEST.C).
  51.  
  52. For those of you that want optimal performance, You can use 
  53. the function SetDStoHeap(). This functions does just what 
  54. its name implies. There are several caveats to using this:
  55.  
  56.    1) Since you have changed your DS, you no longer have 
  57. access  to any global variables. (you can make far pointers 
  58. to the variables you need access to and pass them into your 
  59. function)
  60.  
  61.    2) While your DS is changed, the same rules apply to DLLs 
  62. DS!=SS. So don't expect the C runtime functions that assume 
  63. this to work. (see the SDK docs).
  64.  
  65.    3) You will have to make you own NEAR pointers. DO NOT 
  66. expect the C compiler to do this for you. You will GP fault 
  67. at best.
  68.  
  69.  
  70. FARLOCAL MEMORY
  71.  
  72. Included with the Multiple Local Heap routines are several 
  73. "FarLocal" that make use of some of the Multiple heap 
  74. routines. These hybrid functions allow applications to 
  75. allocate memory in the "spirit" of C runtime.
  76.  
  77. Each global allocation (using GlobalAlloc) you make in 
  78. Windows pmode, allocates at least one selector. The 
  79. 80286/386/486 processors limit the size of descriptor 
  80. table(s) to 64k, thus allowing 8k selectors. (in enhanced 
  81. mode, all windows apps (including drivers) run in a single 
  82. pmode VM). This can be a "limitation" to some application's 
  83. memory schemes, that use GlobalAlloc as its main source of 
  84. memory and make hundreds of allocations.
  85.  
  86. These FarLocal routines allow you to allocate as many 
  87. protect mode "global" objects as memory allows. As usual, 
  88. you can't get something for nothing, so the limitation of 
  89. FarLocal memory is that each memory object must be less than 
  90. 64k.
  91.  
  92. FarLocal routines use a VERY simple memory management 
  93. paradigm.  It is not the most efficient if your application 
  94. manipulates memory objects frequently. My suggestion if you 
  95. need this ability, is either re-write the FarLocal memory 
  96. manager or use standard global memory (GlobalAlloc) for 
  97. those objects that get manipulated alot. The latter is much 
  98. less work.
  99.  
  100.  
  101. LISTMGR.ASM
  102.  
  103. As an added bonus I have included a copy of my linked list 
  104. manager. This is coded for the 386/486 ONLY, and is intended 
  105. as a useful example of how you can use the FarLocal 
  106. routines. You can use these routines under the same license 
  107. as above. I do not intend to rewrite these for use on 
  108. another processor in the near future. So if you need that 
  109. functionality, the source is included so have at it.
  110.  
  111. To assemble LISTMGR.ASM without the debug list dump routines
  112. undefine the appropriate flag. (see source file)
  113.  
  114. Since it makes use of 32 bit registers, this code is fast
  115. as linked list managers go.
  116.  
  117.  
  118. MLTEST
  119.  
  120. MLTEST is a quick and dirty demo of how you can implement
  121. the functions in this package. I make several nasty 
  122. assumptions on the equipment you have. (sorry)
  123.  
  124. In order to see the listmgr dumps you will have to have
  125. a terminal or a PC running a terminal program attached
  126. to the AUX: device. (or use a driver that redirects output
  127. to your monochrome monitor.) You can also see output if
  128. you are using CVW. (it redirects output to AUX)
  129.  
  130. To see the allocations of FarLocal memory you will need
  131. to have a monochrome adaptor and monitor attached.
  132.  
  133. Multiple local heap demo runs as a MDI window app and
  134. all output is to MDI child windows.
  135.  
  136.  
  137. KUDOS
  138.  
  139. Enjoy, Thanks for patronizing me. Oh yes, Windows is a trademark
  140. of Microsoft.
  141.  
  142. Dan
  143.  
  144.  
  145.  
  146. DOCUMENTATION:
  147.  
  148. Multiple Local Heaps:
  149.  
  150.  
  151. The documentation for the following routines is exactly the 
  152. same as is found in the Windows SDK Reference Manual. Except 
  153. for the addition of an hHeap parameter and the following:
  154.  
  155.  
  156. HANDLE MultLocalInit(wInitialSize)
  157.  
  158. This function allocates and initializes a "local" heap from 
  159. the Windows Global memory manager. You must call this 
  160. function prior to  calling any of the Multiple Local Heap 
  161. Routines. The handle returned from this function is used to 
  162. identify each heap and is a necessary parameter to the 
  163. remaining Multiple local heap functions.
  164.  
  165. Heaps will grow/shrink dynamically as need be. Each heap can 
  166. grow to a maximum of 64k bytes.
  167.  
  168.  
  169. Parameter       Type/Description
  170. ------------------------------------------------------------
  171. hInitalSize WORD Specifies the initial size of the heap. 
  172.                 The value must be greater than 256 bytes and 
  173.                 less than 64k bytes.
  174.  
  175. Return Value: The return value identifies the newly 
  176. allocated heap if the function is successful. Otherwise it 
  177. is NULL.
  178.  
  179.  
  180.  
  181. HANDLE SetDStoHeap(hHeap)
  182.  
  183. This function sets the current DS to that of the hHeap. This 
  184. allows use of NEAR pointers for Multiple Local heap objects. 
  185. (see caveats above)
  186.  
  187.  
  188. Parameter       Type/Description
  189. ------------------------------------------------------------
  190. hHeap               HANDLE Identifies the heap.
  191.  
  192. Return Value: The return value is the previous DS selector.
  193.  
  194.  
  195. Usage:              hOldDS = SetDStoHeap(hHeap);
  196.  
  197.                     /* near pointer code */
  198.  
  199.                     SetDStoHeap(hOldDS);
  200.  
  201.  
  202.  
  203.  
  204. With the addition of the hHeap parameter (which is returned 
  205. by MultLocalInit, the documentation to the following 
  206. functions can be found in the Microsoft Windows SDK 
  207. Reference Manual (Volume 1)
  208.  
  209. Function                                             Page
  210. ----------------------------------------------------------
  211. HANDLE MultLocalAlloc(hHeap, wFlags, wBytes)         4-285
  212. WORD MultLocalCompact(hHeap, wBytes)                 4-286
  213. HANDLE MultLocalDiscard(hHeap,hMem)                  4-287
  214. WORD MultLocalFlags(hHeap, hMem)                     4-287
  215. HANDLE MultLocalFree(hHeap, hMem)                    4-288
  216. HANDLE MultLocalHandle(hHeap, lpMem)                 4-288
  217. LPSTR MultLocalLock(hHeap, hMem)                     4-289
  218. HANDLE MultLocalReAlloc(hHeap, hMem, wBytes, wFlags) 4-290
  219. HANDLE MultLocalShrink(hHeap,wSize)                  4-291
  220. WORD MultLocalSize(hHeap, hMem)                      4-292
  221. BOOL MultLocalUnlock(hHeap, hMem)                    4-292
  222.  
  223.  
  224.  
  225. FarLocal Routines:
  226.  
  227. FHANDLE FarLocalAlloc(wFlags, wBytes)
  228.  
  229. This function allocates the number of bytes of memory 
  230. specified by the wBytes parameter from the farlocal heap. 
  231. The memory block can either be fixed or moveable, as 
  232. specified by the wFlags parameter.
  233.  
  234. Parameter           Type/Description
  235. ------------------------------------------------------------
  236. wFlags              WORD See LocalAlloc page 4-285 in the 
  237.                     Microsoft Windows SDK Reference Volume 1.
  238.  
  239. wBytes              WORD Specifies the total number of bytes 
  240.                     to be allocated.
  241.  
  242.  
  243. Return Value: The return value identifies the newly 
  244. allocated farlocal memory block if the function is 
  245. successful. Otherwise it is NULL.
  246.  
  247.  
  248. FHANDLE FarLocalFree(fhMem)
  249.  
  250. This function frees the memory block identified by the fhMem 
  251. parameter and invalidates the handle of the memory block.
  252.  
  253. Parameter           Type/Description
  254. ------------------------------------------------------------
  255. fhMem               FHANDLE Identifies the memory block
  256.  
  257. Return Value: The return value specifies the outcome of the 
  258. function. It is NULL if successful. Otherwise it is equal to 
  259. fhMem.
  260.  
  261.  
  262.  
  263.  
  264. LPSTR FarLocalLock(fhMem)
  265.  
  266. This function locks the farlocal memory block specified by 
  267. the fhMem parameter. The block is locked into memory at the 
  268. given address and its reference count is incremented. Locked 
  269. memory cannot be moved or discarded. The block remains 
  270. locked in memory until its reference count is decremented to 
  271. zero using the FarLocalUnlock function.
  272.  
  273.  
  274. Parameter           Type/Description
  275. ------------------------------------------------------------
  276. fhMem               FHANDLE Identifies the memory block to 
  277.                     be locked.
  278.  
  279. Return Value: The return value points to the first byte of 
  280. memory in the memory block if the function is successful. 
  281. Otherwise it is NULL
  282.  
  283.  
  284. BOOL FarLocalUnlock(fhMem)
  285.  
  286. This function unlocks the farlocal memory block specified by 
  287. the fhMem parameter. The blocks reference count is 
  288. decremented.
  289.  
  290.  
  291. Parameter           Type/Description
  292. ------------------------------------------------------------
  293. fhMem               FHANDLE Identifies the memory block to 
  294.                     be unlocked.
  295.  
  296. Return Value: BOOL The return value is zero if the blocks 
  297. reference count was decreased to zero. Otherwise it is 
  298. nonzero.
  299.  
  300.  
  301.  
  302.