Legal Stuff...


SOFTWARE LICENSE

You can use the routines in MLOCAL.ZIP royalty free if you 
pay me $59.95. If you don't pay me, you can't use them.

"Use" means as you would "use" any other Copyrighted 
software of this nature.

If there is a bug or any other problem with the routines 
contained in MLOCAL.ZIP, and it damages you legally (or 
otherwise) in any way its your problem not mine. You get 
the source so you are liable!

If you find a bug let me know about it and I'll fix it and 
upload a new version.

 
Send to:  Dan Quigley
		  17219 NE 32nd Street
		  Redmond, WA 98052 
		  USA

For support or bug reports call:  (206) 885-9694


Fun Stuff...


MULTIPLE LOCAL HEAPS

The routines in MLOCAL.ZIP work on the principle that 
Windows local heap management routines use the current 
selector or (real mode segment) in the DS register, as the 
"base" segment for its objects. You will note that most all 
the routines change the DS register just prior to the 
"normal" LocalXXXX call.

The only difference these routines have from their Windows 
KERNEL counterparts is that they use sizeof(DWORD) handles 
and the MultLocalLock() routine returns a far pointer. You 
can expect the same behavior normally associated with the 
Windows functions.

Applications that use MDI will find these routines 
especially useful as they allow a separate "local" heap for 
each MDI child. I have included an example of how this can 
be done (see MLTEST.C).

For those of you that want optimal performance, You can use 
the function SetDStoHeap(). This functions does just what 
its name implies. There are several caveats to using this:

   1) Since you have changed your DS, you no longer have 
access  to any global variables. (you can make far pointers 
to the variables you need access to and pass them into your 
function)

   2) While your DS is changed, the same rules apply to DLLs 
DS!=SS. So don't expect the C runtime functions that assume 
this to work. (see the SDK docs).

   3) You will have to make you own NEAR pointers. DO NOT 
expect the C compiler to do this for you. You will GP fault 
at best.


FARLOCAL MEMORY

Included with the Multiple Local Heap routines are several 
"FarLocal" that make use of some of the Multiple heap 
routines. These hybrid functions allow applications to 
allocate memory in the "spirit" of C runtime.

Each global allocation (using GlobalAlloc) you make in 
Windows pmode, allocates at least one selector. The 
80286/386/486 processors limit the size of descriptor 
table(s) to 64k, thus allowing 8k selectors. (in enhanced 
mode, all windows apps (including drivers) run in a single 
pmode VM). This can be a "limitation" to some application's 
memory schemes, that use GlobalAlloc as its main source of 
memory and make hundreds of allocations.

These FarLocal routines allow you to allocate as many 
protect mode "global" objects as memory allows. As usual, 
you can't get something for nothing, so the limitation of 
FarLocal memory is that each memory object must be less than 
64k.

FarLocal routines use a VERY simple memory management 
paradigm.  It is not the most efficient if your application 
manipulates memory objects frequently. My suggestion if you 
need this ability, is either re-write the FarLocal memory 
manager or use standard global memory (GlobalAlloc) for 
those objects that get manipulated alot. The latter is much 
less work.


LISTMGR.ASM

As an added bonus I have included a copy of my linked list 
manager. This is coded for the 386/486 ONLY, and is intended 
as a useful example of how you can use the FarLocal 
routines. You can use these routines under the same license 
as above. I do not intend to rewrite these for use on 
another processor in the near future. So if you need that 
functionality, the source is included so have at it.

To assemble LISTMGR.ASM without the debug list dump routines
undefine the appropriate flag. (see source file)

Since it makes use of 32 bit registers, this code is fast
as linked list managers go.


MLTEST

MLTEST is a quick and dirty demo of how you can implement
the functions in this package. I make several nasty 
assumptions on the equipment you have. (sorry)

In order to see the listmgr dumps you will have to have
a terminal or a PC running a terminal program attached
to the AUX: device. (or use a driver that redirects output
to your monochrome monitor.) You can also see output if
you are using CVW. (it redirects output to AUX)

To see the allocations of FarLocal memory you will need
to have a monochrome adaptor and monitor attached.

Multiple local heap demo runs as a MDI window app and
all output is to MDI child windows.


KUDOS

Enjoy, Thanks for patronizing me. Oh yes, Windows is a trademark
of Microsoft.

Dan



DOCUMENTATION:

Multiple Local Heaps:


