ceph/src/jaegertracing/opentelemetry-cpp/docs/abi-policy.md

   1 # Application Binary Interface (ABI) Policy
   2
   3 To support scenarios where OpenTelemetry implementations are deployed as binary
   4 plugins, certain restrictions are imposed on portions of the OpenTelemetry API.
   5
   6 Many parts of the C++ standard library don't have well-defined ABIs. To ensure
   7 that a plugin compiled against one version of the C++ standard library can work
   8 with an application or library compiled against a different version of the C++
   9 standard library, we limit a portion of the OpenTelemetry API to use ABI stable
  10 types.
  11
  12 In the areas of the API where we need ABI stability, we use C++ as an extended
  13 C. We assume that standard language features like inheritance follow a
  14 consistent ABI (vtable layouts, for example, are specified by the [Itanium
  15 ABI](https://itanium-cxx-abi.github.io/cxx-abi/abi.html#vtable)) and can be used
  16 across compilers, but don't rely on the ABI stability of the C++ standard
  17 library classes.
  18
  19 ABI stability is not provided by the interfaces the SDK provides as
  20 implementation hooks to vendor implementors, like exporters, processors,
  21 aggregators and propagators.
  22
  23 These are some of the rules for where ABI stability is required.
  24
  25 Note: This assumes export maps are used to properly control symbol resolution.
  26
  27 1. Abstract classes in the OpenTelemetry API must use ABI stable types in their
  28    virtual function signatures. Example
  29
  30 ```cpp
  31 class Tracer {
  32 public:
  33   ...
  34
  35   // Bad: std::string doesn't have a well-defined ABI.
  36   virtual void f(const std::string& s);
  37
  38   // OK: We provide a ABI stable string_view type.
  39   virtual void f(nostd::string_view s);
  40
  41   // OK: g is non-virtual function.
  42   void g(const std::vector<int>& v);
  43   ...
  44 };
  45 ```
  46
  47 The ABI restrictions don't apply to concrete classes.
  48
  49 ```cpp
  50 class TracerImpl final : public Tracer {
  51 public:
  52   // ...
  53 private:
  54   std::string s; // OK
  55 };
  56 ```
  57
  58 Singletons defined by the OpenTelemetry API must use ABI stable types since they
  59 could potentially be shared across multiple instrumented dynamic shared objects
  60 (DSOs) compiled against different versions of the C++ standard library.