Skip to content

Latest commit

 

History

History
44 lines (39 loc) · 2.52 KB

compatibility.md

File metadata and controls

44 lines (39 loc) · 2.52 KB
Raw

TCMalloc Compatibility Guidelines

This document details what we expect from well-behaved users. Any usage of TCMalloc libraries outside of these technical boundaries may result in breakage when upgrading to newer versions of TCMalloc.

Put another way: don't do things that make TCMalloc API maintenance tasks harder. If you misuse TCMalloc APIs, you're on your own.

Additionally, because TCMalloc depends on Abseil, Abseil's compatibility guidelines also apply.

What Users Must (And Must Not) Do

  • Do not depend on a compiled representation of TCMalloc. We do not promise any ABI compatibility — we intend for TCMalloc to be built from source, hopefully from head. The internal layout of our types may change at any point, without notice. Building TCMalloc in the presence of different C++ standard library types may change Abseil types, especially for pre-adopted types (string_view, variant, etc) — these will become typedefs and their ABI will change accordingly.
  • Do not rely on dynamic loading/unloading. TCMalloc does not support dynamic loading and unloading.
  • You may not open namespace tcmalloc. You are not allowed to define additional names in namespace tcmalloc, nor are you allowed to specialize anything we provide.
  • You may not depend on the signatures of TCMalloc APIs. You cannot take the address of APIs in TCMalloc (that would prevent us from adding overloads without breaking you). You cannot use metaprogramming tricks to depend on those signatures either. (This is also similar to the restrictions in the C++ standard.)
  • You may not forward declare TCMalloc APIs. This is actually a sub-point of "do not depend on the signatures of TCMalloc APIs" as well as "do not open namespace tcmalloc", but can be surprising. Any refactoring that changes template parameters, default parameters, or namespaces will be a breaking change in the face of forward-declarations.
  • Do not depend upon internal details. This should go without saying: if something is in a namespace or filename/path that includes the word "internal", you are not allowed to depend upon it. It's an implementation detail. You cannot friend it, you cannot include it, you cannot mention it or refer to it in any way.
  • Include What You Use. We may make changes to the internal #include graph for TCMalloc headers - if you use an API, please include the relevant header file directly.