Memory Library
[Libraries]


Detailed Description

Created: 23rd May 2006 Updated: 13th March 2007.

This library defines functions, classes, allocator class templates, and meta-classes that assist in the manipulation of memory.


Classes

class  task_allocator
 STL Allocator based on the COM task allocator. More...
class  afx_allocator
 STL Allocator based on the MFC memory framework. More...
class  allocator_base
 STL Allocator base class adaptor, providing much of the boilerplate functionality of an STL-compliant Allocator class. More...
struct  allocator_selector
 Type generator class template that selects an appropriate allocator specialisation for the given type. More...
class  auto_buffer
 This class provides an efficient variable automatic buffer. More...
struct  move_proxy
 A simple proxy class that supports the movement of pointers between the various destructor classes. More...
class  auto_destructor
 This class acts as an automatic frame scope variable that manages heap-allocated object instances. More...
class  auto_array_destructor
 This class acts as an automatic frame scope variable that manages heap-allocated object arrays. More...
class  return_value_destructor
 This class acts as a return-value scope variable that manages heap-allocated object instances. More...
class  return_value_array_destructor
 This class acts as a return-value scope variable that manages heap-allocated object arrays. More...
class  malloc_allocator
 STL Allocator based on the C runtime malloc() & free() functions. More...
class  new_allocator
 STL Allocator based on operators new and delete. More...
class  null_allocator
 STL Allocator that fails all allocation requests. More...
class  global_allocator
 STL Allocator based on the Win32 Global() API. More...
class  heapwalk_sequence
 An STL-like sequence for walking heap allocated blocks. More...
class  heapwalk_sequence_const_iterator
 Iterator for the heapwalk_sequence class. More...
class  netapi_allocator
 STL Allocator based on the Windows Network Management ApiBuffer API. More...
class  processheap_allocator
 STL Allocator based on the Win32 process heap. More...
class  shell_allocator
 STL Allocator based on the Win32 shell allocator. More...

Defines

#define STLSOFT_CF_ALLOCATOR_TYPED_DEALLOCATE_POINTER
 Indicates, when defined, that STL-like allocator classes need their deallocate() method to use void*.
#define STLSOFT_CF_ALLOCATOR_CHARALLOC_METHOD
 Indicates, when defined, that STL-like allocator classes need a _Charalloc() method, to be compatible with the Dinkumware libraries of older Visual C++ compilers.
#define STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT
 Indicates, when defined, that STL-like allocator classes' allocate() method takes a second hint parameter.
#define STLSOFT_LF_ALLOCATOR_DEALLOCATE_HAS_COUNT
 Indicates, when defined, that STL-like allocator classes' deallocate() method takes a second count parameter.
#define STLSOFT_CF_ALLOCATOR_REBIND_SUPPORT
 Indicates, when defined, that STL-like allocator classes use the rebind mechanism.
#define STLSOFT_CF_ALLOCATOR_REBIND_SUPPORT
 Indicates, when defined, that STL-like allocator classes use the rebind mechanism.
#define STLSOFT_LF_ALLOCATOR_REBIND_SUPPORT
 Indicates, when defined, that std::allocator defines a rebind member template.

Functions

ACE_Message_Block * make_copied_Message_Block (char const *p, size_t n)
 Creates a new ACE_Message_Block instance whose contents are copied from the given memory.
STLSOFT_INLINE size_t comstl__CoTaskMemGetSize (void *pv)
 [C only] Gives the size of a memory block
STLSOFT_INLINE cs_sint_t comstl__CoTaskMemDidAlloc (void *pv)
 [C only] Determines allocation ownership of a memory block
STLSOFT_INLINE void comstl__CoTaskMemHeapMinimise (void)
 [C only] Minimises the heap
size_t CoTaskMemGetSize (void *pv)
 Gives the size of a memory block.
cs_sint_t CoTaskMemDidAlloc (void *pv)
 Determines allocation ownership of a memory block.
