include/llvm-c/Error.h

0001 /*===------- llvm-c/Error.h - llvm::Error class C Interface -------*- C -*-===*\
0002 |*                                                                            *|
0003 |* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
0004 |* Exceptions.                                                                *|
0005 |* See https://llvm.org/LICENSE.txt for license information.                  *|
0006 |* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
0007 |*                                                                            *|
0008 |*===----------------------------------------------------------------------===*|
0009 |*                                                                            *|
0010 |* This file defines the C interface to LLVM's Error class.                   *|
0011 |*                                                                            *|
0012 \*===----------------------------------------------------------------------===*/
0013
0014 #ifndef LLVM_C_ERROR_H
0015 #define LLVM_C_ERROR_H
0016
0017 #include "llvm-c/ExternC.h"
0018
0019 LLVM_C_EXTERN_C_BEGIN
0020
0021 /**
0022  * @defgroup LLVMCError Error Handling
0023  * @ingroup LLVMC
0024  *
0025  * @{
0026  */
0027
0028 #define LLVMErrorSuccess 0
0029
0030 /**
0031  * Opaque reference to an error instance. Null serves as the 'success' value.
0032  */
0033 typedef struct LLVMOpaqueError *LLVMErrorRef;
0034
0035 /**
0036  * Error type identifier.
0037  */
0038 typedef const void *LLVMErrorTypeId;
0039
0040 /**
0041  * Returns the type id for the given error instance, which must be a failure
0042  * value (i.e. non-null).
0043  */
0044 LLVMErrorTypeId LLVMGetErrorTypeId(LLVMErrorRef Err);
0045
0046 /**
0047  * Dispose of the given error without handling it. This operation consumes the
0048  * error, and the given LLVMErrorRef value is not usable once this call returns.
0049  * Note: This method *only* needs to be called if the error is not being passed
0050  * to some other consuming operation, e.g. LLVMGetErrorMessage.
0051  */
0052 void LLVMConsumeError(LLVMErrorRef Err);
0053
0054 /**
0055  * Report a fatal error if Err is a failure value.
0056  *
0057  * This function can be used to wrap calls to fallible functions ONLY when it is
0058  * known that the Error will always be a success value.
0059  */
0060 void LLVMCantFail(LLVMErrorRef Err);
0061
0062 /**
0063  * Returns the given string's error message. This operation consumes the error,
0064  * and the given LLVMErrorRef value is not usable once this call returns.
0065  * The caller is responsible for disposing of the string by calling
0066  * LLVMDisposeErrorMessage.
0067  */
0068 char *LLVMGetErrorMessage(LLVMErrorRef Err);
0069
0070 /**
0071  * Dispose of the given error message.
0072  */
0073 void LLVMDisposeErrorMessage(char *ErrMsg);
0074
0075 /**
0076  * Returns the type id for llvm StringError.
0077  */
0078 LLVMErrorTypeId LLVMGetStringErrorTypeId(void);
0079
0080 /**
0081  * Create a StringError.
0082  */
0083 LLVMErrorRef LLVMCreateStringError(const char *ErrMsg);
0084
0085 /**
0086  * @}
0087  */
0088
0089 LLVM_C_EXTERN_C_END
0090
0091 #endif