llvm-project/mlir/include/mlir-c/Bindings/Python/Interop.h

//===-- mlir-c/Interop.h - Constants for Python/C-API interop -----*- C -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM
// Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This header declares constants and helpers necessary for C-level
// interop with the MLIR Python extension module. Since the Python bindings
// are a thin wrapper around the MLIR C-API, a further C-API is not provided
// specifically for the Python extension. Instead, simple facilities are
// provided for translating between Python types and corresponding MLIR C-API
// types.
//
// This header is standalone, requiring nothing beyond normal linking against
// the Python implementation.
//===----------------------------------------------------------------------===//

#ifndef MLIR_C_BINDINGS_PYTHON_INTEROP_H
#define MLIR_C_BINDINGS_PYTHON_INTEROP_H

// We *should*, in theory, include Python.h here in order to import the correct
// definitions for what we need below, however, importing Python.h directly on
// Windows results in the enforcement of either pythonX.lib or pythonX_d.lib
// depending on the build flavor. Instead, we rely on the fact that this file
// (Interop.h) is always included AFTER pybind11 and will therefore have access
// to the definitions from Python.h in addition to having a workaround applied
// through the pybind11 headers that allows us to control which python library
// is used.
#if !defined(_MSC_VER)
#include <Python.h>
#endif

#include "mlir-c/AffineExpr.h"
#include "mlir-c/AffineMap.h"
#include "mlir-c/ExecutionEngine.h"
#include "mlir-c/IR.h"
#include "mlir-c/IntegerSet.h"
#include "mlir-c/Pass.h"
#include "mlir-c/Rewrite.h"

// The 'mlir' Python package is relocatable and supports co-existing in multiple
// projects. Each project must define its outer package prefix with this define
// in order to provide proper isolation and local name resolution.
// The default is for the upstream "import mlir" package layout.
// Note that this prefix is internally stringified, allowing it to be passed
// unquoted on the compiler command line without shell quote escaping issues.
#ifndef MLIR_PYTHON_PACKAGE_PREFIX
#define MLIR_PYTHON_PACKAGE_PREFIX mlir.
#endif

// Makes a fully-qualified name relative to the MLIR python package.
#define MLIR_PYTHON_STRINGIZE(s) #s
#define MLIR_PYTHON_STRINGIZE_ARG(arg) MLIR_PYTHON_STRINGIZE(arg)
#define MAKE_MLIR_PYTHON_QUALNAME(local)                                       \
  MLIR_PYTHON_STRINGIZE_ARG(MLIR_PYTHON_PACKAGE_PREFIX) local

