EXT Win Library - process_heap_allocator

The win::process_heap_allocator template is an extension to the set of STL allocators that allocates memory from a process heap.

Interface:


            template <typename T>

            class win::process_heap_allocator {

                public:

                   
            typedef std::size_t     size_type;

                   
            typedef std::ptrdiff_t  difference_type;

                   
            typedef T *             pointer;

                   
            typedef const T *       const_pointer;

                   
            typedef T &             reference;

                   
            typedef const T &       const_reference;

                   
            typedef T               value_type;

            

                    template <typename T2>

                    struct rebind {

                       
            typedef process_heap_allocator <T2> other;

                    };

            

                public:

                   
            process_heap_allocator () throw ();

                   
            process_heap_allocator (const process_heap_allocator &) throw ();

            

                    template <typename T2>

                   
            process_heap_allocator (const process_heap_allocator <T2> &) throw ();

            

                    ~process_heap_allocator () throw ()

            

                public:

                   
            pointer       address (reference)       const;

                   
            const_pointer address (const_reference) const;

            

                   
            pointer       allocate (size_type, const void * = 0);

                   
            void          deallocate (pointer, size_type);

            

                   
            size_type     max_size () const throw ();

                   
            void          construct (pointer, const T &);

                   
            void          destroy (pointer);

            };

            

            template <typename T>

            bool win::operator == (const win::process_heap_allocator <T> &,

                                  
            const win::process_heap_allocator <T> &) throw ();
            

            template <typename T>

            bool win::operator != (const win::process_heap_allocator <T> &,

                                  
            const win::process_heap_allocator <T> &) throw ();

typename T
win::process_heap_allocator::value_type
The type that the allocator will manage memory for and that will be constructed and destroyed by it.
win::process_heap_allocator::address (reference)
win::process_heap_allocator::address (const_reference)
Returns a pointer to the referenced type. An operator & is always used to provide this information.
win::process_heap_allocator::allocate (size_type, const void *)
Allocates a memory to fit at least provided number (first parameter) of objects of type T. A pointer to this memory is returned or std::bad_alloc is thrown if allocation did not succeeded. Second parameter, if any, is always ignored.
win::process_heap_allocator::deallocate (pointer, size_type)
Frees the memory pointed to by provided pointer. Second parameter is ignored. The function does not throw.
win::process_heap_allocator::max_size ()
Returns a theoretical limit of number of objects of type T that can be allocated. Note that the actual maximum will definitely be less than half of the returned value. For more details see your copy of C++ standard and MSDN (Platform SDK).
win::process_heap_allocator::construct (pointer, const T &)
Copy-constructs an object of type T at the location provided by pointer (first parameter).
win::process_heap_allocator::destroy (pointer)
Destroys an object of type T at the location provided by the pointer.

Details:

To increase performance, the heap is set to be Low Fragmentation Heap (see MSDN). But this may also increase memory usage for simple applications. To suppress this behavior, define WIN_NO_LOW_FRAGMENTATION_HEAP when compiling the "ext/win_bits/process_heap_allocator.cpp" file to use normal heaps. Moreover, if the project is compiled with _WIN32_WINNT set to 0x0501 or higher, the HeapSetInformation function will be linked statically, thus preventing the application from running on Windows earlier than Windows XP.

All constructors and the destructor are not documented above because they are no-ops; the functions have empty implementation and do nothing.

You will need to include "ext/win_bits/process_heap_allocator.cpp" into your project in order to use win::process_heap_allocator.

Examples:


            #include <ext/win>

            #include <vector>

            

            std::vector <int, win::process_heap_allocator> int_heap;

            

            int main () {

                int_heap.push_back (1);

                int_heap.push_back (2);

                int_heap.push_back (3);

                int_heap.reserve (10);

                // ...

                int_heap.clear ();

                return 0;

            };

Remarks

A process-heap is a memory heap that is created for every Win32/64 process when started.
The implementation uses the Windows API heap functions thread-safely.

The win::process_heap_allocator design is based on implementations of GCC G++ extended allocators.

[index]