The documentation for the following routines is exactly the 
same as is found in the Windows SDK Reference Manual. Except 
for the addition of an hHeap parameter and the following:


HANDLE MultLocalInit(wInitialSize)

This function allocates and initializes a "local" heap from 
the Windows Global memory manager. You must call this 
function prior to  calling any of the Multiple Local Heap 
Routines. The handle returned from this function is used to 
identify each heap and is a necessary parameter to the 
remaining Multiple local heap functions.

Heaps will grow/shrink dynamically as need be. Each heap can 
grow to a maximum of 64k bytes.


Parameter       Type/Description
------------------------------------------------------------
hInitalSize WORD Specifies the initial size of the heap. 
				The value must be greater than 256 bytes and 
				less than 64k bytes.

Return Value: The return value identifies the newly 
allocated heap if the function is successful. Otherwise it 
is NULL.



HANDLE SetDStoHeap(hHeap)

This function sets the current DS to that of the hHeap. This 
allows use of NEAR pointers for Multiple Local heap objects. 
(see caveats above)


Parameter       Type/Description
------------------------------------------------------------
hHeap               HANDLE Identifies the heap.

Return Value: The return value is the previous DS selector.


Usage:              hOldDS = SetDStoHeap(hHeap);

					/* near pointer code */

					SetDStoHeap(hOldDS);




With the addition of the hHeap parameter (which is returned 
by MultLocalInit, the documentation to the following 
functions can be found in the Microsoft Windows SDK 
Reference Manual (Volume 1)

Function                                             Page
----------------------------------------------------------
HANDLE MultLocalAlloc(hHeap, wFlags, wBytes)         4-285
WORD MultLocalCompact(hHeap, wBytes)                 4-286
HANDLE MultLocalDiscard(hHeap,hMem)                  4-287
WORD MultLocalFlags(hHeap, hMem)                     4-287
HANDLE MultLocalFree(hHeap, hMem)                    4-288
HANDLE MultLocalHandle(hHeap, lpMem)                 4-288
LPSTR MultLocalLock(hHeap, hMem)                     4-289
HANDLE MultLocalReAlloc(hHeap, hMem, wBytes, wFlags) 4-290
HANDLE MultLocalShrink(hHeap,wSize)                  4-291
WORD MultLocalSize(hHeap, hMem)                      4-292
BOOL MultLocalUnlock(hHeap, hMem)                    4-292



FarLocal Routines:

FHANDLE FarLocalAlloc(wFlags, wBytes)

This function allocates the number of bytes of memory 
specified by the wBytes parameter from the farlocal heap. 
The memory block can either be fixed or moveable, as 
specified by the wFlags parameter.

Parameter           Type/Description
------------------------------------------------------------
wFlags              WORD See LocalAlloc page 4-285 in the 
					Microsoft Windows SDK Reference Volume 1.

wBytes              WORD Specifies the total number of bytes 
					to be allocated.


Return Value: The return value identifies the newly 
allocated farlocal memory block if the function is 
successful. Otherwise it is NULL.


FHANDLE FarLocalFree(fhMem)

This function frees the memory block identified by the fhMem 
parameter and invalidates the handle of the memory block.

Parameter           Type/Description
------------------------------------------------------------
fhMem               FHANDLE Identifies the memory block

Return Value: The return value specifies the outcome of the 
function. It is NULL if successful. Otherwise it is equal to 
fhMem.




LPSTR FarLocalLock(fhMem)

This function locks the farlocal memory block specified by 
the fhMem parameter. The block is locked into memory at the 
given address and its reference count is incremented. Locked 
memory cannot be moved or discarded. The block remains 
locked in memory until its reference count is decremented to 
zero using the FarLocalUnlock function.


Parameter           Type/Description
------------------------------------------------------------
fhMem               FHANDLE Identifies the memory block to 
					be locked.

Return Value: The return value points to the first byte of 
memory in the memory block if the function is successful. 
Otherwise it is NULL


BOOL FarLocalUnlock(fhMem)

This function unlocks the farlocal memory block specified by 
the fhMem parameter. The blocks reference count is 
decremented.


Parameter           Type/Description
------------------------------------------------------------
fhMem               FHANDLE Identifies the memory block to 
					be unlocked.

Return Value: BOOL The return value is zero if the blocks 
reference count was decreased to zero. Otherwise it is 
nonzero.



