[#BloombergLP-bdlma-GuardingAllocator]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlma.adoc[bdlma]::GuardingAllocator
:relfileprefix: ../../
:mrdocs:

This class defines a concrete thread‐safe "guarding" allocator mechanism that implements the `bslma::Allocator` protocol, and adjoins a read/write protected guard page to each block of memory returned by the `allocate` method. The guard page is placed immediately before or immediately following the block returned from `allocate` according to the `GuardPageLocation` enumerator value (optionally) supplied at construction. Note that, unlike many other allocators, an allocator cannot be (optionally) supplied at construction; instead, a system facility is used that allocates blocks of memory in multiples of the system page size. Also note that this allocator is intended for debugging purposes _only_.

== Synopsis

Declared in `<bdlma_guardingallocator.h>`

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

== Base Classes

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


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlma/GuardingAllocator/GuardPageLocation.adoc[`GuardPageLocation`] 
| Enumerate the configuration options for `GuardingAllocator` that may be (optionally) supplied at construction.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlma/GuardingAllocator/2constructor.adoc[`GuardingAllocator`]         [.small]#[constructor]#
| Create a guarding allocator. Optionally specify a `guardLocation` indicating where read/write protected guard pages should be placed with respect to the memory blocks returned by the `allocate` method. If `guardLocation` is not specified, guard pages are placed immediately following the memory blocks returned by `allocate`.
| xref:BloombergLP/bdlma/GuardingAllocator/2destructor.adoc[`~GuardingAllocator`] [.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/bdlma/GuardingAllocator/allocate-07.adoc[`allocate`] 
| `allocate` overloads
| xref:BloombergLP/bdlma/GuardingAllocator/deallocate-03.adoc[`deallocate`] 
| Return the memory block at the specified `address` back to this allocator. If `address` is 0, this method has no effect. Otherwise, the guard page associated with `address` is unprotected and also deallocated. The behavior is undefined unless `address` was returned by `allocate` and has not already been deallocated.
| 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/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]#