Seastar
High performance C++ framework for concurrent servers
|
Low-level memory management support
The memory
namespace provides functions and classes for interfacing with the seastar memory allocator.
The seastar memory allocator splits system memory into a pool per logical core (lcore). Memory allocated one an lcore should be freed on the same lcore; failing to do so carries a severe performance penalty. It is possible to share memory with another core, but this should be limited to avoid cache coherency traffic. You can obtain the memory layout of the current shard with get_memory_layout().
Seastar supports marking scopes as critical allocation scopes for the purpose of special treatment from various memory related utilities. See scoped_critical_alloc_section.
Allows injecting allocation failures for testing resiliency against allocation failures, or exceptions in general. See:
Large allocations put great pressure on the allocator which might be unable to serve them even if there is enough memory available, due to memory fragmentation. This is especially relevant for long-running applications, the kind of applications that are typically built with seastar. This feature allows finding these large by logging a warning on large allocations, with the stacktrace of the. See:
Heap profiling allows finding out how memory is used by your application, by recording the stacktrace of a sampled subset (or all) allocations. See:
Often, the best way to debug an allocation failure is a coredump. This feature allows dumping core on allocation failures, containing the stack of the failed allocation, by means of aborting. To enable this behavior, set abort_on_seastar_bad_alloc
in reactor_options
or pass the --abort-on-seastar-bad-alloc
command line flag. Additionally, applications may enable or disable this functionality globally at runtime by calling set_abort_on_allocation_failure()
.
Dump a diagnostic report of the state of the seastar allocator upon allocation failure. The report is dumped with the seastar_memory
logger, with debug level. You can configure a report to be dumped with error level on certain allocation kinds, see:
The diagnostics report dump can be configured with the command line/configuration file via the dump-memory-diagnostics-on-alloc-failure-kind
command-line flag/configuration item.
Classes | |
class | alloc_failure_injector |
struct | allocation_site |
Describes an allocation location in the code. More... | |
struct | disable_failure_guard |
struct | memory_layout |
struct | scoped_critical_alloc_section |
class | scoped_heap_profiling |
Enable heap profiling for the duration of the scope. More... | |
class | scoped_large_allocation_warning_disable |
Disable large allocation warnings for a scope. More... | |
class | scoped_large_allocation_warning_threshold |
Set a different large allocation warning threshold for a scope. More... | |
class | statistics |
Memory allocation statistics. More... | |
Typedefs | |
using | memory_diagnostics_writer = noncopyable_function< void(std::string_view)> |
A functor which writes its argument into the diagnostics report. | |
Enumerations | |
enum class | alloc_failure_kind { none , critical , all } |
The kind of allocation failures to dump diagnostics report for. More... | |
Functions | |
void | set_abort_on_allocation_failure (bool enabled) |
Set the global state of the abort on allocation failure behavior. More... | |
bool | is_abort_on_allocation_failure () |
Determine the abort on allocation failure mode. More... | |
statistics | stats () |
Capture a snapshot of memory allocation statistics for this lcore. | |
memory::memory_layout | get_memory_layout () |
size_t | free_memory () |
Returns the size of free memory in bytes. | |
size_t | min_free_memory () |
void | set_min_free_pages (size_t pages) |
Sets the value of free memory low water mark in memory::page_size units. | |
void | set_large_allocation_warning_threshold (size_t threshold) |
size_t | get_large_allocation_warning_threshold () |
Gets the current large allocation warning threshold. | |
void | disable_large_allocation_warning () |
Disable large allocation warnings. | |
std::vector< allocation_site > | sampled_memory_profile () |
If memory sampling is on returns the current sampled memory live set. More... | |
size_t | sampled_memory_profile (allocation_site *output, size_t size) |
Copies the current sampled set of allocation_sites into the array pointed to by the output parameter. More... | |
void | set_heap_profiling_sampling_rate (size_t sample_rate) |
Enable sampled heap profiling by setting a sample rate. More... | |
size_t | get_heap_profiling_sample_rate () |
Returns the current heap profiling sampling rate (0 means off) More... | |
alloc_failure_injector & | local_failure_injector () |
Return the shard-local alloc_failure_injector instance. | |
void | on_alloc_point () |
Marks a point in code which should be considered for failure injection. | |
void | with_allocation_failures (noncopyable_function< void()> func) |
bool | is_critical_alloc_section () |
void | set_dump_memory_diagnostics_on_alloc_failure_kind (alloc_failure_kind) |
Configure when memory diagnostics are dumped. More... | |
void | set_dump_memory_diagnostics_on_alloc_failure_kind (std::string_view) |
Configure when memory diagnostics are dumped. More... | |
void | set_additional_diagnostics_producer (noncopyable_function< void(memory_diagnostics_writer)> producer) |
Set a producer of additional diagnostic information. More... | |
sstring | generate_memory_diagnostics_report () |
struct seastar::memory::disable_failure_guard |
Class Members | ||
---|---|---|
scoped_critical_alloc_section | cs |
struct seastar::memory::scoped_critical_alloc_section |
|
strong |
The kind of allocation failures to dump diagnostics report for.
Note that if the seastar_memory logger is set to level debug, there will be a report dumped for any allocation failure, regardless of this configuration.
Enumerator | |
---|---|
none | Dump diagnostic error report for none of the allocation failures. |
critical | Dump diagnostic error report for critical allocation failures, see scoped_critical_alloc_section. |
all | Dump diagnostic error report for all the allocation failures. |
sstring seastar::memory::generate_memory_diagnostics_report | ( | ) |
Generate and return a diagnostics report as a string.
Note that contrary to the automated report generation (triggered by allocation failure), this method does allocate memory and can fail in low-memory conditions.
size_t seastar::memory::get_heap_profiling_sample_rate | ( | ) |
Returns the current heap profiling sampling rate (0 means off)
bool seastar::memory::is_abort_on_allocation_failure | ( | ) |
Determine the abort on allocation failure mode.
Return true if the global abort on allocation failure behavior is enabled, or false otherwise. Always returns false if the default (system) allocator is being used.
size_t seastar::memory::min_free_memory | ( | ) |
Returns the value of free memory low water mark in bytes. When free memory is below this value, reclaimers are invoked until it goes above again.
std::vector< allocation_site > seastar::memory::sampled_memory_profile | ( | ) |
If memory sampling is on returns the current sampled memory live set.
If there is tracked allocations (because heap profiling was on earlier) these will still be returned if heap profiling is now off
size_t seastar::memory::sampled_memory_profile | ( | allocation_site * | output, |
size_t | size | ||
) |
Copies the current sampled set of allocation_sites into the array pointed to by the output parameter.
Copies up to size
elements of the current sampled set of allocation sites into the output array, which must have length at least size
.
Returns amount of copied elements. This method does not allocate so it is a useful alternative to sampled_memory_profile() when one wants to avoid allocating (e.g.: under OOM conditions).
output | array to copy the allocation sites to |
size | the size of the array pointed to by output |
void seastar::memory::set_abort_on_allocation_failure | ( | bool | enabled | ) |
Set the global state of the abort on allocation failure behavior.
If enabled, an allocation failure (i.e., the requested memory could not be allocated even after reclaim was attempted), will generally result in abort()
being called. If disabled, the failure is reported to the caller, e.g., by throwing a std::bad_alloc
for C++ allocations such as new, or returning a null pointer from malloc.
Note that even if the global state is set to enabled, the disable_abort_on_alloc_failure_temporarily
class may override the behavior tepmorarily on a given shard. That is, abort only occurs if abort is globablly enabled on this shard and there are no disable_abort_on_alloc_failure_temporarily
objects currently alive on this shard.
void seastar::memory::set_additional_diagnostics_producer | ( | noncopyable_function< void(memory_diagnostics_writer)> | producer | ) |
Set a producer of additional diagnostic information.
This allows the application running on top of seastar to add its own part to the diagnostics dump. The application can supply higher level diagnostics information, that might help explain how the memory was consumed.
The application specific part will be added just below the main stats (free/used/total memory).
producer | - the functor to produce the additional diagnostics, specific to the application, to be added to the generated report. The producer is passed a writer functor, which it can use to add its parts to the report. |
void seastar::memory::set_dump_memory_diagnostics_on_alloc_failure_kind | ( | alloc_failure_kind | ) |
Configure when memory diagnostics are dumped.
See alloc_failure_kind on available options. Applies configuration on all shards.
void seastar::memory::set_dump_memory_diagnostics_on_alloc_failure_kind | ( | std::string_view | ) |
Configure when memory diagnostics are dumped.
String version. See alloc_failure_kind on available options. Applies configuration on all shards.
void seastar::memory::set_heap_profiling_sampling_rate | ( | size_t | sample_rate | ) |
Enable sampled heap profiling by setting a sample rate.
sample_rate | the sample rate to use. Disable heap profiling by setting the sample rate to 0 |
In order to use heap profiling you have to define SEASTAR_HEAPPROF
.
Use sampled_memory_profile for API access to profiling data
Note: Changing the sampling rate while previously sampled allocations are still alive can lead to inconsistent results of their reported size (i.e.: their size will be over or under reported). Undefined behavior or memory corruption will not occur.
For an example script that makes use of the heap profiling data see [scylla-gdb.py] (https://github.com/scylladb/scylla/blob/e1b22b6a4c56b4f1d0adf65d1a11db4bcb51fe7d/scylla-gdb.py#L1439) This script can generate either textual representation of the data, or a zoomable flame graph (flame graph generation instructions, example flame graph).
void seastar::memory::set_large_allocation_warning_threshold | ( | size_t | threshold | ) |
Enable the large allocation warning threshold.
Warn when allocation above a given threshold are performed.
threshold | size (in bytes) above which an allocation will be logged |
void seastar::memory::with_allocation_failures | ( | noncopyable_function< void()> | func | ) |
Repeatedly run func with allocation failures
Initially, allocations start to fail immediately. In each subsequent run the failures start one allocation later. This returns when func is run and no allocation failures are detected.