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
21extern "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.
26struct MlirDiagnostic {
27 void *ptr;
28};
29typedef struct MlirDiagnostic MlirDiagnostic;
30
31/// Severity of a diagnostic.
32enum MlirDiagnosticSeverity {
33 MlirDiagnosticError,
34 MlirDiagnosticWarning,
35 MlirDiagnosticNote,
36 MlirDiagnosticRemark
37};
38typedef enum MlirDiagnosticSeverity MlirDiagnosticSeverity;
39
40/// Opaque identifier of a diagnostic handler, useful to detach a handler.
41typedef 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.
49typedef MlirLogicalResult (*MlirDiagnosticHandler)(MlirDiagnostic,
50 void *userData);
51
52/// Prints a diagnostic using the provided callback.
53MLIR_CAPI_EXPORTED void mlirDiagnosticPrint(MlirDiagnostic diagnostic,
54 MlirStringCallback callback,
55 void *userData);
56
57/// Returns the location at which the diagnostic is reported.
58MLIR_CAPI_EXPORTED MlirLocation
59mlirDiagnosticGetLocation(MlirDiagnostic diagnostic);
60
61/// Returns the severity of the diagnostic.
62MLIR_CAPI_EXPORTED MlirDiagnosticSeverity
63mlirDiagnosticGetSeverity(MlirDiagnostic diagnostic);
64
65/// Returns the number of notes attached to the diagnostic.
66MLIR_CAPI_EXPORTED intptr_t
67mlirDiagnosticGetNumNotes(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.
71MLIR_CAPI_EXPORTED MlirDiagnostic
72mlirDiagnosticGetNote(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
82MLIR_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.
88MLIR_CAPI_EXPORTED void
89mlirContextDetachDiagnosticHandler(MlirContext context,
90 MlirDiagnosticHandlerID id);
91
92/// Emits an error at the given location through the diagnostics engine. Used
93/// for testing purposes.
94MLIR_CAPI_EXPORTED void mlirEmitError(MlirLocation location,
95 const char *message);
96
97#ifdef __cplusplus
98}
99#endif
100
101#endif // MLIR_C_DIAGNOSTICS_H
102

source code of mlir/include/mlir-c/Diagnostics.h