MallocTrim.h

#pragma once
 
#include <xrpl/beast/utility/Journal.h>
 
#include <chrono>
#include <cstdint>
#include <string_view>
 
namespace xrpl {
 
// cSpell:ignore ptmalloc
 
// -----------------------------------------------------------------------------
// Allocator interaction note:
// - This facility invokes glibc's malloc_trim(0) on Linux/glibc to request that
//   ptmalloc return free heap pages to the OS.
// - If an alternative allocator (e.g. jemalloc or tcmalloc) is linked or
//   preloaded (LD_PRELOAD), calling glibc's malloc_trim typically has no effect
//   on the *active* heap. The call is harmless but may not reclaim memory
//   because those allocators manage their own arenas.
// - Only glibc sbrk/arena space is eligible for trimming; large mmap-backed
//   allocations are usually returned to the OS on free regardless of trimming.
// - Call at known reclamation points (e.g., after cache sweeps / online delete)
//   and consider rate limiting to avoid churn.
// -----------------------------------------------------------------------------
 
struct MallocTrimReport
{
    bool supported{false};
    int trimResult{-1};
    std::int64_t rssBeforeKB{-1};
    std::int64_t rssAfterKB{-1};
    std::chrono::microseconds durationUs{-1};
    std::int64_t minfltDelta{-1};
    std::int64_t majfltDelta{-1};
 
    [[nodiscard]] std::int64_t
    deltaKB() const noexcept
    {
        if (rssBeforeKB < 0 || rssAfterKB < 0)
            return 0;
        return rssAfterKB - rssBeforeKB;
    }
};
 
MallocTrimReport
mallocTrim(std::string_view tag, beast::Journal journal);
 
}  // namespace xrpl