en:docs:win16:modules:local_heap

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
en:docs:win16:modules:local_heap [2026/02/24 07:36] – prokusheven:docs:win16:modules:local_heap [2026/02/24 08:12] (current) – [References] prokushev
Line 1: Line 1:
-===== Win16 Local Heap Functions =====+===== Local Heap and Atom Table =====
  
 ===== Overview ===== ===== Overview =====
Line 23: Line 23:
  
 **Important Notes:** **Important Notes:**
-* The field at offset 6 (pLocalHeap) is the primary way to locate the local heap structures given only the DGROUP selector. + 
-* When LocalInit() is called on a globally allocated block (non‑DGROUP), the WORD at offset 6 of that block is also set to point to the local heap information structure for that block. +  * The field at offset 6 (pLocalHeap) is the primary way to locate the local heap structures given only the DGROUP selector. 
-* Similarly, if InitAtomTable() is called on a global block, offset 8 points to the atom table, and offset 6 will point to the associated local heap (since atoms are stored in the local heap).+  * When LocalInit() is called on a globally allocated block (non‑DGROUP), the WORD at offset 6 of that block is also set to point to the local heap information structure for that block. 
 +  * Similarly, if InitAtomTable() is called on a global block, offset 8 points to the atom table, and offset 6 will point to the associated local heap (since atoms are stored in the local heap).
  
 ==== HeapInfo and LocalInfo ==== ==== HeapInfo and LocalInfo ====
Line 97: Line 98:
 Every block in the local heap is preceded by an arena (header) that contains management information. Arenas always start on a 4‑byte boundary, so the two low bits of every arena address are zero. These bits are reused as flags in the la_prev field of each arena. The two low bits of la_prev have the following meaning: Every block in the local heap is preceded by an arena (header) that contains management information. Arenas always start on a 4‑byte boundary, so the two low bits of every arena address are zero. These bits are reused as flags in the la_prev field of each arena. The two low bits of la_prev have the following meaning:
  
-* Bit 0 (least significant): Set if the block is in use (FIXED or MOVEABLE); cleared if the block is free. +  * Bit 0 (least significant): Set if the block is in use (FIXED or MOVEABLE); cleared if the block is free. 
-* Bit 1: Set if the block is MOVEABLE; cleared if the block is FIXED (only meaningful when bit 0 is set).+  * Bit 1: Set if the block is MOVEABLE; cleared if the block is FIXED (only meaningful when bit 0 is set).
  
 Thus, to obtain the real address of the previous arena, the two low bits must be masked off. Thus, to obtain the real address of the previous arena, the two low bits must be masked off.
Line 148: Line 149:
 ===== Heap Operations ===== ===== Heap Operations =====
  
-* **Allocation (LocalAlloc)** walks the free list, splitting blocks if necessary, and sets up the appropriate arena. For MOVEABLE blocks, it also allocates a handle table entry. +  * **Allocation (LocalAlloc)** walks the free list, splitting blocks if necessary, and sets up the appropriate arena. For MOVEABLE blocks, it also allocates a handle table entry. 
-* **Compaction (LocalCompact)** coalesces adjacent free blocks and may move or discard unlocked MOVEABLE blocks. When a block is moved, its lhe_address is updated. +  * **Compaction (LocalCompact)** coalesces adjacent free blocks and may move or discard unlocked MOVEABLE blocks. When a block is moved, its lhe_address is updated. 
-* **Locking (LocalLock/LocalUnlock)** manipulates the lhe_count field of the handle entry for MOVEABLE blocks; for FIXED blocks, no count is maintained. +  * **Locking (LocalLock/LocalUnlock)** manipulates the lhe_count field of the handle entry for MOVEABLE blocks; for FIXED blocks, no count is maintained. 
-* **Discarding (LocalDiscard)** frees the memory of a MOVEABLE block but keeps the handle entry alive with the LHE_DISCARDED flag set.+  * **Discarding (LocalDiscard)** frees the memory of a MOVEABLE block but keeps the handle entry alive with the LHE_DISCARDED flag set.
  
 ===== Atom Tables ===== ===== Atom Tables =====
