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

== Synopsis

Declared in `<balst_stacktracetestallocator.h>`

[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_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]`
| This protocol class extends `bslma::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.
|===

== 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. Note that this can be set and accessed using the `setFailureHandler` and `failureHandler` methods respectively.
| 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. Report any memory leaks to the `ostream` that was supplied at construction. If no memory leaks are observed, nothing is written to the output `ostream`. Call the failure handler if `numBlocksInUse() > 0`. 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.
| 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). If `size` is 0, a null pointer is returned with no other other effect. 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.
| 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. If `address` is 0, this function has no effect. 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'. 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.
| 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. Note that this does not count allocations of 0 length, which return null pointers.
| 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 to the specified `ostream`, reporting the unique call‐stacks for each block that has been allocated and has not yet been freed. If `ostream` is not specified, the value of `ostream` passed to the last call to `setOstream` will be used. If `setOstream` was never called, `bsl::cerr` will be used.
| 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`. If `limit` is less than 0, no exception is to be thrown. By default, no exception is scheduled.
| 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`. The default value of the flag is `true`. However the flag is ignored on some platforms; demangling never happens on some platforms and always happens on others.
| xref:BloombergLP/balst/StackTraceTestAllocator/setFailureHandler.adoc[`setFailureHandler`] 
| Set the failure handler associated with this allocator object to the specified `func`. Upon construction, the function `failAbort` is associated with this object by default. Note that `func` will be called by this object's destructor if memory is leaked, so it is important that it not throw. 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.
| xref:BloombergLP/balst/StackTraceTestAllocator/setName.adoc[`setName`] 
| Set the name of this allocator to the specified `name`. If `setName` is never called, the name of the allocator is "<unnamed>". Note that the lifetime of `name` must exceed the lifetime of this object.
| 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`] 
| Calls `bsl::abort()`, `d_failureHandler` is initialized to this value by all constructors. 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.
| xref:BloombergLP/balst/StackTraceTestAllocator/failNoop.adoc[`failNoop`] 
| Does nothing. `setFailureHandler` may be called with this function, in which case this allocator object, when a failure occurs, will recover rather than abort. 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.
| 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]#