.\"
.de Id
..
.de Sp
.if n .sp
.if t .sp 0.4
..
.TH heap_allocator 7rheolef "rheolef-6.7" "rheolef-6.7" "rheolef-6.7"
.\" label: /*Class:man
.SH NAME
heap_allocator - heap-based allocator
.SH DESCRIPTION

Heap allocators are generally used when there is a lot of allocation and deallocation
of small objects.
For instance, this is often the case when dealing with \fBstd::list\fP and \fBstd::map\fP.
.PP
Heap-based allocator is conform to the STL specification of allocators.
It does not "free" the memory until the heap is destroyed.
.PP
This allocator handles an a priori unlimited area of memory: a sequence
of growing chunks are allocated.
For a limited memory handler in the same spirit, see "stack_allocator"(9).
.SH EXAMPLE

.\" begin_example
.Sp
.nf
    typedef map <size_t, double, less<size_t>, heap_allocator<pair<size_t,double> > >  map_type;
    map_type a;
    a.insert (make_pair (0, 3.14));
    a.insert (make_pair (1, 1.17));
    for (map_type::iterator iter = a.begin(), last = a.end(); iter != last; iter++) {
      cout << (*iter).first << " " << (*iter).second << endl;
    }
.Sp
.fi
.\" end_example
.\" skip start:SEE ALSO:
.\" skip start:AUTHORS:

.\" skip start:DATE:
.\" END
.SH IMPLEMENTATION
.\" begin_example
.Sp
.nf
template <typename T>
class heap_allocator {
protected:
    struct handler_type; // forward declaration:
public:

// typedefs:

    typedef 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;

// constructors:

    heap_allocator() throw()
      : handler (new handler_type)
    {
    }
    heap_allocator (const heap_allocator& ha) throw()
      : handler (ha.handler)
    {
        ++handler->reference_count;
    }
    template <typename U>
    heap_allocator (const heap_allocator<U>& ha) throw()
      : handler ((typename heap_allocator<T>::handler_type*)(ha.handler))
    {
        ++handler->reference_count;
    }
    ~heap_allocator() throw()
    {
        check_macro (handler != NULL, "unexpected null mem_info");
        if (--handler->reference_count == 0) delete handler;
    }
    // Rebind to allocators of other types
    template <typename U>
    struct rebind {
        typedef heap_allocator<U> other;
    };

// assignement:

    heap_allocator& operator= (const heap_allocator& ha)
    {
        handler = ha.handler;
        ++handler->reference_count;
        return *this;
    }

// utility functions:

    pointer       address (reference r)       const { return &r; }
    const_pointer address (const_reference c) const { return &c; }
    size_type     max_size() const { return std::numeric_limits<size_t>::max() / sizeof(T); }

// in-place construction/destruction

    void construct (pointer p, const_reference c)
    {
        // placement new operator:
        new( reinterpret_cast<void*>(p) ) T(c);
    }
    // C++ 2011: default construct a value of type T at the location referenced by p
    void construct (pointer p) { new ( reinterpret_cast<void*>(p) ) T(); }

    void destroy (pointer p)
    {
        // call destructor directly:
        (p)->~T();
    }

// allocate raw memory

    pointer allocate (size_type n, const void* = NULL)
    {
        return pointer (handler->raw_allocate (n*sizeof(T)));
    }
    void deallocate (pointer p, size_type n)
    {
        // No need to free heap memory
    }
    const handler_type* get_handler() const {
        return handler;
    }

// data:

protected:
    handler_type* handler;
    template <typename U> friend class heap_allocator;
};
.Sp
.fi
.\" end_example