#define MLIR_PYTHON_CAPSULE_AFFINE_EXPR                                        \
  MAKE_MLIR_PYTHON_QUALNAME("ir.AffineExpr._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_AFFINE_MAP                                         \
  MAKE_MLIR_PYTHON_QUALNAME("ir.AffineMap._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_ATTRIBUTE                                          \
  MAKE_MLIR_PYTHON_QUALNAME("ir.Attribute._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_BLOCK MAKE_MLIR_PYTHON_QUALNAME("ir.Block._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_CONTEXT                                            \
  MAKE_MLIR_PYTHON_QUALNAME("ir.Context._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_DIALECT_REGISTRY                                   \
  MAKE_MLIR_PYTHON_QUALNAME("ir.DialectRegistry._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_EXECUTION_ENGINE                                   \
  MAKE_MLIR_PYTHON_QUALNAME("execution_engine.ExecutionEngine._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_INTEGER_SET                                        \
  MAKE_MLIR_PYTHON_QUALNAME("ir.IntegerSet._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_LOCATION                                           \
  MAKE_MLIR_PYTHON_QUALNAME("ir.Location._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_MODULE                                             \
  MAKE_MLIR_PYTHON_QUALNAME("ir.Module._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_OPERATION                                          \
  MAKE_MLIR_PYTHON_QUALNAME("ir.Operation._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_TYPE MAKE_MLIR_PYTHON_QUALNAME("ir.Type._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_PASS_MANAGER                                       \
  MAKE_MLIR_PYTHON_QUALNAME("passmanager.PassManager._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_VALUE MAKE_MLIR_PYTHON_QUALNAME("ir.Value._CAPIPtr")
#define MLIR_PYTHON_CAPSULE_TYPEID                                             \
  MAKE_MLIR_PYTHON_QUALNAME("ir.TypeID._CAPIPtr")

/** Attribute on MLIR Python objects that expose their C-API pointer.
 * This will be a type-specific capsule created as per one of the helpers
 * below.
 *
 * Ownership is not transferred by acquiring a capsule in this way: the
 * validity of the pointer wrapped by the capsule will be bounded by the
 * lifetime of the Python object that produced it. Only the name and pointer
 * of the capsule are set. The caller is free to set a destructor and context
 * as needed to manage anything further. */
#define MLIR_PYTHON_CAPI_PTR_ATTR "_CAPIPtr"

/** Attribute on MLIR Python objects that exposes a factory function for
 * constructing the corresponding Python object from a type-specific
 * capsule wrapping the C-API pointer. The signature of the function is:
 *   def _CAPICreate(capsule) -> object
 * Calling such a function implies a transfer of ownership of the object the
 * capsule wraps: after such a call, the capsule should be considered invalid,
 * and its wrapped pointer must not be destroyed.
 *
 * Only a very small number of Python objects can be created in such a fashion
 * (i.e. top-level types such as Context where the lifetime can be cleanly
 * delineated). */
#define MLIR_PYTHON_CAPI_FACTORY_ATTR "_CAPICreate"

/** Attribute on MLIR Python objects that expose a function for downcasting the
 * corresponding Python object to a subclass if the object is in fact a subclass
 * (Concrete or mlir_type_subclass) of ir.Type. The signature of the function
 * is: def maybe_downcast(self) -> object where the resulting object will
 * (possibly) be an instance of the subclass.
 */
#define MLIR_PYTHON_MAYBE_DOWNCAST_ATTR "maybe_downcast"

/** Attribute on main C extension module (_mlir) that corresponds to the
 * type caster registration binding. The signature of the function is:
 *   def register_type_caster(MlirTypeID mlirTypeID, *, bool replace)
 * which then takes a typeCaster (register_type_caster is meant to be used as a
 * decorator from python), and where replace indicates the typeCaster should
 * replace any existing registered type casters (such as those for upstream
 * ConcreteTypes). The interface of the typeCaster is: def type_caster(ir.Type)
 * -> SubClassTypeT where SubClassTypeT indicates the result should be a
 * subclass (inherit from) ir.Type.
 */
#define MLIR_PYTHON_CAPI_TYPE_CASTER_REGISTER_ATTR "register_type_caster"

/** Attribute on main C extension module (_mlir) that corresponds to the
 * value caster registration binding. The signature of the function is:
 *   def register_value_caster(MlirTypeID mlirTypeID, *, bool replace)
 * which then takes a valueCaster (register_value_caster is meant to be used as
 * a decorator, from python), and where replace indicates the valueCaster should
 * replace any existing registered value casters. The interface of the
 * valueCaster is: def value_caster(ir.Value) -> SubClassValueT where
 * SubClassValueT indicates the result should be a subclass (inherit from)
 * ir.Value.
 */
#define MLIR_PYTHON_CAPI_VALUE_CASTER_REGISTER_ATTR "register_value_caster"

/// Gets a void* from a wrapped struct. Needed because const cast is different
/// between C/C++.
#ifdef __cplusplus
#define MLIR_PYTHON_GET_WRAPPED_POINTER(object)                                \
  (const_cast<void *>((object).ptr))
#else
#define MLIR_PYTHON_GET_WRAPPED_POINTER(object) (void *)(object.ptr)
#endif

#ifdef __cplusplus
extern "C" {
#endif

/** Creates a capsule object encapsulating the raw C-API MlirAffineExpr. The
 * returned capsule does not extend or affect ownership of any Python objects
 * that reference the expression in any way.
 */
static inline PyObject *mlirPythonAffineExprToCapsule(MlirAffineExpr expr) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(expr),
                       MLIR_PYTHON_CAPSULE_AFFINE_EXPR, NULL);
}

/** Extracts an MlirAffineExpr from a capsule as produced from
 * mlirPythonAffineExprToCapsule. If the capsule is not of the right type, then
 * a null expression is returned (as checked via mlirAffineExprIsNull). In such
 * a case, the Python APIs will have already set an error. */
static inline MlirAffineExpr mlirPythonCapsuleToAffineExpr(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_AFFINE_EXPR);
  MlirAffineExpr expr = {ptr};
  return expr;
}

/** Creates a capsule object encapsulating the raw C-API MlirAttribute.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the attribute in any way.
 */
static inline PyObject *mlirPythonAttributeToCapsule(MlirAttribute attribute) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(attribute),
                       MLIR_PYTHON_CAPSULE_ATTRIBUTE, NULL);
}

/** Extracts an MlirAttribute from a capsule as produced from
 * mlirPythonAttributeToCapsule. If the capsule is not of the right type, then
 * a null attribute is returned (as checked via mlirAttributeIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirAttribute mlirPythonCapsuleToAttribute(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_ATTRIBUTE);
  MlirAttribute attr = {ptr};
  return attr;
}

/** Creates a capsule object encapsulating the raw C-API MlirBlock.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the module in any way. */
static inline PyObject *mlirPythonBlockToCapsule(MlirBlock block) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(block),
                       MLIR_PYTHON_CAPSULE_BLOCK, NULL);
}

/** Extracts an MlirBlock from a capsule as produced from
 * mlirPythonBlockToCapsule. If the capsule is not of the right type, then
 * a null pass manager is returned (as checked via mlirBlockIsNull). */
static inline MlirBlock mlirPythonCapsuleToBlock(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_BLOCK);
  MlirBlock block = {ptr};
  return block;
}

