ReactOS  0.4.14-dev-1115-gebeeb9d
baseheap.h
Go to the documentation of this file.
1 /*
2  * PROJECT: ReactOS Win32 Base API
3  * LICENSE: GPL - See COPYING in the top level directory
4  * FILE: dll/win32/kernel32/include/baseheap.h
5  * PURPOSE: Base Heap Structures
6  * PROGRAMMERS: Alex Ionescu (alex.ionescu@reactos.org)
7  */
8 
9 //
10 // Some important implementation notes.
11 //
12 // Firstly, the Global* APIs in Win32 are largely similar to the Local* APIs,
13 // but there are a number of small differences (for example, there is no such
14 // thing as DDE/Shared Local memory, and the re-allocation semantics are also
15 // simpler, because you cannot force a move).
16 //
17 // Note something VERY IMPORTANT: This implementation *depends* on the fact
18 // that all heap pointers are, at the very least, 8 byte aligned, and that heap
19 // handles are actually pointers inside our HandleEntry->Object, which happens
20 // to be at offset 0x4, which means testing with bit 3 tells us if the handle
21 // is a pointer or a real "handle". On 64-bit, heap pointers should be 16-byte
22 // aligned, and our offset should be 0x8, so the trick works anyways, but using
23 // the 4th bit.
24 //
25 // Apart from MSDN, a wonderful source of information about how this works is
26 // available on Raymond's blog, in a 4-parter series starting at:
27 // http://blogs.msdn.com/oldnewthing/archive/2004/11/04/252258.aspx.
28 //
29 // Finally, as Raymond points out, be aware that some applications depend on
30 // the way this implementation was done, since global memory handles are a
31 // straight-forward overlay on top of the RTL Handle implementation, and rogue
32 // applications can easily do the conversion manually without calling the right
33 // API for it (such as GlobalLock).
34 //
35 
36 // Tracing Support
37 // Define _BASE_HANDLE_TRACE for Traces
38 //
39 #ifdef _BASE_HANDLE_TRACE_
40 #define BH_PRINT DbgPrint
41 #else
42 #define BH_PRINT DPRINT
43 #endif
44 #define BASE_TRACE_ALLOC(x, y) \
45  BH_PRINT("[BASE_HEAP] %s : Allocating %lx bytes with flags: %lx\n", \
46  __FUNCTION__, x, y)
47 #define BASE_TRACE_ALLOC2(x) \
48  BH_PRINT("[BASE_HEAP] %s : Allocated %p\n", \
49  __FUNCTION__, x)
50 #define BASE_TRACE_PTR(x, y) \
51  BH_PRINT("[BASE_HEAP] %s : Using handle: %p for pointer: %p\n", \
52  __FUNCTION__, x, y)
53 #define BASE_TRACE_HANDLE(x, y) \
54  BH_PRINT("[BASE_HEAP] %s : Using handle: %lx for block: %p\n", \
55  __FUNCTION__, x, y)
56 #define BASE_TRACE_DEALLOC(x) \
57  BH_PRINT("[BASE_HEAP] %s : Freeing %p\n", \
58  __FUNCTION__, x)
59 #define BASE_TRACE_FAILURE() \
60  BH_PRINT("[BASE_HEAP] %s : Failing %d\n", \
61  __FUNCTION__, __LINE__)
62 
63 //
64 // The handle structure for global heap handles.
65 // Notice that it nicely overlays with RTL_HANDLE_ENTRY.
66 // KEEP IT THAT WAY! ;-)
67 //
69 {
72  union
73  {
76  };
78 
79 //
80 // Handle entry flags
81 // Note that 0x0001 is the shared/generic RTL_HANDLE_VALID
82 //
83 #define BASE_HEAP_ENTRY_FLAG_MOVABLE 0x0002
84 #define BASE_HEAP_ENTRY_FLAG_REUSABLE 0x0004
85 #define BASE_HEAP_ENTRY_FLAG_REUSE 0x0008
86 #define BASE_HEAP_ENTRY_FLAG_DDESHARE 0x0010
87 
88 //
89 // Easy way to check if the global handle is actually an entry in our table
90 //
91 #define BASE_HEAP_IS_HANDLE_ENTRY \
92  (ULONG_PTR)FIELD_OFFSET(BASE_HEAP_HANDLE_ENTRY, Object)
93 
94 //
95 // Tags for the entire heap allocation for this global memory.
96 // They are set part of the User Flags of the RTL Heap.
97 //
98 #define BASE_HEAP_FLAG_MOVABLE HEAP_SETTABLE_USER_FLAG1
99 #define BASE_HEAP_FLAG_DDESHARE HEAP_SETTABLE_USER_FLAG2
100 
101 //
102 // Internal Handle Functions
103 //
104 #define BaseHeapAllocEntry() \
105  (PBASE_HEAP_HANDLE_ENTRY)RtlAllocateHandle(&BaseHeapHandleTable, NULL)
106 
107 #define BaseHeapGetEntry(h) \
108  (PBASE_HEAP_HANDLE_ENTRY) \
109  CONTAINING_RECORD(h, \
110  BASE_HEAP_HANDLE_ENTRY, \
111  Object);
112 
113 #define BaseHeapValidateEntry(he) \
114  RtlIsValidHandle(&BaseHeapHandleTable, (PRTL_HANDLE_TABLE_ENTRY)he)
115 
116 #define BaseHeapFreeEntry(he) \
117  RtlFreeHandle(&BaseHeapHandleTable, (PRTL_HANDLE_TABLE_ENTRY)he);
118 
ULONG OldSize
Definition: baseheap.h:75
Definition: baseheap.h:68
struct _BASE_HEAP_HANDLE_ENTRY * PBASE_HEAP_HANDLE_ENTRY
PVOID Object
Definition: baseheap.h:74
unsigned short USHORT
Definition: pedump.c:61
unsigned int ULONG
Definition: retypes.h:1
USHORT LockCount
Definition: baseheap.h:71
struct _BASE_HEAP_HANDLE_ENTRY BASE_HEAP_HANDLE_ENTRY
USHORT Flags
Definition: baseheap.h:70