bslma::Allocator Class Reference

#include <bslma_allocator.h>

Inheritance diagram for bslma::Allocator:

Detailed Description

This protocol class provides a pure abstract interface and contract for clients and suppliers of raw memory. If the requested memory cannot be returned, the contract requires that an std::bad_alloc exception be thrown.

Note

Note that memory is guaranteed to be sufficiently aligned for any object of the requested size on the current platform, which may be less than the maximal alignment guarantee afforded by global operator new.

See bslma_allocator

Public Types
typedef std::size_t	size_type

Public Member Functions
	~Allocator () BSLS_KEYWORD_OVERRIDE
virtual void *	allocate (size_type size)=0
virtual void	deallocate (void *address)=0
template<class TYPE >
void	deleteObject (const TYPE *object)
template<class TYPE >
void	deleteObjectRaw (const TYPE *object)
void	deleteObject (bsl::nullptr_t)
void	deleteObjectRaw (bsl::nullptr_t)
Public Member Functions inherited from bsl::memory_resource
	memory_resource () BSLS_KEYWORD_DEFAULT
	memory_resource (const memory_resource &) BSLS_KEYWORD_DEFAULT
virtual	~memory_resource ()
memory_resource &	operator= (const memory_resource &) BSLS_KEYWORD_DEFAULT
BSLA_NODISCARD void *	allocate (size_t bytes, size_t alignment=k_MAX_ALIGN)
void	deallocate (void *p, size_t bytes, size_t alignment=k_MAX_ALIGN)
bool	is_equal (const memory_resource &other) const BSLS_KEYWORD_NOEXCEPT

Static Public Member Functions
static void	throwBadAlloc ()

Protected Member Functions
void *	do_allocate (std::size_t bytes, std::size_t alignment) BSLS_KEYWORD_OVERRIDE
void	do_deallocate (void *p, std::size_t bytes, std::size_t alignment) BSLS_KEYWORD_OVERRIDE
bool	do_is_equal (const memory_resource &other) const BSLS_KEYWORD_NOEXCEPT BSLS_KEYWORD_OVERRIDE

Member Typedef Documentation

size_type

typedef std::size_t bslma::Allocator::size_type

Alias for an unsigned integral type capable of representing the number of bytes in this platform's virtual address space.

Constructor & Destructor Documentation

~Allocator()

bslma::Allocator::~Allocator

(

)

Destroy this allocator.

Note

Note that the behavior of destroying an allocator while memory is allocated from it is not specified; unless you know that it is valid to do so, don't!

Member Function Documentation

allocate()

virtual void * bslma::Allocator::allocate ( size_type  size )

pure virtual

Return a newly allocated block of memory of (at least) the specified positive size (in bytes). If size is 0, a null pointer is returned with no other effect. If this allocator cannot return the requested number of bytes, then it will throw a std::bad_alloc exception in an exception-enabled build, or else will abort the program in a non-exception build.

Precondition

The behavior is undefined unless 0 <= size.

Note

Note that the alignment of the address returned conforms to the platform requirement for any object of the specified size.

Note that this virtual function hides a two-parameter non-virtual allocate method inherited from bsl::memory_resource; to access the inherited function, upcast the object to bsl::memory_resource& before calling the base-class function.

Implemented in bdlma::ConcurrentAllocatorAdapter, bdlma::AligningAllocator, bdlma::ConcurrentMultipoolAllocator, bdlma::CountingAllocator, bdlma::GuardingAllocator, bdlma::HeapBypassAllocator, bdlma::MultipoolAllocator, bdlma::SequentialAllocator, bslma::SequentialAllocator, ball::CountingAllocator, balst::StackTraceTestAllocator, bdlma::BufferedSequentialAllocator, bdlma::ConcurrentPoolAllocator, bslma::AllocatorAdaptor_Imp< STL_ALLOC >, bslma::AllocatorAdaptor_Imp< STL_ALLOC::template rebind< char >::other >, bslma::BufferAllocator, bslma::MallocFreeAllocator, bslma::NewDeleteAllocator, and bslma::TestAllocator.

deallocate()

virtual void bslma::Allocator::deallocate ( void *  address )

pure virtual

Return the memory block at the specified address back to this allocator. If address is 0, this function has no effect.

Precondition

The behavior is undefined unless address was allocated using this allocator object and has not already been deallocated.

Note

Note that this virtual function hides a three-parameter, non-virtual deallocate method inherited from bsl::memory_resource; to access the inherited function, upcast the object to bsl::memory_resource& before calling the base-class function.