void CoTaskMemHeapMinimise ()
 Minimises the heap.
void CoTaskMemHeapMinimize ()
 Minimises the heap.
STLSOFT_INLINE void * winstl__SHMemAlloc (size_t cb)
 [C only] Allocates a block of shell memory.
STLSOFT_INLINE void winstl__SHMemFree (void *pv)
 [C only] Deallocates a block of shell memory previously allocated by a call to winstl__SHMemAlloc(), winstl__SHMemRealloc() or through the IMalloc::Alloc() or IMalloc::Realloc() methods on the shell allocator (obtained via SHGetMalloc()).
STLSOFT_INLINE void * winstl__SHMemRealloc (void *pv, size_t cb)
 [C only] Rellocates a block of shell memory.
STLSOFT_INLINE size_t winstl__SHMemGetSize (void *pv)
 [C only] Gives the size of a memory block
STLSOFT_INLINE ws_sint_t winstl__SHMemDidAlloc (void *pv)
 [C only] Determines allocation ownership of a memory block
STLSOFT_INLINE void winstl__SHMemHeapMinimise (void)
 [C only] Minimises the heap
void * SHMemAlloc (size_t cb)
 Allocates a block of shell memory.
void SHMemFree (void *pv)
 Deallocates a block of shell memory.
void * SHMemRealloc (void *pv, size_t cb)
 Changes the size of a previously allocated block of shell memory.
size_t SHMemGetSize (void *pv)
 Gives the size of a memory block.
ws_sint_t SHMemDidAlloc (void *pv)
 Determines allocation ownership of a memory block.
void SHMemHeapMinimise ()
 Minimises the heap.
void SHMemHeapMinimize ()
 Minimises the heap.


Define Documentation

#define STLSOFT_CF_ALLOCATOR_CHARALLOC_METHOD

Indicates, when defined, that STL-like allocator classes need a _Charalloc() method, to be compatible with the Dinkumware libraries of older Visual C++ compilers.

See also:
stlsoft::allocator_base::_Charalloc()

#define STLSOFT_CF_ALLOCATOR_REBIND_SUPPORT

Indicates, when defined, that STL-like allocator classes use the rebind mechanism.

Use this symbol when determining whether to provide rebind for an allocator.

#define STLSOFT_CF_ALLOCATOR_REBIND_SUPPORT

Indicates, when defined, that STL-like allocator classes use the rebind mechanism.

Use this symbol when determining whether to provide rebind for an allocator.

#define STLSOFT_CF_ALLOCATOR_TYPED_DEALLOCATE_POINTER

Indicates, when defined, that STL-like allocator classes need their deallocate() method to use void*.

See also:
stlsoft::allocator_base::_Charalloc()

#define STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT

Indicates, when defined, that STL-like allocator classes' allocate() method takes a second hint parameter.

TODO: This should be resolving solely on the library (and version), and not involving the compiler.

#define STLSOFT_LF_ALLOCATOR_DEALLOCATE_HAS_COUNT

Indicates, when defined, that STL-like allocator classes' deallocate() method takes a second count parameter.

TODO: This should be resolving solely on the library (and version), and not involving the compiler.

#define STLSOFT_LF_ALLOCATOR_REBIND_SUPPORT

Indicates, when defined, that std::allocator defines a rebind member template.

Note:
Effectively, this can be used to determine whether any allocator supports rebind.
Use this symbol when determining whether to use rebind on an allocator.


Function Documentation

STLSOFT_INLINE cs_sint_t comstl__CoTaskMemDidAlloc ( void *  pv  ) 

[C only] Determines allocation ownership of a memory block

This function returns a value indicating whether a memory block was allocated by the COM task allocator, as per IMalloc::DidAlloc()