/** Creates a capsule object encapsulating the raw C-API MlirContext.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the context in any way.
 */
static inline PyObject *mlirPythonContextToCapsule(MlirContext context) {
  return PyCapsule_New(context.ptr, MLIR_PYTHON_CAPSULE_CONTEXT, NULL);
}

/** Extracts a MlirContext from a capsule as produced from
 * mlirPythonContextToCapsule. If the capsule is not of the right type, then
 * a null context is returned (as checked via mlirContextIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirContext mlirPythonCapsuleToContext(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_CONTEXT);
  MlirContext context = {ptr};
  return context;
}

/** Creates a capsule object encapsulating the raw C-API MlirDialectRegistry.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the context in any way.
 */
static inline PyObject *
mlirPythonDialectRegistryToCapsule(MlirDialectRegistry registry) {
  return PyCapsule_New(registry.ptr, MLIR_PYTHON_CAPSULE_DIALECT_REGISTRY,
                       NULL);
}

/** Extracts an MlirDialectRegistry from a capsule as produced from
 * mlirPythonDialectRegistryToCapsule. If the capsule is not of the right type,
 * then a null context is returned (as checked via mlirContextIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirDialectRegistry
mlirPythonCapsuleToDialectRegistry(PyObject *capsule) {
  void *ptr =
      PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_DIALECT_REGISTRY);
  MlirDialectRegistry registry = {ptr};
  return registry;
}

/** Creates a capsule object encapsulating the raw C-API MlirLocation.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the location in any way. */
static inline PyObject *mlirPythonLocationToCapsule(MlirLocation loc) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(loc),
                       MLIR_PYTHON_CAPSULE_LOCATION, NULL);
}

/** Extracts an MlirLocation from a capsule as produced from
 * mlirPythonLocationToCapsule. If the capsule is not of the right type, then
 * a null module is returned (as checked via mlirLocationIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirLocation mlirPythonCapsuleToLocation(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_LOCATION);
  MlirLocation loc = {ptr};
  return loc;
}

/** Creates a capsule object encapsulating the raw C-API MlirModule.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the module in any way. */
static inline PyObject *mlirPythonModuleToCapsule(MlirModule module) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(module),
                       MLIR_PYTHON_CAPSULE_MODULE, NULL);
}

/** Extracts an MlirModule from a capsule as produced from
 * mlirPythonModuleToCapsule. If the capsule is not of the right type, then
 * a null module is returned (as checked via mlirModuleIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirModule mlirPythonCapsuleToModule(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_MODULE);
  MlirModule module = {ptr};
  return module;
}

/** Creates a capsule object encapsulating the raw C-API
 * MlirFrozenRewritePatternSet.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the module in any way. */
static inline PyObject *
mlirPythonFrozenRewritePatternSetToCapsule(MlirFrozenRewritePatternSet pm) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(pm),
                       MLIR_PYTHON_CAPSULE_PASS_MANAGER, NULL);
}

/** Extracts an MlirFrozenRewritePatternSet from a capsule as produced from
 * mlirPythonFrozenRewritePatternSetToCapsule. If the capsule is not of the
 * right type, then a null module is returned. */
static inline MlirFrozenRewritePatternSet
mlirPythonCapsuleToFrozenRewritePatternSet(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_PASS_MANAGER);
  MlirFrozenRewritePatternSet pm = {ptr};
  return pm;
}

/** Creates a capsule object encapsulating the raw C-API MlirPassManager.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the module in any way. */
static inline PyObject *mlirPythonPassManagerToCapsule(MlirPassManager pm) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(pm),
                       MLIR_PYTHON_CAPSULE_PASS_MANAGER, NULL);
}

/** Extracts an MlirPassManager from a capsule as produced from
 * mlirPythonPassManagerToCapsule. If the capsule is not of the right type, then
 * a null pass manager is returned (as checked via mlirPassManagerIsNull). */
static inline MlirPassManager
mlirPythonCapsuleToPassManager(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_PASS_MANAGER);
  MlirPassManager pm = {ptr};
  return pm;
}

/** Creates a capsule object encapsulating the raw C-API MlirOperation.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the operation in any way.
 */
static inline PyObject *mlirPythonOperationToCapsule(MlirOperation operation) {
  return PyCapsule_New(operation.ptr, MLIR_PYTHON_CAPSULE_OPERATION, NULL);
}