Line 181: Line 182:
 String atoms are created by passing an ordinary string to `AddAtom` or `GlobalAddAtom`. They are stored in the atom table as `ATOMENTRY` structures. String atoms are created by passing an ordinary string to `AddAtom` or `GlobalAddAtom`. They are stored in the atom table as `ATOMENTRY` structures.
  
-* **Range**: `0xC000` to `0xFFFF` (encoded pointer). +  * **Range**: `0xC000` to `0xFFFF` (encoded pointer). 
-* **Storage**: Allocated in the local heap as `ATOMENTRY`, inserted into the hash table. +  * **Storage**: Allocated in the local heap as `ATOMENTRY`, inserted into the hash table. 
-* **Reference count**: Yes (`usage` field). +  * **Reference count**: Yes (`usage` field). 
-* **String representation**: The original string. +  * **String representation**: The original string. 
-* **Creation**: `AddAtom("MyString")`.+  * **Creation**: `AddAtom("MyString")`.
  
 **Encoding:** A string atom value is derived from the near pointer to its `ATOMENTRY`. Since the pointer is 4‑byte aligned, the low two bits are zero. The atom is formed by shifting the pointer right by 2 bits and ORing with `0xC000`. This guarantees the range `0xC000–0xFFFF`. **Encoding:** A string atom value is derived from the near pointer to its `ATOMENTRY`. Since the pointer is 4‑byte aligned, the low two bits are zero. The atom is formed by shifting the pointer right by 2 bits and ORing with `0xC000`. This guarantees the range `0xC000–0xFFFF`.
Line 198: Line 199:
 Integer atoms are created by passing a string of the form `"#dddd"` (or by using `MAKEINTATOM` with a value ≤ 0xBFFF). They are **not stored in the atom table** and have no associated `ATOMENTRY` structure. Integer atoms are created by passing a string of the form `"#dddd"` (or by using `MAKEINTATOM` with a value ≤ 0xBFFF). They are **not stored in the atom table** and have no associated `ATOMENTRY` structure.
  
-* **Range**: `0x0001` to `0xBFFF` . +  * **Range**: `0x0001` to `0xBFFF` . 
-* **Storage**: None; the value is used directly as the atom. +  * **Storage**: None; the value is used directly as the atom. 
-* **Reference count**: Not applicable. +  * **Reference count**: Not applicable. 
-* **String representation**: Generated on the fly as `"#dddd"` when `GetAtomName` is called. +  * **String representation**: Generated on the fly as `"#dddd"` when `GetAtomName` is called. 
-* **Creation**: `AddAtom("#1234")` or `AddAtom(MAKEINTATOM(0x04D2))`.+  * **Creation**: `AddAtom("#1234")` or `AddAtom(MAKEINTATOM(0x04D2))`.
  
 **How it works:** When a string of the form '#dddd' is passed, the function parses the decimal number and, if it is less than 0xC000, returns it directly without accessing the atom table. Similarly, `FindAtom` for such a string or for a `MAKEINTATOM` value simply returns the number without any lookup. Integer atoms are always considered "found" because any value in the range is valid. **How it works:** When a string of the form '#dddd' is passed, the function parses the decimal number and, if it is less than 0xC000, returns it directly without accessing the atom table. Similarly, `FindAtom` for such a string or for a `MAKEINTATOM` value simply returns the number without any lookup. Integer atoms are always considered "found" because any value in the range is valid.
Line 216: Line 217:
 This macro casts a 16‑bit integer value to a pointer type. When this "pointer" is passed to atom functions, it is interpreted as an integer atom (if the value is ≤ `0xBFFF`) or as a string atom (if ≥ `0xC000`). This macro casts a 16‑bit integer value to a pointer type. When this "pointer" is passed to atom functions, it is interpreted as an integer atom (if the value is ≤ `0xBFFF`) or as a string atom (if ≥ `0xC000`).
  
