mlir/include/mlir-c/Diagnostics.h

   1 //===-- mlir-c/Diagnostics.h - MLIR Diagnostic subsystem C API ----*- C -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM
   4 // Exceptions.
   5 // See https://llvm.org/LICENSE.txt for license information.
   6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This header declares the C APIs accessing MLIR Diagnostics subsystem.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef MLIR_C_DIAGNOSTICS_H
  15 #define MLIR_C_DIAGNOSTICS_H
  16
  17 #include "mlir-c/IR.h"
  18 #include "mlir-c/Support.h"
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /// An opaque reference to a diagnostic, always owned by the diagnostics engine
  25 /// (context). Must not be stored outside of the diagnostic handler.
  26 struct MlirDiagnostic {
  27   void *ptr;
  28 };
  29 typedef struct MlirDiagnostic MlirDiagnostic;
  30
  31 /// Severity of a diagnostic.
  32 enum MlirDiagnosticSeverity {
  33   MlirDiagnosticError,
  34   MlirDiagnosticWarning,
  35   MlirDiagnosticNote,
  36   MlirDiagnosticRemark
  37 };
  38 typedef enum MlirDiagnosticSeverity MlirDiagnosticSeverity;
  39
  40 /// Opaque identifier of a diagnostic handler, useful to detach a handler.
  41 typedef uint64_t MlirDiagnosticHandlerID;
  42
  43 /// Diagnostic handler type. Accepts a reference to a diagnostic, which is only
  44 /// guaranteed to be live during the call. The handler is passed the `userData`
  45 /// that was provided when the handler was attached to a context. If the handler
  46 /// processed the diagnostic completely, it is expected to return success.
  47 /// Otherwise, it is expected to return failure to indicate that other handlers
  48 /// should attempt to process the diagnostic.
  49 typedef MlirLogicalResult (*MlirDiagnosticHandler)(MlirDiagnostic,
  50                                                    void *userData);
  51
  52 /// Prints a diagnostic using the provided callback.
  53 MLIR_CAPI_EXPORTED void mlirDiagnosticPrint(MlirDiagnostic diagnostic,
  54                                             MlirStringCallback callback,
  55                                             void *userData);
  56
  57 /// Returns the location at which the diagnostic is reported.
  58 MLIR_CAPI_EXPORTED MlirLocation
  59 mlirDiagnosticGetLocation(MlirDiagnostic diagnostic);
  60
  61 /// Returns the severity of the diagnostic.
  62 MLIR_CAPI_EXPORTED MlirDiagnosticSeverity
  63 mlirDiagnosticGetSeverity(MlirDiagnostic diagnostic);
  64
  65 /// Returns the number of notes attached to the diagnostic.
  66 MLIR_CAPI_EXPORTED intptr_t
  67 mlirDiagnosticGetNumNotes(MlirDiagnostic diagnostic);
  68
  69 /// Returns `pos`-th note attached to the diagnostic. Expects `pos` to be a
  70 /// valid zero-based index into the list of notes.
  71 MLIR_CAPI_EXPORTED MlirDiagnostic
  72 mlirDiagnosticGetNote(MlirDiagnostic diagnostic, intptr_t pos);
  73
  74 /// Attaches the diagnostic handler to the context. Handlers are invoked in the
  75 /// reverse order of attachment until one of them processes the diagnostic
  76 /// completely. When a handler is invoked it is passed the `userData` that was
  77 /// provided when it was attached. If non-NULL, `deleteUserData` is called once
  78 /// the system no longer needs to call the handler (for instance after the
  79 /// handler is detached or the context is destroyed). Returns an identifier that
  80 /// can be used to detach the handler.
  81
  82 MLIR_CAPI_EXPORTED MlirDiagnosticHandlerID mlirContextAttachDiagnosticHandler(
  83     MlirContext context, MlirDiagnosticHandler handler, void *userData,
  84     void (*deleteUserData)(void *));
  85
  86 /// Detaches an attached diagnostic handler from the context given its
  87 /// identifier.
  88 MLIR_CAPI_EXPORTED void
  89 mlirContextDetachDiagnosticHandler(MlirContext context,
  90                                    MlirDiagnosticHandlerID id);
  91
  92 /// Emits an error at the given location through the diagnostics engine. Used
  93 /// for testing purposes.
  94 MLIR_CAPI_EXPORTED void mlirEmitError(MlirLocation location,
  95                                       const char *message);
  96
  97 #ifdef __cplusplus
  98 }
  99 #endif
 100
 101 #endif // MLIR_C_DIAGNOSTICS_H