C API

The stable C ABI in tensorflow/c/. Every other-language binding (Java, Go, Rust, Haskell, Node, …) links against libtensorflow.so and uses these headers.

Purpose

• Provide a stable, plain-C interface to the TensorFlow runtime.
• Expose graph construction, session execution, eager execution, kernel registration, and tensor manipulation.
• Be ABI-stable across minor releases so language bindings don't break on upgrades.

Directory layout

tensorflow/c/
├── c_api.h                     # Graph + Session + base operations
├── c_api.cc
├── c_api_experimental.h        # Newer / unstable additions
├── c_api_experimental.cc
├── c_api_function.{h,cc}       # Function (FuncGraph) operations
├── eager/                      # Eager-mode TFE_* APIs
├── kernels.h / kernels.cc      # User-defined kernel registration via C
├── ops.h / ops.cc              # User-defined op registration via C
├── tf_tensor.{h,cc}            # TF_Tensor type
├── tf_status.{h,cc}            # TF_Status type
├── tf_datatype.{h,cc}          # TF_DataType
├── tf_buffer.{h,cc}            # TF_Buffer (raw byte buffer wrapper)
├── tf_shape.{h,cc}             # TF_Shape
├── tf_tstring.{h,cc}           # tstring helpers (TF's variable-length string)
├── tf_status_helper.{h,cc}     # C++→C Status conversion
└── experimental/               # Optional / unstable areas (e.g. saved_model loader)

tensorflow/c/eager/ mirrors the C API surface for eager execution: TFE_Context, TFE_TensorHandle, TFE_Op, TFE_Execute.

Key abstractions

Type	Header	Description
TF_Status	tensorflow/c/tf_status.h	Carries error codes + messages.
TF_Tensor	tensorflow/c/tf_tensor.h	Owns or borrows a tensor's data.
TF_DataType	tensorflow/c/tf_datatype.h	Enum mirroring tensorflow::DataType.
TF_Graph	tensorflow/c/c_api.h	A mutable graph being built.
TF_Operation	tensorflow/c/c_api.h	An op node in TF_Graph.
TF_OperationDescription	tensorflow/c/c_api.h	Builder for a TF_Operation.
TF_Session	tensorflow/c/c_api.h	Graph-mode session (legacy but still used).
TFE_Context	tensorflow/c/eager/c_api.h	Eager runtime context.
TFE_TensorHandle	tensorflow/c/eager/c_api.h	Handle to an eager tensor (may be on device).
TFE_Op	tensorflow/c/eager/c_api.h	Builder for an eager op invocation.
TF_Buffer	tensorflow/c/tf_buffer.h	Raw byte buffer (used to pass GraphDefs).

How it works

The C API is a thin wrapper over the C++ runtime. Each TF_* opaque type holds a std::unique_ptr to its C++ counterpart in the .cc file. Errors are reported by mutating a passed-in TF_Status*.

sequenceDiagram
    participant App as App (e.g. Java/Go binding)
    participant CAPI as C API (libtensorflow.so)
    participant Runtime as C++ Core Runtime
    participant Kernel as Op kernel

    App->>CAPI: TFE_NewContext(opts, status)
    CAPI->>Runtime: new tensorflow::EagerContext(...)
    App->>CAPI: TFE_NewOp("MatMul", status); TFE_OpAddInput(...); TFE_Execute(...)
    CAPI->>Runtime: EagerContext::Execute(op_def, inputs)
    Runtime->>Kernel: ResolveKernel + Compute()
    Kernel-->>Runtime: outputs
    Runtime-->>CAPI: TFE_TensorHandle*
    CAPI-->>App: TFE_TensorHandle*

For graph-mode use, TF_NewGraph() produces a TF_Graph, ops are added with TF_OperationDescription builders, and a TF_Session is created over the graph. TF_SessionRun mirrors Session::Run in C++.

Stability promises

• Public functions in c_api.h are part of the stable ABI; symbols are listed in tensorflow/c/exported_symbols.lds.
• c_api_experimental.h and the contents of tensorflow/c/experimental/ are explicitly not stable — they may break across minor releases.
• The eager API in tensorflow/c/eager/c_api.h is treated as stable in practice but historically had TFE_*Experimental* markers; check the function name prefix.

Integration points

• Used by: tensorflow/java/, tensorflow/go/, every other-language repo (TFJS converter, Rust bindings, etc.).
• Used by Python: less than you'd expect. Python uses pybind11 in tensorflow/python/ to talk to C++ directly for performance. The C API is mostly used by Python for the SavedModel loader (tensorflow/c/experimental/saved_model/) and a few helpers.
• Symbols exported: see tensorflow/c/exported_symbols.lds and the version script tensorflow/c/version_script.lds for the linker-controlled surface.

Entry points for modification

• New top-level operations — usually you don't add to c_api.h directly. Add an OpDef and let bindings call it through the existing TFE_Op / TF_OperationDescription machinery.
• New stable function — add to c_api.h and the corresponding exported_symbols.lds. Updates here are rare and require ABI review.
• Fixes to the eager API — tensorflow/c/eager/, then make sure the Java/Go/JS bindings still build.

Related

• java-api, go-api — bindings that ride this surface.
• python-api — Python bypasses the C API for most paths; here's where it doesn't.
• systems/eager-execution — the C++ runtime backing TFE_*.