[#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, and 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;

== 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

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]`
| This protocol class extends `bslma&colon;&colon;Allocator` for allocators with the ability to `release` all memory currently allocated through the protocol back to the memory supplier of the derived concrete allocator object&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; Note that this can be set and accessed using the `setFailureHandler` and `failureHandler` methods respectively&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; Report any memory leaks to the `ostream` that was supplied at construction&period; If no memory leaks are observed, nothing is written to the output `ostream`&period; Call the failure handler if `numBlocksInUse() &gt; 0`&period; Note that a report of outstanding memory blocks is written to `ostream` before the failure handler is called, and if the failure handler returns, all outstanding memory blocks will be released&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; If `size` is 0, a null pointer is returned with no other other effect&period; Otherwise, invoke the `allocate` method of the allocator supplied at construction and record the returned block in order to be able to report leaked blocks upon destruction&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; If `address` is 0, this function has no effect&period; Otherwise, if the memory at `address` is consistent with being allocated from this test allocator, deallocate it using the underlying allocator and delete it from the data structures keeping track of blocks in use&apos;&period; If `address` is not zero and is not the address of a block allocated with this allocator (or if it is being deallocated a second time), write an error message and call the failure handler&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; Note that this does not count allocations of 0 length, which return null pointers&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 to the specified `ostream`, reporting the unique call&hyphen;stacks for each block that has been allocated and has not yet been freed&period; If `ostream` is not specified, the value of `ostream` passed to the last call to `setOstream` will be used&period; If `setOstream` was never called, `bsl&colon;&colon;cerr` will be used&period;
| xref:BloombergLP/balst/StackTraceTestAllocator/setAllocationLimit.adoc[`setAllocationLimit`] 
| Set the number of valid allocation requests before an exception is to be thrown for this allocator to the specified `limit`&period; If `limit` is less than 0, no exception is to be thrown&period; By default, no exception is scheduled&period;
| xref:BloombergLP/balst/StackTraceTestAllocator/setDemanglingPreferredFlag.adoc[`setDemanglingPreferredFlag`] 
| Set the `demanglingPreferredFlag` attribute, which is used to determine whether demangling of symbols is to be attempted when generating diagnostics, to the specified `value`&period; The default value of the flag is `true`&period; However the flag is ignored on some platforms&semi; demangling never happens on some platforms and always happens on others&period;
| xref:BloombergLP/balst/StackTraceTestAllocator/setFailureHandler.adoc[`setFailureHandler`] 
| Set the failure handler associated with this allocator object to the specified `func`&period; Upon construction, the function `failAbort` is associated with this object by default&period; Note that `func` will be called by this object&apos;s destructor if memory is leaked, so it is important that it not throw&period; Note that in ALL failure situations, errors or warnings will be written to the `ostream` associated with this object prior to the call to the failure handler&period;
| xref:BloombergLP/balst/StackTraceTestAllocator/setName.adoc[`setName`] 
| Set the name of this allocator to the specified `name`&period; If `setName` is never called, the name of the allocator is &quot;&lt;unnamed&gt;&quot;&period; Note that the lifetime of `name` must exceed the lifetime of this object&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`] 
| Calls `bsl&colon;&colon;abort()`, `d&lowbar;failureHandler` is initialized to this value by all constructors&period; Note that in ALL failure situations, errors or warnings will be written to the `ostream` associated with this object prior to the failure handler call&period;
| xref:BloombergLP/balst/StackTraceTestAllocator/failNoop.adoc[`failNoop`] 
| Does nothing&period; `setFailureHandler` may be called with this function, in which case this allocator object, when a failure occurs, will recover rather than abort&period; Note that in ALL failure situations, errors or warnings will be written to the `ostream` associated with this object prior to the failure handler call&period;
| xref:BloombergLP/bslma/Allocator/throwBadAlloc.adoc[`throwBadAlloc`] 
| Throw `std&colon;&colon;bad&lowbar;alloc` if exceptions are enabled or abort the program otherwise&period; Derived classes and helper functions will typically call this function when they are unable to satisfy an allocation request&period; This function never returns&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 memory of (at least) the specified positive `bytes` and having at least the specified `alignment`&period; Unless overriden in a derived class, the return value is `this&hyphen;&gt;allocate(bytes)`&period; If this allocator cannot return the requested number of bytes or cannot satisfy the alignment request, then it will throw a `std&colon;&colon;bad&lowbar;alloc` exception in an exception&hyphen;enabled build, or else will abort the program in a non&hyphen;exception build&period; 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&period; Note that if `bytes` is `0`, the same non&hyphen;null value will be returned every time&period;
| xref:BloombergLP/bslma/Allocator/do_deallocate.adoc[`do&lowbar;deallocate`]  [.small]#[virtual]#
| Return the memory block at the specified `p` address, having the specified `bytes` and specified `alignment`, back to this allocator&period; 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`&period; The behavior is undefined unless `address` is a block allocated from this allocator object using the same `bytes` and `alignment` and not already deallocated&period;
| xref:BloombergLP/bslma/Allocator/do_is_equal.adoc[`do&lowbar;is&lowbar;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&semi; otherwise return `false`&period; Unless overriden, this method returns `this &equals;&equals; &amp;other`&period;
|===



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