Implemented in bdlma::HeapBypassAllocator, ball::CountingAllocator, balst::StackTraceTestAllocator, bdlma::AligningAllocator, bdlma::BufferedSequentialAllocator, bdlma::ConcurrentAllocatorAdapter, bdlma::ConcurrentMultipoolAllocator, bdlma::ConcurrentPoolAllocator, bdlma::CountingAllocator, bdlma::GuardingAllocator, bdlma::MultipoolAllocator, bdlma::SequentialAllocator, bslma::AllocatorAdaptor_Imp< STL_ALLOC >, bslma::AllocatorAdaptor_Imp< STL_ALLOC::template rebind< char >::other >, bslma::BufferAllocator, bslma::MallocFreeAllocator, bslma::NewDeleteAllocator, bslma::SequentialAllocator, and bslma::TestAllocator.

deleteObject() [1/2]

void bslma::Allocator::deleteObject ( bsl::nullptr_t  )

inline

This function has no effect.

Note

Note that it exists to support calling deleteObject will a null pointer literal, that would otherwise not deduce to a pointer type for the method above. As calls to deleteObject with (typed) null pointer values have well-defined behavior, it should also support calls with a null pointer literal.

deleteObject() [2/2]

template<class TYPE >

void bslma::Allocator::deleteObject ( const TYPE *  object )

inline

Destroy the specified object based on its dynamic type and then use this allocator to deallocate its memory footprint. Do nothing if object is a null pointer.

Precondition

The behavior is undefined unless object, when cast appropriately to void *, was allocated using this allocator and has not already been deallocated.

Note

Note that dynamic_cast<void *>(object) is applied if TYPE is polymorphic, and static_cast<void *>(object) is applied otherwise.

deleteObjectRaw() [1/2]

void bslma::Allocator::deleteObjectRaw ( bsl::nullptr_t  )

inline

This function has no effect.

Note

Note that it exists to support calling deleteObjectRaw will a null pointer literal, that would otherwise not deduce to a pointer type for the method above. As calls to deleteObjectRaw with (typed) null pointer values have well-defined behavior, it should also support calls with a null pointer literal.

deleteObjectRaw() [2/2]

template<class TYPE >

void bslma::Allocator::deleteObjectRaw ( const TYPE *  object )

inline

Destroy the specified object and then use this allocator to deallocate its memory footprint. Do nothing if object is a null pointer.

Precondition

The behavior is undefined unless object was allocated using this allocator, is not a secondary base class pointer – i.e., the address is (numerically) the same as when it was originally dispensed by this allocator, and has not already been deallocated.

do_allocate()

void * bslma::Allocator::do_allocate ( std::size_t  bytes, std::size_t  alignment  )

protected

Return a newly allocated block of memory of (at least) the specified positive bytes and having at least the specified alignment. Unless overriden in a derived class, the return value is this->allocate(bytes). If this allocator cannot return the requested number of bytes or cannot satisfy the alignment request, then it will throw a std::bad_alloc exception in an exception-enabled build, or else will abort the program in a non-exception build. Unless overriden in a derived class, this function will forward the allocation request to the allocate virtual function, padding bytes and adjusting the return value as necessary to ensure sufficient alignment.

Note

Note that if bytes is 0, the same non-null value will be returned every time.

do_deallocate()

void bslma::Allocator::do_deallocate ( void *  p, std::size_t  bytes, std::size_t  alignment  )

protected

Return the memory block at the specified p address, having the specified bytes and specified alignment, back to this allocator. Unless overriden in a derived class, this function will forward the deallocation request to the deallocate virtual function, padding bytes and adjusting p as necessary to account for alignment values other than the natural alignment for an object of size bytes.

Precondition

The behavior is undefined unless address is a block allocated from this allocator object using the same bytes and alignment and not already deallocated.

do_is_equal()

bool bslma::Allocator::do_is_equal ( const memory_resource &  other ) const

protected

Return true if this allocator is equal to the specified other allocator, meaning (at least) that a memory block allocated by one can be deallocated by the other; otherwise return false. Unless overriden, this method returns this == &other.

throwBadAlloc()

static void bslma::Allocator::throwBadAlloc ( )

static

Throw std::bad_alloc if exceptions are enabled or abort the program otherwise. Derived classes and helper functions will typically call this function when they are unable to satisfy an allocation request. This function never returns.

Deprecated:

Use bsls::BslExceptionUtil::throwBadAlloc instead.

---

The documentation for this class was generated from the following file:

• bslma_allocator.h