description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CWin32Heap Class |
CWin32Heap Class |
11/04/2016 |
|
|
69176022-ed98-4e3b-96d8-116b0c58ac95 |
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.
class CWin32Heap : public IAtlMemMgr
Name | Description |
---|---|
CWin32Heap::CWin32Heap | The constructor. |
CWin32Heap::~CWin32Heap | The destructor. |
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. |
Name | Description |
---|---|
CWin32Heap::m_bOwnHeap | A flag used to determine current ownership of the heap handle. |
CWin32Heap::m_hHeap | Handle to the heap object. |
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.
See the example for IAtlMemMgr.
IAtlMemMgr
CWin32Heap
Header: atlmem.h
Allocates a block of memory from the heap object.
virtual __declspec(allocator) void* Allocate(size_t nBytes) throw();
nBytes
The requested number of bytes in the new memory block.
Returns a pointer to the newly allocated memory block.
Call CWin32Heap::Free or CWin32Heap::Reallocate to free the memory allocated by this method.
Implemented using HeapAlloc.
Attaches the heap object to an existing heap.
void Attach(HANDLE hHeap, bool bTakeOwnership) throw();
hHeap
An existing heap handle.
bTakeOwnership
A flag indicating if the CWin32Heap
object is to take ownership over the resources of the heap.
If bTakeOwnership is TRUE, the CWin32Heap
object is responsible for deleting the heap handle.
The constructor.
CWin32Heap() throw();
CWin32Heap( HANDLE hHeap) throw();
CWin32Heap(
DWORD dwFlags,
size_t nInitialSize,
size_t nMaxSize = 0);
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.
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:
[!code-cppNVC_ATL_Utilities#92]
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:
[!code-cppNVC_ATL_Utilities#93]
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.
The destructor.
~CWin32Heap() throw();
Destroys the heap handle if the CWin32Heap
object has ownership of the heap.
Detaches the heap object from an existing heap.
HANDLE Detach() throw();
Returns the handle to the heap to which the object was previously attached.
Frees memory previously allocated from the heap by CWin32Heap::Allocate or CWin32Heap::Reallocate.
virtual void Free(void* p) throw();
p
Pointer to the block of memory to free. NULL is a valid value and does nothing.
Returns the size of a memory block allocated from the heap object.
virtual size_t GetSize(void* p) throw();
p
Pointer to the memory block whose size the method will obtain. This is a pointer returned by CWin32Heap::Allocate or CWin32Heap::Reallocate.
Returns the size, in bytes, of the allocated memory block.
A flag used to determine current ownership of the heap handle stored in m_hHeap.
bool m_bOwnHeap;
Handle to the heap object.
HANDLE m_hHeap;
A variable used to store a handle to the heap object.
Reallocates a block of memory from the heap object.
virtual __declspec(allocator) void* Reallocate(void* p, size_t nBytes) throw();
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.
Returns a pointer to the newly allocated memory block.
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.
Class Overview
IAtlMemMgr Class
CLocalHeap Class
CGlobalHeap Class
CCRTHeap Class
CComHeap Class