Files
pytorch/docs/cpp/source/api/stable/registration.md
T
Svetlana Karslioglu 19da3da3d3 Restructure C++ docs (#174096)
The fix-cpp-build branch is a major restructuring that:

- Drops Exhale (which auto-generated API docs but caused OOM in CI) in favor of hand-written RST pages using Breathe directives
- Reorganizes notes into a hierarchical API reference with proper categories
- Adds new content: XPU docs, stable ABI docs, DeviceGuard/Stream docs
- Always runs Doxygen instead of gating on an env var

Pull Request resolved: https://github.com/pytorch/pytorch/pull/174096
Approved by: https://github.com/janeyx99, https://github.com/seemethere, https://github.com/albanD
2026-04-07 17:24:38 +00:00

3.3 KiB

myst
myst
html_meta
description keywords
Stable ABI registration macros in PyTorch C++ — STABLE_TORCH_LIBRARY, STABLE_TORCH_LIBRARY_IMPL, and TORCH_BOX. PyTorch, C++, stable ABI, STABLE_TORCH_LIBRARY, TORCH_BOX, macro, registration

Library Registration Macros

These macros provide stable ABI equivalents of the standard PyTorch operator registration macros (TORCH_LIBRARY, TORCH_LIBRARY_IMPL, etc.). Use these when building custom operators that need to maintain binary compatibility across PyTorch versions.

STABLE_TORCH_LIBRARY


Defines a library of operators in a namespace using the stable ABI.

This is the stable ABI equivalent of {c:macro}`TORCH_LIBRARY`.
Use this macro to define operator schemas that will maintain
binary compatibility across PyTorch versions. Only one `STABLE_TORCH_LIBRARY`
block can exist per namespace; use `STABLE_TORCH_LIBRARY_FRAGMENT` for
additional definitions in the same namespace from different translation units.

:param ns: The namespace in which to define operators (e.g., `mylib`).
:param m: The name of the StableLibrary variable available in the block.

**Example:**

```cpp
STABLE_TORCH_LIBRARY(mylib, m) {
    m.def("my_op(Tensor input, int size) -> Tensor");
    m.def("another_op(Tensor a, Tensor b) -> Tensor");
}

Minimum compatible version: PyTorch 2.9.

## STABLE_TORCH_LIBRARY_IMPL

```{c:macro} STABLE_TORCH_LIBRARY_IMPL(ns, k, m)

Registers operator implementations for a specific dispatch key using the stable ABI.

This is the stable ABI equivalent of `TORCH_LIBRARY_IMPL`. Use this macro
to provide implementations of operators for a specific dispatch key (e.g.,
CPU, CUDA) while maintaining binary compatibility across PyTorch versions.

All kernel functions registered with this macro must be boxed using
the `TORCH_BOX` macro.

:param ns: The namespace in which the operators are defined. :param k: The dispatch key (e.g., CPU, CUDA). :param m: The name of the StableLibrary variable available in the block.

Example:

STABLE_TORCH_LIBRARY_IMPL(mylib, CPU, m) {
    m.impl("my_op", TORCH_BOX(&my_cpu_kernel));
}

STABLE_TORCH_LIBRARY_IMPL(mylib, CUDA, m) {
    m.impl("my_op", TORCH_BOX(&my_cuda_kernel));
}

Minimum compatible version: PyTorch 2.9.

STABLE_TORCH_LIBRARY_FRAGMENT


Extends operator definitions in an existing namespace using the stable ABI.

This is the stable ABI equivalent of `TORCH_LIBRARY_FRAGMENT`. Use this macro
to add additional operator definitions to a namespace that was already
created with `STABLE_TORCH_LIBRARY`.

:param ns: The namespace to extend.
:param m: The name of the StableLibrary variable available in the block.

Minimum compatible version: PyTorch 2.9.

TORCH_BOX


Wraps a function to conform to the stable boxed kernel calling convention.

This macro takes an unboxed kernel function pointer and generates a boxed wrapper
that can be registered with the stable library API.

:param func: The unboxed kernel function to wrap.

**Example:**

```cpp
Tensor my_kernel(const Tensor& input, int64_t size) {
    return input.reshape({size});
}

STABLE_TORCH_LIBRARY_IMPL(my_namespace, CPU, m) {
    m.impl("my_op", TORCH_BOX(&my_kernel));
}

Minimum compatible version: PyTorch 2.9.