-* For values ≤ `0xBFFF`, the function treats it as an integer atom and returns the value directly. +  * For values ≤ `0xBFFF`, the function treats it as an integer atom and returns the value directly. 
-* For values ≥ `0xC000`, the function assumes it is an encoded pointer to an `ATOMENTRY` and will dereference it (after shifting left by 2 bits) to access the atom entry.+  * For values ≥ `0xC000`, the function assumes it is an encoded pointer to an `ATOMENTRY` and will dereference it (after shifting left by 2 bits) to access the atom entry.
  
 **Important:** `MAKEINTATOM` does not create a string or allocate any memory; it is simply a type-punning convenience to pass integer atoms to functions that formally expect a string pointer. **Important:** `MAKEINTATOM` does not create a string or allocate any memory; it is simply a type-punning convenience to pass integer atoms to functions that formally expect a string pointer.
Line 223: Line 224:
 ==== Local vs. Global Atom Tables ==== ==== Local vs. Global Atom Tables ====
  
-* **Local atom tables**: Bound to a specific data segment (e.g., an application's DGROUP). Created by calling `InitAtomTable()`. Used for a module's internal needs. Access is only possible when the DS register points to that segment. +  * **Local atom tables**: Bound to a specific data segment (e.g., an application's DGROUP). Created by calling `InitAtomTable()`. Used for a module's internal needs. Access is only possible when the DS register points to that segment. 
-* **Global atom table**: A system-wide table accessible to all applications via `GlobalAddAtom`, `GlobalFindAtom`, and `GlobalDeleteAtom` . Physically, it resides not in an application's data segment but in a special USER data segment (part of the so-called "global atom and text heap") . Its structure is identical to a local atom table. The `Global...` functions internally switch DS to the USER segment and call the ordinary `AddAtom`/`FindAtom`.+  * **Global atom table**: A system-wide table accessible to all applications via `GlobalAddAtom`, `GlobalFindAtom`, and `GlobalDeleteAtom` . Physically, it resides not in an application's data segment but in a special USER data segment (part of the so-called "global atom and text heap") . Its structure is identical to a local atom table. The `Global...` functions internally switch DS to the USER segment and call the ordinary `AddAtom`/`FindAtom`.
  
 ==== Creating Custom Atom Tables (outside DGROUP) ==== ==== Creating Custom Atom Tables (outside DGROUP) ====
Line 230: Line 231:
 Since all atom operations work with the current segment pointed to by DS, you can create and use an atom table in any arbitrary data segment by following three steps: Since all atom operations work with the current segment pointed to by DS, you can create and use an atom table in any arbitrary data segment by following three steps:
  
-1. **Create a local heap** in the target segment using `LocalInit(Selector, Start, End)`. +  -  **Create a local heap** in the target segment using `LocalInit(Selector, Start, End)`. 
-2. **Switch the DS register** to that segment. +  - **Switch the DS register** to that segment. 
-3. Call `InitAtomTable(size)` to initialize the atom table in the newly created heap.+  - Call `InitAtomTable(size)` to initialize the atom table in the newly created heap.
  
 After that, any subsequent call to `AddAtom`, `FindAtom`, etc., will operate on the custom table if DS is temporarily set to the correct segment. After that, any subsequent call to `AddAtom`, `FindAtom`, etc., will operate on the custom table if DS is temporarily set to the correct segment.
Line 260: Line 261:
 </code> </code>
  
-* `wSegment` – Selector of the segment where the heap will be created. +  * `wSegment` – Selector of the segment where the heap will be created. 
-* `pStart` – Offset of the first byte of the heap area (must be paragraph‑aligned, i.e., a multiple of 16). +  * `pStart` – Offset of the first byte of the heap area (must be paragraph‑aligned, i.e., a multiple of 16). 
-* `pEnd` – Offset of the last byte of the heap area (inclusive). The heap will manage memory from `pStart` to `pEnd`.+  * `pEnd` – Offset of the last byte of the heap area (inclusive). The heap will manage memory from `pStart` to `pEnd`.
  
 If successful, `LocalInit()` returns a non‑zero value. It sets up the `HeapInfo` and `LocalInfo` structures at the beginning of the heap area (starting at `pStart`) and updates the segment’s instance data at offset **06h** (`pLocalHeap`) to point to that `HeapInfo` structure. However, if the segment is not a default data segment (i.e., not DGROUP), the instance data at offset 0 must also contain a zero word to indicate that the NULL segment structure is present; otherwise, the heap may not be recognized by some routines. If successful, `LocalInit()` returns a non‑zero value. It sets up the `HeapInfo` and `LocalInfo` structures at the beginning of the heap area (starting at `pStart`) and updates the segment’s instance data at offset **06h** (`pLocalHeap`) to point to that `HeapInfo` structure. However, if the segment is not a default data segment (i.e., not DGROUP), the instance data at offset 0 must also contain a zero word to indicate that the NULL segment structure is present; otherwise, the heap may not be recognized by some routines.
Line 305: Line 306:
  
 **Important Considerations:** **Important Considerations:**
-* The heap structures themselves occupy space at the beginning of the heap area. The first block (sentinel) resides at `pStart + size of (LocalInfo)`. + 
-* The segment’s instance data (at offset 0) must be properly set up, especially the zero word at offset 0, to avoid confusion with other structures. +  * The heap structures themselves occupy space at the beginning of the heap area. The first block (sentinel) resides at `pStart + size of (LocalInfo)`. 
-* Custom local heaps are not automatically enlarged if they run out of space; they are limited to the range specified in `LocalInit`. +  * The segment’s instance data (at offset 0) must be properly set up, especially the zero word at offset 0, to avoid confusion with other structures. 
-* The `HEAPSIZE` setting in the module’s .DEF file only affects the default DGROUP heap.+  * Custom local heaps are not automatically enlarged if they run out of space; they are limited to the range specified in `LocalInit`. 
 +  * The `HEAPSIZE` setting in the module’s .DEF file only affects the default DGROUP heap.
  
 ==== Creating Atom Tables Outside DGROUP ==== ==== Creating Atom Tables Outside DGROUP ====
Line 316: Line 318:
 ==== Summary of Custom Heap and Atom Table Creation ==== ==== Summary of Custom Heap and Atom Table Creation ====
  
-* Use `LocalInit` on a segment to establish a local heap anywhere in memory. +  * Use `LocalInit` on a segment to establish a local heap anywhere in memory. 
-* The segment must have a valid NULL segment structure (zero word at offset 0) for the heap to be recognized. +  * The segment must have a valid NULL segment structure (zero word at offset 0) for the heap to be recognized. 
-* After `LocalInit`, you can use `LocalAlloc`, `LocalLock`, etc., with near pointers within that segment. +  * After `LocalInit`, you can use `LocalAlloc`, `LocalLock`, etc., with near pointers within that segment. 
-* To create an atom table in a custom heap, switch DS to that segment and call `InitAtomTable`. +  * To create an atom table in a custom heap, switch DS to that segment and call `InitAtomTable`. 
-* All subsequent atom operations must be performed with DS set appropriately (or via wrapper functions). +  * All subsequent atom operations must be performed with DS set appropriately (or via wrapper functions). 
-* Custom heaps and atom tables are useful for isolating memory pools, implementing resource managers, or working with large data structures without polluting the default DGROUP.+  * Custom heaps and atom tables are useful for isolating memory pools, implementing resource managers, or working with large data structures without polluting the default DGROUP.
  
 ===== References ===== ===== References =====
  
-1. Schulman, A., Maxey, D., Pietrek, M. //Undocumented Windows//. Addison-Wesley, 1992. +  - Schulman, A., Maxey, D., Pietrek, M. //Undocumented Windows//. Addison-Wesley, 1992. 
-2. Pietrek, M. //Windows Internals//. Addison-Wesley, 1993. +  - Pietrek, M. //Windows Internals//. Addison-Wesley, 1993. 
-3. Chen, R. //The Old New Thing// (blog). Microsoft Developer Blogs. +  - Chen, R. //The Old New Thing// (blog). Microsoft Developer Blogs. 
-4. Microsoft OS/2 Version 1.1 Programmer's Reference, Volume 1.+  - Microsoft OS/2 Version 1.1 Programmer's Reference, Volume 1.