Code Demonstrates Multiple Instance DLL

ID: Q81335

The information in this article applies to:

Microsoft Windows Software Development Kit (SDK) versions 3.0, 3.1

SUMMARY

A dynamic-link library (DLL) in the Windows environment has a single data segment that is used by each task (application instance) that links to the DLL. However, there are many situations in which a DLL must maintain data for each individual task. This article discusses the method used by the MULTINST sample application to create a multiple instance DLL. The DLL creates a separate data segment for each task that links to it.

MORE INFORMATION

The following files are available for download from the Microsoft Download Center. Click the file names below to download the files:

Multinst.exe

For more information about how to download files from the Microsoft Download Center, please visit the Download Center at the following Web address

http://www.microsoft.com/downloads/search.asp

and then click How to use the Microsoft Download Center.

Because each task in the system has a separate stack segment, the value of the stack segment can be used as a unique identifier. MULTINST stores data for each task in a block of memory obtained using GlobalAlloc(). Each time a task calls the DLL, use the value of its stack segment as an index into the table of selectors for the global memory blocks. Load the corresponding selector into the DS register. After this is done, all static data and the local heap correspond to the calling task.

When a new task calls into the DLL for the first time, the DLL allocates a new block of memory to hold data for the task. It copies initial values for static variables into the data block, and initializes a local heap.

When a task that uses the DLL shuts down, it calls the UnregisterTask() function in the DLL, which frees the data block associated with the task and removes the task from the DLL's task list. Failing to call UnregisterTask() might cause serious problems because Windows could reassign a stack segment value to a new task. If this task called the DLL, it would receive the data values associated with the previous task, which might be completely inappropriate.

Place the following six lines of code at the beginning of each function exported by the DLL to load the correct data segment:


   if ((wDS = LoadInstanceData()) == 0) // Get DS for this instance
      return;                           // If DS==0 then out of memory

   _asm {
        mov     ax,wDS
        mov     DS,ax
        }

The following text describes each function in the MULTINST DLL:


AddTask(): Allocate data for the task, initialize the data, and add the
           task to the task list.

FillHeap(): Allocate memory in the local heap until LocalAlloc fails.
            Used to demonstrate that the local heap will grow.

InitInstanceData(): Save initial values of static variables and
                    initialize the task list.

LibMain(): Save the initial values of static variables and the initial
           size of the data segment and the heap.

LoadInstanceData(): Retrieve the segment address (selector) to the data
                    for the task that called the DLL.

LookUpTask(): Given the value of the stack segment for the task, look up
              the segment address (selector) for the data for the task.
              If the task is not in the list, this function returns zero.

StoreData(): Save a string in the local heap.

WEP(): Required by a DLL.

Additional query words: softlib MULTINST.EXE

Keywords : kbfile kbsample kb16bitonly kbWinOS310 kbWinOS300
Version : WINDOWS:3.0,3.1
Platform : WINDOWS
Issue type :