path: root/absl/base/internal/malloc_extension.h

//
// Copyright 2017 The Abseil Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

// Extra extensions exported by some malloc implementations.  These
// extensions are accessed through a virtual base class so an
// application can link against a malloc that does not implement these
// extensions, and it will get default versions that do nothing.
//
// NOTE FOR C USERS: If you wish to use this functionality from within
// a C program, see malloc_extension_c.h.

#ifndef ABSL_BASE_INTERNAL_MALLOC_EXTENSION_H_
#define ABSL_BASE_INTERNAL_MALLOC_EXTENSION_H_

#include <atomic>
#include <map>
#include <memory>
#include <vector>

#include <stddef.h>
#include <stdint.h>
#include <string>
#include "absl/base/macros.h"
#include "absl/base/port.h"
namespace absl {
namespace base_internal {

class MallocExtensionWriter;

// Interface to a pluggable system allocator.
class SysAllocator {
 public:
  SysAllocator() {
  }
  virtual ~SysAllocator();

  // Allocates "size"-byte of memory from system aligned with "alignment".
  // Returns null if failed. Otherwise, the returned pointer p up to and
  // including (p + actual_size -1) have been allocated.
  virtual void* Alloc(size_t size, size_t *actual_size, size_t alignment) = 0;

  // Get a human-readable description of the current state of the
  // allocator.  The state is stored as a null-terminated std::string in
  // a prefix of buffer.
  virtual void GetStats(char* buffer, int length);
};

// The default implementations of the following routines do nothing.
// All implementations should be thread-safe; the current ones
// (DebugMallocImplementation and TCMallocImplementation) are.
class MallocExtension {
 public:
  virtual ~MallocExtension();

  // Verifies that all blocks are valid.  Returns true if all are; dumps
  // core otherwise.  A no-op except in debug mode.  Even in debug mode,
  // they may not do any checking except with certain malloc
  // implementations.  Thread-safe.
  virtual bool VerifyAllMemory();

  // Verifies that p was returned by new, has not been deleted, and is
  // valid.  Returns true if p is good; dumps core otherwise.  A no-op
  // except in debug mode.  Even in debug mode, may not do any checking
  // except with certain malloc implementations.  Thread-safe.
  virtual bool VerifyNewMemory(const void* p);

  // Verifies that p was returned by new[], has not been deleted, and is
  // valid.  Returns true if p is good; dumps core otherwise.  A no-op
  // except in debug mode.  Even in debug mode, may not do any checking
  // except with certain malloc implementations.  Thread-safe.
  virtual bool VerifyArrayNewMemory(const void* p);

  // Verifies that p was returned by malloc, has not been freed, and is
  // valid.  Returns true if p is good; dumps core otherwise.  A no-op
  // except in debug mode.  Even in debug mode, may not do any checking
  // except with certain malloc implementations.  Thread-safe.
  virtual bool VerifyMallocMemory(const void* p);

  // If statistics collection is enabled, sets *blocks to be the number of
  // currently allocated blocks, sets *total to be the total size allocated
  // over all blocks, sets histogram[n] to be the number of blocks with
  // size between 2^n-1 and 2^(n+1), and returns true.  Returns false, and
  // does not change *blocks, *total, or *histogram, if statistics
  // collection is disabled.
  //
  // Note that these statistics reflect memory allocated by new, new[],
  // malloc(), and realloc(), but not mmap().  They may be larger (if not
  // all pages have been written to) or smaller (if pages have been
  // allocated by mmap()) than the total RSS size.  They will always be
  // smaller than the total virtual memory size.
  static constexpr int kMallocHistogramSize = 64;
  virtual bool MallocMemoryStats(int* blocks, size_t* total,
                                 int histogram[kMallocHistogramSize]);

  // Get a human readable description of the current state of the malloc
  // data structures.  The state is stored as a null-terminated std::string
  // in a prefix of "buffer[0,buffer_length-1]".
  // REQUIRES: buffer_length > 0.
  virtual void GetStats(char* buffer, int buffer_length);

  // Outputs to "writer" a sample of live objects and the stack traces
  // that allocated these objects. The output can be passed to pprof.
  virtual void GetHeapSample(MallocExtensionWriter* writer);

