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

This class defines a concrete &quot;test&quot; allocator mechanism that implements the `bdlma&colon;&colon;ManagedAllocator` protocol&period;

== Synopsis

Declared in `&lt;balst&lowbar;stacktracetestallocator&period;h&gt;`

[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&period; At any time it can produce a report about such blocks, listing for each place that any unfreed blocks were allocated &ast; the number of unfreed blocks allocated at that place &ast; the stack trace at that place The allocator will also detect redundant frees of the same block, and frees by the wrong allocator&period; The client can choose whether such violations are handled by a core dump, or merely a report being written&period;

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

== Base Classes

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

== 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&period;
| xref:BloombergLP/bslma/Allocator/size_type.adoc[`size&lowbar;type`] 
| Alias for an unsigned integral type capable of representing the number of bytes in this platform&apos;s virtual address space&period;
|===


== Member Functions

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


== Static Member Functions

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


== Protected Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslma/Allocator/do_allocate.adoc[`do&lowbar;allocate`]  [.small]#[virtual]#
| Return a newly allocated block of at least `bytes` with `alignment`&period;
| xref:BloombergLP/bslma/Allocator/do_deallocate.adoc[`do&lowbar;deallocate`]  [.small]#[virtual]#
| Return the memory block at `p` having `bytes` and `alignment`&period;
| xref:BloombergLP/bslma/Allocator/do_is_equal.adoc[`do&lowbar;is&lowbar;equal`]  [.small]#[virtual]#
| Return whether this allocator can exchange memory with `other`&period;
|===



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