CWin32Heap Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CWin32Heap Class.
This class implements IAtlMemMgr using the Win32 heap allocation functions.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
class CWin32Heap : public IAtlMemMgr
Members
Public Constructors
| Name | Description |
|---|---|
| CWin32Heap::CWin32Heap | The constructor. |
| CWin32Heap::~CWin32Heap | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CWin32Heap::Allocate | Allocates a block of memory from the heap object. |
| CWin32Heap::Attach | Attaches the heap object to an existing heap. |
| CWin32Heap::Detach | Detaches the heap object from an existing heap. |
| CWin32Heap::Free | Frees memory previously allocated from the heap. |
| CWin32Heap::GetSize | Returns the size of a memory block allocated from the heap object. |
| CWin32Heap::Reallocate | Reallocates a block of memory from the heap object. |
Public Data Members
| Name | Description |
|---|---|
| CWin32Heap::m_bOwnHeap | A flag used to determine current ownership of the heap handle. |
| CWin32Heap::m_hHeap | Handle to the heap object. |
Remarks
CWin32Heap implements memory allocation methods using the Win32 heap allocation functions, including HeapAlloc and HeapFree. Unlike other Heap classes, CWin32Heap requires a valid heap handle to be provided before memory is allocated: the other classes default to using the process heap. The handle can be supplied to the constructor or to the CWin32Heap::Attach method. See the CWin32Heap::CWin32Heap method for more details.
Example
See the example for IAtlMemMgr.
Inheritance Hierarchy
IAtlMemMgr
CWin32Heap
Requirements
Header: atlmem.h
CWin32Heap::Allocate
Allocates a block of memory from the heap object.
virtual __declspec(allocator) void* Allocate(size_t nBytes) throw();
Parameters
nBytes
The requested number of bytes in the new memory block.
Return Value
Returns a pointer to the newly allocated memory block.
Remarks
Call CWin32Heap::Free or CWin32Heap::Reallocate to free the memory allocated by this method.
Implemented using HeapAlloc.
CWin32Heap::Attach
Attaches the heap object to an existing heap.
void Attach(HANDLE hHeap, bool bTakeOwnership) throw();
Parameters
hHeap
An existing heap handle.
bTakeOwnership
A flag indicating if the CWin32Heap object is to take ownership over the resources of the heap.
Remarks
If bTakeOwnership is TRUE, the CWin32Heap object is responsible for deleting the heap handle.
CWin32Heap::CWin32Heap
The constructor.
CWin32Heap() throw();
CWin32Heap( HANDLE hHeap) throw();
CWin32Heap(
DWORD dwFlags,
size_t nInitialSize,
size_t nMaxSize = 0);
Parameters
hHeap
An existing heap object.
dwFlags
Flags used in creating the heap.
nInitialSize
The initial size of the heap.
nMaxSize
The maximum size of the heap.
Remarks
Before allocating memory, it is necessary to provide the CWin32Heap object with a valid heap handle. The simplest way to achieve this is to use the process heap:
CWin32Heap MyHeap(GetProcessHeap());
It is also possible to supply an existing heap handle to the constructor, in which case the new object does not take over ownership of the heap. The original heap handle will still be valid when the CWin32Heap object is deleted.
An existing heap can also be attached to the new object, using CWin32Heap::Attach.
If a heap is required where operations are all performed from a single thread, the best way is to create the object as follows:
CWin32Heap MyHeap(HEAP_NO_SERIALIZE, SomeInitialSize);
The parameter HEAP_NO_SERIALIZE specifies that mutual exclusion will not be used when the heap functions allocate and free memory, with an according increase in performance.
The third parameter defaults to 0, which allows the heap to grow as required. See HeapCreate for an explanation of the memory sizes and flags.
CWin32Heap::~CWin32Heap
The destructor.
~CWin32Heap() throw();
Remarks
Destroys the heap handle if the CWin32Heap object has ownership of the heap.
CWin32Heap::Detach
Detaches the heap object from an existing heap.
HANDLE Detach() throw();
Return Value
Returns the handle to the heap to which the object was previously attached.
CWin32Heap::Free
Frees memory previously allocated from the heap by CWin32Heap::Allocate or CWin32Heap::Reallocate.
virtual void Free(void* p) throw();
Parameters
p
Pointer to the block of memory to free. NULL is a valid value and does nothing.
CWin32Heap::GetSize
Returns the size of a memory block allocated from the heap object.
virtual size_t GetSize(void* p) throw();
Parameters
p
Pointer to the memory block whose size the method will obtain. This is a pointer returned by CWin32Heap::Allocate or CWin32Heap::Reallocate.
Return Value
Returns the size, in bytes, of the allocated memory block.
CWin32Heap::m_bOwnHeap
A flag used to determine current ownership of the heap handle stored in m_hHeap.
bool m_bOwnHeap;
CWin32Heap::m_hHeap
Handle to the heap object.
HANDLE m_hHeap;
Remarks
A variable used to store a handle to the heap object.
CWin32Heap::Reallocate
Reallocates a block of memory from the heap object.
virtual __declspec(allocator) void* Reallocate(void* p, size_t nBytes) throw();
Parameters
p
Pointer to the block of memory to reallocate.
nBytes
The new size in bytes of the allocated block. The block can be made larger or smaller.
Return Value
Returns a pointer to the newly allocated memory block.
Remarks
If p is NULL, it's assumed that the memory block has not yet been allocated and CWin32Heap::Allocate is called, with an argument of nBytes.
See Also
Class Overview
IAtlMemMgr Class
CLocalHeap Class
CGlobalHeap Class
CCRTHeap Class
CComHeap Class