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
102