  // Outputs to "writer" the stack traces that caused growth in the
  // address space size. The output can be passed to "pprof".
  virtual void GetHeapGrowthStacks(MallocExtensionWriter* writer);

  // Outputs to "writer" a fragmentation profile. The output can be
  // passed to "pprof".  In particular, the result is a list of
  // <n,total,stacktrace> tuples that says that "total" bytes in "n"
  // objects are currently unusable because of fragmentation caused by
  // an allocation with the specified "stacktrace".
  virtual void GetFragmentationProfile(MallocExtensionWriter* writer);

  // -------------------------------------------------------------------
  // Control operations for getting and setting malloc implementation
  // specific parameters.  Some currently useful properties:
  //
  // generic
  // -------
  // "generic.current_allocated_bytes"
  //      Number of bytes currently allocated by application
  //      This property is not writable.
  //
  // "generic.heap_size"
  //      Number of bytes in the heap ==
  //            current_allocated_bytes +
  //            fragmentation +
  //            freed memory regions
  //      This property is not writable.
  //
  // tcmalloc
  // --------
  // "tcmalloc.max_total_thread_cache_bytes"
  //      Upper limit on total number of bytes stored across all
  //      per-thread caches.  Default: 16MB.
  //
  // "tcmalloc.current_total_thread_cache_bytes"
  //      Number of bytes used across all thread caches.
  //      This property is not writable.
  //
  // "tcmalloc.pageheap_free_bytes"
  //      Number of bytes in free, mapped pages in page heap.  These
  //      bytes can be used to fulfill allocation requests.  They
  //      always count towards virtual memory usage, and unless the
  //      underlying memory is swapped out by the OS, they also count
  //      towards physical memory usage.  This property is not writable.
  //
  // "tcmalloc.pageheap_unmapped_bytes"
  //      Number of bytes in free, unmapped pages in page heap.
  //      These are bytes that have been released back to the OS,
  //      possibly by one of the MallocExtension "Release" calls.
  //      They can be used to fulfill allocation requests, but
  //      typically incur a page fault.  They always count towards
  //      virtual memory usage, and depending on the OS, typically
  //      do not count towards physical memory usage.  This property
  //      is not writable.
  //
  //  "tcmalloc.per_cpu_caches_active"
  //      Whether tcmalloc is using per-CPU caches (1 or 0 respectively).
  //      This property is not writable.
  // -------------------------------------------------------------------

  // Get the named "property"'s value.  Returns true if the property
  // is known.  Returns false if the property is not a valid property
  // name for the current malloc implementation.
  // REQUIRES: property != null; value != null
  virtual bool GetNumericProperty(const char* property, size_t* value);

  // Set the named "property"'s value.  Returns true if the property
  // is known and writable.  Returns false if the property is not a
  // valid property name for the current malloc implementation, or
  // is not writable.
  // REQUIRES: property != null
  virtual bool SetNumericProperty(const char* property, size_t value);

  // Mark the current thread as "idle".  This routine may optionally
  // be called by threads as a hint to the malloc implementation that
  // any thread-specific resources should be released.  Note: this may
  // be an expensive routine, so it should not be called too often.
  //
  // Also, if the code that calls this routine will go to sleep for
  // a while, it should take care to not allocate anything between
  // the call to this routine and the beginning of the sleep.
  //
  // Most malloc implementations ignore this routine.
  virtual void MarkThreadIdle();

  // Mark the current thread as "busy".  This routine should be
  // called after MarkThreadIdle() if the thread will now do more
  // work.  If this method is not called, performance may suffer.
  //
  // Most malloc implementations ignore this routine.
  virtual void MarkThreadBusy();

  // Attempt to free any resources associated with cpu <cpu> (in the sense
  // of only being usable from that CPU.)  Returns the number of bytes
  // previously assigned to "cpu" that were freed.  Safe to call from
  // any processor, not just <cpu>.
  //
  // Most malloc implementations ignore this routine (known exceptions:
  // tcmalloc with --tcmalloc_per_cpu_caches=true.)
  virtual size_t ReleaseCPUMemory(int cpu);

  // Gets the system allocator used by the malloc extension instance. Returns
  // null for malloc implementations that do not support pluggable system
  // allocators.
  virtual SysAllocator* GetSystemAllocator();