Parameters:
pv Pointer to the memory block
Returns:
Result indicating ownership
Return values:
1 The memory block was allocated by the task allocator
0 The memory block was not allocated by the task allocator
-1 CoTaskMemDidAlloc() cannot determine whether the memory block was allocated by the task allocator
Note:
[C++] This function is wrapped by the comstl::CoTaskMemDidAlloc() function.

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, STLSOFT_NS_GLOBAL, and stlsoft_static_cast.

Referenced by comstl__olestring_destroy(), and comstl::CoTaskMemDidAlloc().

STLSOFT_INLINE size_t comstl__CoTaskMemGetSize ( void *  pv  ) 

[C only] Gives the size of a memory block

This function returns the size of a memory block relative to the COM task alloctor, as per IMalloc::GetSize()

Parameters:
pv Pointer to the memory block
Returns:
The size of the memory block (in bytes)
Note:
[C++] This function is wrapped by the comstl::CoTaskMemGetSize() function.

References COMSTL_ITF_CALL, COMSTL_ITF_THIS, COMSTL_ITF_THIS0, STLSOFT_NS_GLOBAL, and stlsoft_static_cast.

Referenced by comstl::CoTaskMemGetSize().

STLSOFT_INLINE void comstl__CoTaskMemHeapMinimise ( void   ) 

[C only] Minimises the heap

This function minimises the heap as much as possible by releasing unused memory to the operating system, coalescing adjacent free blocks and committing free pages, as as per IMalloc::HeapMinimize().

Note:
[C++] This function is wrapped by the comstl::CoTaskMemHeapMinimise() function.

References COMSTL_ITF_CALL, COMSTL_ITF_THIS0, STLSOFT_NS_GLOBAL, and stlsoft_static_cast.

Referenced by comstl::CoTaskMemHeapMinimise(), and comstl::CoTaskMemHeapMinimize().

cs_sint_t comstl::CoTaskMemDidAlloc ( void *  pv  )  [inline]

Determines allocation ownership of a memory block.

This function is a wrapper for comstl__CoTaskMemDidAlloc().

Parameters:
pv Pointer to the memory block
Returns:
Result indicating ownership
Return values:
1 The memory block was allocated by the task allocator
0 The memory block was not allocated by the task allocator
-1 CoTaskMemDidAlloc() cannot determine whether the memory block was allocated by the task allocator
Examples:
by_library/memory/com_memory_functions/com_memory_functions.cpp.

References comstl__CoTaskMemDidAlloc().

size_t comstl::CoTaskMemGetSize ( void *  pv  )  [inline]

Gives the size of a memory block.

This function is a wrapper for comstl__CoTaskMemGetSize().

Parameters:
pv Pointer to the memory block
Returns:
The size of the memory block (in bytes)
Examples:
by_library/memory/com_memory_functions/com_memory_functions.cpp.

References comstl__CoTaskMemGetSize().

void comstl::CoTaskMemHeapMinimise (  )  [inline]

Minimises the heap.

This function is a wrapper for comstl__CoTaskMemHeapMinimise().

References comstl__CoTaskMemHeapMinimise().

void comstl::CoTaskMemHeapMinimize (  )  [inline]

Minimises the heap.

This function is a wrapper for comstl__CoTaskMemHeapMinimise().

References comstl__CoTaskMemHeapMinimise().

ACE_Message_Block* acestl::make_copied_Message_Block ( char const *  p,
size_t  n 
) [inline]

Creates a new ACE_Message_Block instance whose contents are copied from the given memory.

Parameters:
p Pointer to the memory to copy into the new message block. May be NULL, in which case the contents are not explicitly initialised.
n Number of bytes to copy into the new message block. If NULL == p, this is the size of the initialised block.
Usage is simple: just specify the source (pointer and length), and test for NULL (allocation failure):

ACE_Message_Block *newBlock = acestl::make_copied_Message_Block("Contents", 7);

if(NULL == newBlock)
{
  std::cerr <<  "Allocation failed!\n";
}

Exceptions:
- In accordance with the non-throwing nature of ACE, memory allocation failure is reflected by returning NULL.