/** Extracts an MlirOperations from a capsule as produced from
 * mlirPythonOperationToCapsule. If the capsule is not of the right type, then
 * a null type is returned (as checked via mlirOperationIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirOperation mlirPythonCapsuleToOperation(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_OPERATION);
  MlirOperation op = {ptr};
  return op;
}

/** Creates a capsule object encapsulating the raw C-API MlirTypeID.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the type in any way.
 */
static inline PyObject *mlirPythonTypeIDToCapsule(MlirTypeID typeID) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(typeID),
                       MLIR_PYTHON_CAPSULE_TYPEID, NULL);
}

/** Extracts an MlirTypeID from a capsule as produced from
 * mlirPythonTypeIDToCapsule. If the capsule is not of the right type, then
 * a null type is returned (as checked via mlirTypeIDIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirTypeID mlirPythonCapsuleToTypeID(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_TYPEID);
  MlirTypeID typeID = {ptr};
  return typeID;
}

/** Creates a capsule object encapsulating the raw C-API MlirType.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the type in any way.
 */
static inline PyObject *mlirPythonTypeToCapsule(MlirType type) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(type),
                       MLIR_PYTHON_CAPSULE_TYPE, NULL);
}

/** Extracts an MlirType from a capsule as produced from
 * mlirPythonTypeToCapsule. If the capsule is not of the right type, then
 * a null type is returned (as checked via mlirTypeIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirType mlirPythonCapsuleToType(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_TYPE);
  MlirType type = {ptr};
  return type;
}

/** Creates a capsule object encapsulating the raw C-API MlirAffineMap.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the type in any way.
 */
static inline PyObject *mlirPythonAffineMapToCapsule(MlirAffineMap affineMap) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(affineMap),
                       MLIR_PYTHON_CAPSULE_AFFINE_MAP, NULL);
}

/** Extracts an MlirAffineMap from a capsule as produced from
 * mlirPythonAffineMapToCapsule. If the capsule is not of the right type, then
 * a null type is returned (as checked via mlirAffineMapIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirAffineMap mlirPythonCapsuleToAffineMap(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_AFFINE_MAP);
  MlirAffineMap affineMap = {ptr};
  return affineMap;
}

/** Creates a capsule object encapsulating the raw C-API MlirIntegerSet.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the set in any way. */
static inline PyObject *
mlirPythonIntegerSetToCapsule(MlirIntegerSet integerSet) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(integerSet),
                       MLIR_PYTHON_CAPSULE_INTEGER_SET, NULL);
}

/** Extracts an MlirIntegerSet from a capsule as produced from
 * mlirPythonIntegerSetToCapsule. If the capsule is not of the right type, then
 * a null set is returned (as checked via mlirIntegerSetIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirIntegerSet mlirPythonCapsuleToIntegerSet(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_INTEGER_SET);
  MlirIntegerSet integerSet = {ptr};
  return integerSet;
}

/** Creates a capsule object encapsulating the raw C-API MlirExecutionEngine.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the set in any way. */
static inline PyObject *
mlirPythonExecutionEngineToCapsule(MlirExecutionEngine jit) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(jit),
                       MLIR_PYTHON_CAPSULE_EXECUTION_ENGINE, NULL);
}

/** Extracts an MlirExecutionEngine from a capsule as produced from
 * mlirPythonIntegerSetToCapsule. If the capsule is not of the right type, then
 * a null set is returned (as checked via mlirExecutionEngineIsNull). In such a
 * case, the Python APIs will have already set an error. */
static inline MlirExecutionEngine
mlirPythonCapsuleToExecutionEngine(PyObject *capsule) {
  void *ptr =
      PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_EXECUTION_ENGINE);
  MlirExecutionEngine jit = {ptr};
  return jit;
}

/** Creates a capsule object encapsulating the raw C-API MlirValue.
 * The returned capsule does not extend or affect ownership of any Python
 * objects that reference the operation in any way.
 */
static inline PyObject *mlirPythonValueToCapsule(MlirValue value) {
  return PyCapsule_New(MLIR_PYTHON_GET_WRAPPED_POINTER(value),
                       MLIR_PYTHON_CAPSULE_VALUE, NULL);
}

/** Extracts an MlirValue from a capsule as produced from
 * mlirPythonValueToCapsule. If the capsule is not of the right type, then a
 * null type is returned (as checked via mlirValueIsNull). In such a case, the
 * Python APIs will have already set an error. */
static inline MlirValue mlirPythonCapsuleToValue(PyObject *capsule) {
  void *ptr = PyCapsule_GetPointer(capsule, MLIR_PYTHON_CAPSULE_VALUE);
  MlirValue value = {ptr};
  return value;
}

#ifdef __cplusplus
}
#endif

#endif // MLIR_C_BINDINGS_PYTHON_INTEROP_H