  // Sets the system allocator to the specified.
  //
  // Users could register their own system allocators for malloc implementation
  // that supports pluggable system allocators, such as TCMalloc, by doing:
  //   alloc = new MyOwnSysAllocator();
  //   MallocExtension::instance()->SetSystemAllocator(alloc);
  // It's up to users whether to fall back (recommended) to the default
  // system allocator (use GetSystemAllocator() above) or not. The caller is
  // responsible to any necessary locking.
  // See tcmalloc/system-alloc.h for the interface and
  //     tcmalloc/memfs_malloc.cc for the examples.
  //
  // It's a no-op for malloc implementations that do not support pluggable
  // system allocators.
  virtual void SetSystemAllocator(SysAllocator *a);

  // Try to release num_bytes of free memory back to the operating
  // system for reuse.  Use this extension with caution -- to get this
  // memory back may require faulting pages back in by the OS, and
  // that may be slow.  (Currently only implemented in tcmalloc.)
  virtual void ReleaseToSystem(size_t num_bytes);

  // Same as ReleaseToSystem() but release as much memory as possible.
  virtual void ReleaseFreeMemory();

  // Sets the rate at which we release unused memory to the system.
  // Zero means we never release memory back to the system.  Increase
  // this flag to return memory faster; decrease it to return memory
  // slower.  Reasonable rates are in the range [0,10].  (Currently
  // only implemented in tcmalloc).
  virtual void SetMemoryReleaseRate(double rate);

  // Gets the release rate.  Returns a value < 0 if unknown.
  virtual double GetMemoryReleaseRate();

  // Returns the estimated number of bytes that will be allocated for
  // a request of "size" bytes.  This is an estimate: an allocation of
  // SIZE bytes may reserve more bytes, but will never reserve less.
  // (Currently only implemented in tcmalloc, other implementations
  // always return SIZE.)
  // This is equivalent to malloc_good_size() in OS X.
  virtual size_t GetEstimatedAllocatedSize(size_t size);

  // Returns the actual number N of bytes reserved by tcmalloc for the
  // pointer p.  This number may be equal to or greater than the
  // number of bytes requested when p was allocated.
  //
  // This routine is just useful for statistics collection.  The
  // client must *not* read or write from the extra bytes that are
  // indicated by this call.
  //
  // Example, suppose the client gets memory by calling
  //    p = malloc(10)
  // and GetAllocatedSize(p) returns 16.  The client must only use the
  // first 10 bytes p[0..9], and not attempt to read or write p[10..15].
  //
  // p must have been allocated by this malloc implementation, must
  // not be an interior pointer -- that is, must be exactly the
  // pointer returned to by malloc() et al., not some offset from that
  // -- and should not have been freed yet.  p may be null.
  // (Currently only implemented in tcmalloc; other implementations
  // will return 0.)
  virtual size_t GetAllocatedSize(const void* p);

  // Returns kOwned if this malloc implementation allocated the memory
  // pointed to by p, or kNotOwned if some other malloc implementation
  // allocated it or p is null.  May also return kUnknownOwnership if
  // the malloc implementation does not keep track of ownership.
  // REQUIRES: p must be a value returned from a previous call to
  // malloc(), calloc(), realloc(), memalign(), posix_memalign(),
  // valloc(), pvalloc(), new, or new[], and must refer to memory that
  // is currently allocated (so, for instance, you should not pass in
  // a pointer after having called free() on it).
  enum Ownership {
    // NOTE: Enum values MUST be kept in sync with the version in
    // malloc_extension_c.h
    kUnknownOwnership = 0,
    kOwned,
    kNotOwned
  };
  virtual Ownership GetOwnership(const void* p);

  // The current malloc implementation.  Always non-null.
  static MallocExtension* instance() {
    InitModuleOnce();
    return current_instance_.load(std::memory_order_acquire);
  }

  // Change the malloc implementation.  Typically called by the
  // malloc implementation during initialization.
  static void Register(MallocExtension* implementation);

  // Type used by GetProperties.  See comment on GetProperties.
  struct Property {
    size_t value;
    // Stores breakdown of the property value bucketed by object size.
    struct Bucket {
      size_t min_object_size;
      size_t max_object_size;
      size_t size;
    };
    // Empty unless detailed info was asked for and this type has buckets
    std::vector<Bucket> buckets;
  };