void* winstl::SHMemAlloc ( size_t  cb  )  [inline]

Allocates a block of shell memory.

This function is a wrapper for winstl__SHMemAlloc().

Parameters:
cb The size, in bytes, of the memory block to be allocated.
Returns:
Pointer to the allocated memory block, or NULL if the request failed.
Examples:
by_library/windows_shell/memory_functions/memory_functions.cpp.

References winstl__SHMemAlloc().

ws_sint_t winstl::SHMemDidAlloc ( void *  pv  )  [inline]

Determines allocation ownership of a memory block.

This function is a wrapper for winstl__SHMemDidAlloc().

Parameters:
pv Pointer to the memory block
Returns:
Result indicating ownership
Return values:
1 The memory block was allocated by the task allocator
0 The memory block was not allocated by the task allocator
-1 SHMemDidAlloc() cannot determine whether the memory block was allocated by the task allocator
Examples:
by_library/windows_shell/memory_functions/memory_functions.cpp.

References winstl__SHMemDidAlloc().

void winstl::SHMemFree ( void *  pv  )  [inline]

Deallocates a block of shell memory.

This function is a wrapper for winstl__SHMemFree().

Parameters:
pv Pointer to the memory block to be deallocated
Examples:
by_library/windows_shell/memory_functions/memory_functions.cpp, and by_library/windows_shell/shell_functions/shell_functions.cpp.

References winstl__SHMemFree().

size_t winstl::SHMemGetSize ( void *  pv  )  [inline]

Gives the size of a memory block.

This function is a wrapper for winstl__SHMemGetSize().

Parameters:
pv Pointer to the memory block
Returns:
The size of the memory block (in bytes)
Examples:
by_library/windows_shell/memory_functions/memory_functions.cpp.

References winstl__SHMemGetSize().

void winstl::SHMemHeapMinimise (  )  [inline]

Minimises the heap.

This function is a wrapper for winstl__SHMemHeapMinimise().

References winstl__SHMemHeapMinimise().

void winstl::SHMemHeapMinimize (  )  [inline]

Minimises the heap.

This function is a wrapper for winstl__SHMemHeapMinimise().

References winstl__SHMemHeapMinimise().

void* winstl::SHMemRealloc ( void *  pv,
size_t  cb 
) [inline]

Changes the size of a previously allocated block of shell memory.

This function is a wrapper for winstl__SHMemRelloc().

Parameters:
pv Pointer to the memory block to be reallocated. Can be NULL, in which case the function acts like SHMemAlloc()
cb The size, in bytes, of the memory block to be reallocated. Can be 0, in which case the function acts like SHMemFree() (if pv is not NULL), or like SHMemAlloc() (if pv is NULL).
Returns:
Pointer to the allocated memory block, or NULL if the request failed or cb is 0 and pv is not NULL.
Examples:
by_library/windows_shell/memory_functions/memory_functions.cpp.

References winstl__SHMemRealloc().

STLSOFT_INLINE void* winstl__SHMemAlloc ( size_t  cb  ) 

[C only] Allocates a block of shell memory.

This function uses the shell allocator to allocate a memory block.

Parameters:
cb The size, in bytes, of the memory block to be allocated.
Returns:
Pointer to the allocated memory block, or NULL if the request failed.
Remarks:
On failure, the function will set the thread error information, which may be retrieved by the Win32 API function GetLastError()
Note:
[C++] This function is wrapped by the winstl::SHMemAlloc() function.

References STLSOFT_NS_GLOBAL, stlsoft_static_cast, WINSTL_ITF_CALL, WINSTL_ITF_THIS, and WINSTL_ITF_THIS0.

Referenced by winstl::SHMemAlloc().

STLSOFT_INLINE ws_sint_t winstl__SHMemDidAlloc ( void *  pv  ) 

[C only] Determines allocation ownership of a memory block

This function returns a value indicating whether a memory block was allocated by the COM task allocator, as per IMalloc::DidAlloc()

