[#BloombergLP-balst-StackTraceTestAllocator]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/balst.adoc[balst]::StackTraceTestAllocator
:relfileprefix: ../../
:mrdocs:

This class defines a concrete "test" allocator mechanism that implements the `bdlma::ManagedAllocator` protocol.

== Synopsis

Declared in `<balst_stacktracetestallocator.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class StackTraceTestAllocator
    : public xref:BloombergLP/bdlma/ManagedAllocator.adoc[bdlma::ManagedAllocator]
----

== Description

Provides instrumentation to track the set of all blocks allocated by this allocator that have yet to be freed. At any time it can produce a report about such blocks, listing for each place that any unfreed blocks were allocated * the number of unfreed blocks allocated at that place * the stack trace at that place The allocator will also detect redundant frees of the same block, and frees by the wrong allocator. The client can choose whether such violations are handled by a core dump, or merely a report being written.

Note that, unlike many other allocators, this allocator does DOES NOT rely on the currently installed default allocator (see `bslma_default`) at all, but instead ‐‐ by default ‐‐ uses `MallocFreeAllocator` singleton, which in turn calls the C Standard Library functions `malloc` and `free` as needed. Clients may, however, override this allocator by supplying (at construction) any other allocator implementing the `bslma::Allocator` protocol.

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlma/ManagedAllocator.adoc[bdlma::ManagedAllocator]`
| Protocol for allocators that support releasing all allocated memory.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balst/StackTraceTestAllocator/FailureHandler-06.adoc[`FailureHandler`] 
| Type of functor called by this object to handle allocation failures.
| 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/balst/StackTraceTestAllocator/2constructor-0a.adoc[`StackTraceTestAllocator`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/balst/StackTraceTestAllocator/2destructor.adoc[`~StackTraceTestAllocator`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy this allocator.
| xref:BloombergLP/bslma/Allocator/operator_assign.adoc[`operator=`] 
| 
| xref:BloombergLP/balst/StackTraceTestAllocator/allocate-00.adoc[`allocate`] 
| Return a newly allocated block of memory of the specified positive `size` (in bytes).
| xref:BloombergLP/balst/StackTraceTestAllocator/allocationLimit.adoc[`allocationLimit`] 
| Return the current number of allocation requests left before an exception is thrown. A negative value indicates that no exception is scheduled.
| xref:BloombergLP/balst/StackTraceTestAllocator/deallocate-06.adoc[`deallocate`] 
| Return the memory block at the specified `address` back to this allocator.
| xref:BloombergLP/bslma/Allocator/deleteObject-09.adoc[`deleteObject`] 
| `deleteObject` overloads
| xref:BloombergLP/bslma/Allocator/deleteObjectRaw-06f.adoc[`deleteObjectRaw`] 
| `deleteObjectRaw` overloads
| xref:BloombergLP/balst/StackTraceTestAllocator/failureHandler-02.adoc[`failureHandler`] 
| Return a reference to the function that will be called when a failure is observed.
| xref:BloombergLP/bslma/Allocator/is_equal.adoc[`is_equal`] 
| 
| xref:BloombergLP/balst/StackTraceTestAllocator/numAllocations.adoc[`numAllocations`] 
| Return the number of allocations from this object that have occurred since creation.
| xref:BloombergLP/balst/StackTraceTestAllocator/numBlocksInUse.adoc[`numBlocksInUse`] 
| Return the number of blocks currently allocated from this object.
| xref:BloombergLP/balst/StackTraceTestAllocator/release.adoc[`release`]  [.small]#[virtual]#
| Deallocate all memory held by this allocator.
| xref:BloombergLP/balst/StackTraceTestAllocator/reportBlocksInUse.adoc[`reportBlocksInUse`] 
| Write a report of currently allocated blocks to `ostream`.
| xref:BloombergLP/balst/StackTraceTestAllocator/setAllocationLimit.adoc[`setAllocationLimit`] 
| Set the allocation‐limit before an exception is thrown.
| xref:BloombergLP/balst/StackTraceTestAllocator/setDemanglingPreferredFlag.adoc[`setDemanglingPreferredFlag`] 
| Set whether demangling of symbols is preferred in diagnostics.
| xref:BloombergLP/balst/StackTraceTestAllocator/setFailureHandler.adoc[`setFailureHandler`] 
| Set the failure handler associated with this allocator to `func`.
| xref:BloombergLP/balst/StackTraceTestAllocator/setName.adoc[`setName`] 
| Set the name of this allocator to the specified `name`.
| xref:BloombergLP/balst/StackTraceTestAllocator/setOstream.adoc[`setOstream`] 
| Set the stream to which diagnostics will be written to the specified `ostream`. If `setOstream` is never called, diagnostics will be written to `bsl::cerr`.
|===


== Static Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/balst/StackTraceTestAllocator/failAbort.adoc[`failAbort`] 
| Call `bsl::abort()` to terminate the process on failure.
| xref:BloombergLP/balst/StackTraceTestAllocator/failNoop.adoc[`failNoop`] 
| Do nothing when invoked as a failure handler.
| xref:BloombergLP/bslma/Allocator/throwBadAlloc.adoc[`throwBadAlloc`] 
| Throw `std::bad_alloc` or abort the program.
|===


== 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 at least `bytes` with `alignment`.
| xref:BloombergLP/bslma/Allocator/do_deallocate.adoc[`do_deallocate`]  [.small]#[virtual]#
| Return the memory block at `p` having `bytes` and `alignment`.
| xref:BloombergLP/bslma/Allocator/do_is_equal.adoc[`do_is_equal`]  [.small]#[virtual]#
| Return whether this allocator can exchange memory with `other`.
|===



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