[#BloombergLP-bslma-NewDeleteAllocator]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bslma.adoc[bslma]::NewDeleteAllocator
:relfileprefix: ../../
:mrdocs:

This class defines a concrete mechanism that adapts the system‐supplied (native) global `operator new` and `operator delete` to the `Allocator` protocol. The class method `singleton` returns a process‐wide unique object of this class whose lifetime is guaranteed to extend from the first call to `singleton` until the program terminates. A second class method, `allocator`, allows for conveniently replacing a "null" allocator with this singleton object. Note that this entire class should generally not be used directly by typical clients (see `bslma_default` for more information).

== Synopsis

Declared in `<bslma_newdeleteallocator.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class NewDeleteAllocator
    : public xref:BloombergLP/bslma/Allocator.adoc[Allocator]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bslma/Allocator.adoc[Allocator]`
| 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 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`.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/Allocator/size_type.adoc[`size_type`] 
| Alias for an unsigned integral type capable of representing the number of bytes in this platform's virtual address space.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/NewDeleteAllocator/2constructor.adoc[`NewDeleteAllocator`]         [.small]#[constructor]#
| Create a ("stateless") new‐delete‐allocator object that wraps the global native `operator new` and `operator delete` functions in order to supply memory via the `Allocator` protocol. Note that all objects of this class share the same underlying resource; hence, this constructor should generally not be invoked directly by clients; instead, consider using the `static` `singleton` or `allocator` (factory) methods, or ‐‐ better ‐‐ the appropriate ones in `Default` (see `bslma_default` for more information).
| xref:BloombergLP/bslma/NewDeleteAllocator/2destructor.adoc[`~NewDeleteAllocator`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this allocator object. Note that destroying this allocator has no effect on any outstanding allocated memory.
| xref:BloombergLP/bslma/Allocator/operator_assign.adoc[`operator=`] 
| 
| xref:BloombergLP/bslma/NewDeleteAllocator/allocate-02.adoc[`allocate`] 
| 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. The alignment of the address returned is the maximum alignment for any fundamental, pointer, or enumerated type defined for this platform. The behavior is undefined unless `0 <= size`. Note that global `operator new` is _not_ called when `size` is 0 (in order to avoid having to acquire a lock, and potential contention in multi‐threaded programs).
| xref:BloombergLP/bslma/NewDeleteAllocator/deallocate-0f.adoc[`deallocate`] 
| Return the memory block at the specified `address` back to this allocator. If `address` is 0, this function has no effect. The behavior is undefined unless `address` was allocated using this allocator object and has not already been deallocated. Note that global `operator delete` is _not_ called when `address` is 0 (in order to avoid having to acquire a lock, and potential contention in multi‐threaded programs).
| xref:BloombergLP/bslma/Allocator/deleteObject-09.adoc[`deleteObject`] 
| `deleteObject` overloads
| xref:BloombergLP/bslma/Allocator/deleteObjectRaw-06f.adoc[`deleteObjectRaw`] 
| `deleteObjectRaw` overloads
| xref:BloombergLP/bslma/Allocator/is_equal.adoc[`is_equal`] 
| 
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/NewDeleteAllocator/allocator.adoc[`allocator`] 
| Return the address of the specified modifiable `basicAllocator` or, if `basicAllocator` is 0, the process‐wide unique (see `singleton`) object of this class. Note that the behavior of this function is equivalent to the following expression: ` basicAllocator ? basicAllocator : &NewDeleteAllocator::singleton() ` Also note that if a `NewDeleteAllocator` object is supplied, it is owned by the class and must NOT be deleted. Finally note that this method should generally not be called directly by typical clients (see `bslma_default` for more information).
| xref:BloombergLP/bslma/NewDeleteAllocator/singleton.adoc[`singleton`] 
| Return a reference to a process‐wide unique object of this class. The lifetime of this object is guaranteed to extend from the first call of this method until the program terminates. Note that this method should generally not be used directly by typical clients (see `bslma_default` for more information).
| xref:BloombergLP/bslma/Allocator/throwBadAlloc.adoc[`throwBadAlloc`] 
| 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.
|===


== Protected Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/Allocator/do_allocate.adoc[`do_allocate`]  [.small]#[virtual]#
| 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 that if `bytes` is `0`, the same non‐null value will be returned every time.
| xref:BloombergLP/bslma/Allocator/do_deallocate.adoc[`do_deallocate`]  [.small]#[virtual]#
| 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`. The behavior is undefined unless `address` is a block allocated from this allocator object using the same `bytes` and `alignment` and not already deallocated.
| xref:BloombergLP/bslma/Allocator/do_is_equal.adoc[`do_is_equal`]  [.small]#[virtual]#
| 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`.
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#