Parameters:
pv Pointer to the memory block
Returns:
Result indicating ownership
Return values:
1 The memory block was allocated by the task allocator
0 The memory block was not allocated by the task allocator
-1 SHMemDidAlloc() cannot determine whether the memory block was allocated by the task allocator
Note:
[C++] This function is wrapped by the winstl::SHMemDidAlloc() function.

References STLSOFT_NS_GLOBAL, stlsoft_static_cast, WINSTL_ITF_CALL, WINSTL_ITF_THIS, and WINSTL_ITF_THIS0.

Referenced by winstl::SHMemDidAlloc().

STLSOFT_INLINE void winstl__SHMemFree ( void *  pv  ) 

[C only] Deallocates a block of shell memory previously allocated by a call to winstl__SHMemAlloc(), winstl__SHMemRealloc() or through the IMalloc::Alloc() or IMalloc::Realloc() methods on the shell allocator (obtained via SHGetMalloc()).

This function uses the shell allocator to allocate a memory block.

Parameters:
pv Pointer to the memory block to be deallocated
Remarks:
On failure, the function will set the thread error information, which may be retrieved by the Win32 API function GetLastError()
Note:
[C++] This function is wrapped by the winstl::SHMemFree() function.

References STLSOFT_NS_GLOBAL, stlsoft_static_cast, WINSTL_ITF_CALL, WINSTL_ITF_THIS, and WINSTL_ITF_THIS0.

Referenced by winstl::SHMemFree().

STLSOFT_INLINE size_t winstl__SHMemGetSize ( void *  pv  ) 

[C only] Gives the size of a memory block

This function returns the size of a memory block relative to the COM task alloctor, as per IMalloc::GetSize()

Parameters:
pv Pointer to the memory block
Returns:
The size of the memory block (in bytes)
Note:
[C++] This function is wrapped by the winstl::SHMemGetSize() function.

References STLSOFT_NS_GLOBAL, stlsoft_static_cast, WINSTL_ITF_CALL, WINSTL_ITF_THIS, and WINSTL_ITF_THIS0.

Referenced by winstl::SHMemGetSize().

STLSOFT_INLINE void winstl__SHMemHeapMinimise ( void   ) 

[C only] Minimises the heap

This function minimises the heap as much as possible by releasing unused memory to the operating system, coalescing adjacent free blocks and committing free pages, as as per IMalloc::HeapMinimize().

Note:
[C++] This function is wrapped by the winstl::SHMemHeapMinimise() function.

References STLSOFT_NS_GLOBAL, stlsoft_static_cast, WINSTL_ITF_CALL, and WINSTL_ITF_THIS0.

Referenced by winstl::SHMemHeapMinimise(), and winstl::SHMemHeapMinimize().

STLSOFT_INLINE void* winstl__SHMemRealloc ( void *  pv,
size_t  cb 
)

[C only] Rellocates a block of shell memory.

This function uses the shell allocator to allocate a memory block.

Parameters:
pv Pointer to the memory block to be reallocated. Can be NULL, in which case the function acts like SHMemAlloc()
cb The size, in bytes, of the memory block to be reallocated. Can be 0, in which case the function acts like SHMemFree() (if pv is not NULL), or like SHMemAlloc() (if pv is NULL).
Returns:
Pointer to the allocated memory block, or NULL if the request failed or cb is 0 and pv is not NULL.
Remarks:
On failure, the function will set the thread error information, which may be retrieved by the Win32 API function GetLastError()
Note:
[C++] This function is wrapped by the winstl::SHMemRealloc() function.

References STLSOFT_NS_GLOBAL, stlsoft_reinterpret_cast, stlsoft_static_cast, WINSTL_ITF_CALL, WINSTL_ITF_THIS, and WINSTL_ITF_THIS0.

Referenced by winstl::SHMemRealloc().


Generated on Thu Jun 10 08:58:18 2010 for STLSoft by  doxygen 1.5.6