diff options
Diffstat (limited to '3rdparty/asmjit/src/asmjit/core/errorhandler.h')
-rw-r--r-- | 3rdparty/asmjit/src/asmjit/core/errorhandler.h | 137 |
1 files changed, 49 insertions, 88 deletions
diff --git a/3rdparty/asmjit/src/asmjit/core/errorhandler.h b/3rdparty/asmjit/src/asmjit/core/errorhandler.h index 2337cd8d841..a1a2dd2d5db 100644 --- a/3rdparty/asmjit/src/asmjit/core/errorhandler.h +++ b/3rdparty/asmjit/src/asmjit/core/errorhandler.h @@ -1,25 +1,7 @@ -// AsmJit - Machine code generation for C++ +// This file is part of AsmJit project <https://asmjit.com> // -// * Official AsmJit Home Page: https://asmjit.com -// * Official Github Repository: https://github.com/asmjit/asmjit -// -// Copyright (c) 2008-2020 The AsmJit Authors -// -// This software is provided 'as-is', without any express or implied -// warranty. In no event will the authors be held liable for any damages -// arising from the use of this software. -// -// Permission is granted to anyone to use this software for any purpose, -// including commercial applications, and to alter it and redistribute it -// freely, subject to the following restrictions: -// -// 1. The origin of this software must not be misrepresented; you must not -// claim that you wrote the original software. If you use this software -// in a product, an acknowledgment in the product documentation would be -// appreciated but is not required. -// 2. Altered source versions must be plainly marked as such, and must not be -// misrepresented as being the original software. -// 3. This notice may not be removed or altered from any source distribution. +// See asmjit.h or LICENSE.md for license and copyright information +// SPDX-License-Identifier: Zlib #ifndef ASMJIT_CORE_ERRORHANDLER_H_INCLUDED #define ASMJIT_CORE_ERRORHANDLER_H_INCLUDED @@ -31,44 +13,31 @@ ASMJIT_BEGIN_NAMESPACE //! \addtogroup asmjit_error_handling //! \{ -// ============================================================================ -// [Forward Declarations] -// ============================================================================ - class BaseEmitter; -// ============================================================================ -// [asmjit::ErrorHandler] -// ============================================================================ - //! Error handler can be used to override the default behavior of error handling. //! -//! It's available to all classes that inherit `BaseEmitter`. Override -//! \ref ErrorHandler::handleError() to implement your own error handler. +//! It's available to all classes that inherit `BaseEmitter`. Override \ref ErrorHandler::handleError() to implement +//! your own error handler. //! //! The following use-cases are supported: //! -//! - Record the error and continue code generation. This is the simplest -//! approach that can be used to at least log possible errors. -//! - Throw an exception. AsmJit doesn't use exceptions and is completely -//! exception-safe, but it's perfectly legal to throw an exception from -//! the error handler. -//! - Use plain old C's `setjmp()` and `longjmp()`. Asmjit always puts Assembler, -//! Builder and Compiler to a consistent state before calling \ref handleError(), -//! so `longjmp()` can be used without issues to cancel the code-generation if -//! an error occurred. This method can be used if exception handling in your -//! project is turned off and you still want some comfort. In most cases it -//! should be safe as AsmJit uses \ref Zone memory and the ownership of memory -//! it allocates always ends with the instance that allocated it. If using this -//! approach please never jump outside the life-time of \ref CodeHolder and -//! \ref BaseEmitter. -//! -//! \ref ErrorHandler can be attached to \ref CodeHolder or \ref BaseEmitter, -//! which has a priority. The example below uses error handler that just prints -//! the error, but lets AsmJit continue: +//! - Record the error and continue code generation. This is the simplest approach that can be used to at least log +//! possible errors. +//! - Throw an exception. AsmJit doesn't use exceptions and is completely exception-safe, but it's perfectly legal +//! to throw an exception from the error handler. +//! - Use plain old C's `setjmp()` and `longjmp()`. Asmjit always puts Assembler, Builder and Compiler to +//! a consistent state before calling \ref handleError(), so `longjmp()` can be used without issues to cancel the +//! code generation if an error occurred. This method can be used if exception handling in your project is turned +//! off and you still want some comfort. In most cases it should be safe as AsmJit uses \ref Zone memory and the +//! ownership of memory it allocates always ends with the instance that allocated it. If using this approach please +//! never jump outside the life-time of \ref CodeHolder and \ref BaseEmitter. +//! +//! \ref ErrorHandler can be attached to \ref CodeHolder or \ref BaseEmitter, which has a priority. The example below +//! uses error handler that just prints the error, but lets AsmJit continue: //! //! ``` -//! // Error Handling #1 - Logging and returing Error. +//! // Error Handling #1 - Logging and returning Error. //! #include <asmjit/x86.h> //! #include <stdio.h> //! @@ -92,7 +61,7 @@ class BaseEmitter; //! SimpleErrorHandler eh; //! //! CodeHolder code; -//! code.init(rt.environment()); +//! code.init(rt.environment(), rt.cpuFeatures()); //! code.setErrorHandler(&eh); //! //! // Try to emit instruction that doesn't exist. @@ -108,12 +77,10 @@ class BaseEmitter; //! } //! ``` //! -//! If error happens during instruction emitting / encoding the assembler behaves -//! transactionally - the output buffer won't advance if encoding failed, thus -//! either a fully encoded instruction or nothing is emitted. The error handling -//! shown above is useful, but it's still not the best way of dealing with errors -//! in AsmJit. The following example shows how to use exception handling to handle -//! errors in a more C++ way: +//! If error happens during instruction emitting / encoding the assembler behaves transactionally - the output buffer +//! won't advance if encoding failed, thus either a fully encoded instruction or nothing is emitted. The error handling +//! shown above is useful, but it's still not the best way of dealing with errors in AsmJit. The following example +//! shows how to use exception handling to handle errors in a more C++ way: //! //! ``` //! // Error Handling #2 - Throwing an exception. @@ -150,7 +117,7 @@ class BaseEmitter; //! ThrowableErrorHandler eh; //! //! CodeHolder code; -//! code.init(rt.environment()); +//! code.init(rt.environment(), rt.cpuFeatures()); //! code.setErrorHandler(&eh); //! //! x86::Assembler a(&code); @@ -168,13 +135,10 @@ class BaseEmitter; //! } //! ``` //! -//! If C++ exceptions are not what you like or your project turns off them -//! completely there is still a way of reducing the error handling to a minimum -//! by using a standard setjmp/longjmp approach. AsmJit is exception-safe and -//! cleans up everything before calling the ErrorHandler, so any approach is -//! safe. You can simply jump from the error handler without causing any -//! side-effects or memory leaks. The following example demonstrates how it -//! could be done: +//! If C++ exceptions are not what you like or your project turns off them completely there is still a way of reducing +//! the error handling to a minimum by using a standard setjmp/longjmp approach. AsmJit is exception-safe and cleans +//! up everything before calling the ErrorHandler, so any approach is safe. You can simply jump from the error handler +//! without causing any side-effects or memory leaks. The following example demonstrates how it could be done: //! //! ``` //! // Error Handling #3 - Using setjmp/longjmp if exceptions are not allowed. @@ -202,7 +166,7 @@ class BaseEmitter; //! LongJmpErrorHandler eh; //! //! CodeHolder code; -//! code.init(rt.rt.environment()); +//! code.init(rt.environment(), rt.cpuFeatures()); //! code.setErrorHandler(&eh); //! //! x86::Assembler a(&code); @@ -223,40 +187,37 @@ class ASMJIT_VIRTAPI ErrorHandler { public: ASMJIT_BASE_CLASS(ErrorHandler) - // -------------------------------------------------------------------------- - // [Construction / Destruction] - // -------------------------------------------------------------------------- + //! \name Construction & Destruction + //! \{ //! Creates a new `ErrorHandler` instance. ASMJIT_API ErrorHandler() noexcept; //! Destroys the `ErrorHandler` instance. ASMJIT_API virtual ~ErrorHandler() noexcept; - // -------------------------------------------------------------------------- - // [Handle Error] - // -------------------------------------------------------------------------- + //! \} + + //! \name Interface + //! \{ //! Error handler (must be reimplemented). //! - //! Error handler is called after an error happened and before it's propagated - //! to the caller. There are multiple ways how the error handler can be used: + //! Error handler is called after an error happened and before it's propagated to the caller. There are multiple + //! ways how the error handler can be used: //! - //! 1. User-based error handling without throwing exception or using C's - //! `longjmp()`. This is for users that don't use exceptions and want - //! customized error handling. + //! 1. User-based error handling without throwing exception or using C's`longjmp()`. This is for users that don't + //! use exceptions and want customized error handling. //! - //! 2. Throwing an exception. AsmJit doesn't use exceptions and is completely - //! exception-safe, but you can throw exception from your error handler if - //! this way is the preferred way of handling errors in your project. + //! 2. Throwing an exception. AsmJit doesn't use exceptions and is completely exception-safe, but you can throw + //! exception from your error handler if this way is the preferred way of handling errors in your project. //! - //! 3. Using plain old C's `setjmp()` and `longjmp()`. Asmjit always puts - //! `BaseEmitter` to a consistent state before calling `handleError()` - //! so `longjmp()` can be used without any issues to cancel the code - //! generation if an error occurred. There is no difference between - //! exceptions and `longjmp()` from AsmJit's perspective, however, - //! never jump outside of `CodeHolder` and `BaseEmitter` scope as you - //! would leak memory. - virtual void handleError(Error err, const char* message, BaseEmitter* origin) = 0; + //! 3. Using plain old C's `setjmp()` and `longjmp()`. Asmjit always puts `BaseEmitter` to a consistent state before + //! calling `handleError()` so `longjmp()` can be used without any issues to cancel the code generation if an + //! error occurred. There is no difference between exceptions and `longjmp()` from AsmJit's perspective, however, + //! never jump outside of `CodeHolder` and `BaseEmitter` scope as you would leak memory. + ASMJIT_API virtual void handleError(Error err, const char* message, BaseEmitter* origin); + + //! \} }; //! \} |