  // Type used by GetProperties.  See comment on GetProperties.
  enum StatLevel { kSummary, kDetailed };

  // Stores in *result detailed statistics about the malloc
  // implementation. *result will be a map keyed by the name of
  // the statistic. Each statistic has at least a "value" field.
  //
  // Some statistics may also contain an array of buckets if
  // level==kDetailed and the "value" can be subdivided
  // into different buckets for different object sizes.  If
  // such detailed statistics are not available, Property::buckets
  // will be empty.  Otherwise Property::buckets will contain
  // potentially many entries.  For each bucket b, b.value
  // will count the value contributed by objects in the range
  // [b.min_object_size, b.max_object_size].
  //
  // Common across malloc implementations:
  //  generic.bytes_in_use_by_app  -- Bytes currently in use by application
  //  generic.physical_memory_used -- Overall (including malloc internals)
  //  generic.virtual_memory_used  -- Overall (including malloc internals)
  //
  // Tcmalloc specific properties
  //  tcmalloc.cpu_free            -- Bytes in per-cpu free-lists
  //  tcmalloc.thread_cache_free   -- Bytes in per-thread free-lists
  //  tcmalloc.transfer_cache      -- Bytes in cross-thread transfer caches
  //  tcmalloc.central_cache_free  -- Bytes in central cache
  //  tcmalloc.page_heap_free      -- Bytes in page heap
  //  tcmalloc.page_heap_unmapped  -- Bytes in page heap (no backing phys. mem)
  //  tcmalloc.metadata_bytes      -- Used by internal data structures
  //  tcmalloc.thread_cache_count  -- Number of thread caches in use
  //
  // Debug allocator
  //  debug.free_queue             -- Recently freed objects
  virtual void GetProperties(StatLevel level,
                             std::map<std::string, Property>* result);
 private:
  static MallocExtension* InitModule();

  static void InitModuleOnce() {
    // Pointer stored here so heap leak checker will consider the default
    // instance reachable, even if current_instance_ is later overridden by
    // MallocExtension::Register().
    ABSL_ATTRIBUTE_UNUSED static MallocExtension* default_instance =
        InitModule();
  }

  static std::atomic<MallocExtension*> current_instance_;
};

// Base class than can handle output generated by GetHeapSample() and
// GetHeapGrowthStacks().  Use the available subclass or roll your
// own.  Useful if you want explicit control over the type of output
// buffer used (e.g. IOBuffer, Cord, etc.)
class MallocExtensionWriter {
 public:
  virtual ~MallocExtensionWriter() {}
  virtual void Write(const char* buf, int len) = 0;
 protected:
  MallocExtensionWriter() {}
  MallocExtensionWriter(const MallocExtensionWriter&) = delete;
  MallocExtensionWriter& operator=(const MallocExtensionWriter&) = delete;
};

// A subclass that writes to the std::string "out".  NOTE: The generated
// data is *appended* to "*out".  I.e., the old contents of "*out" are
// preserved.
class StringMallocExtensionWriter : public MallocExtensionWriter {
 public:
  explicit StringMallocExtensionWriter(std::string* out) : out_(out) {}
  virtual void Write(const char* buf, int len) {
    out_->append(buf, len);
  }

 private:
  std::string* const out_;
  StringMallocExtensionWriter(const StringMallocExtensionWriter&) = delete;
  StringMallocExtensionWriter& operator=(const StringMallocExtensionWriter&) =
      delete;
};

}  // namespace base_internal
}  // namespace absl

// The nallocx function allocates no memory, but it performs the same size
// computation as the malloc function, and returns the real size of the
// allocation that would result from the equivalent malloc function call.
// Default weak implementation returns size unchanged, but tcmalloc overrides it
// and returns rounded up size. See the following link for details:
// http://www.unix.com/man-page/freebsd/3/nallocx/
extern "C" size_t nallocx(size_t size, int flags);

#ifndef MALLOCX_LG_ALIGN
#define MALLOCX_LG_ALIGN(la) (la)
#endif

#endif  // ABSL_BASE_INTERNAL_MALLOC_EXTENSION_H_