1// Copyright 2021 the V8 project authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5// Note 1: Any file that includes this one should include api-macros-undef.h 6// at the bottom. 7 8// Note 2: This file is deliberately missing the include guards (the undeffing 9// approach wouldn't work otherwise). 10// 11// PRESUBMIT_INTENTIONALLY_MISSING_INCLUDE_GUARD 12 13/* 14 * Most API methods should use one of the three macros: 15 * 16 * ENTER_V8, ENTER_V8_NO_SCRIPT, ENTER_V8_NO_SCRIPT_NO_EXCEPTION. 17 * 18 * The latter two assume that no script is executed, and no exceptions are 19 * scheduled in addition (respectively). Creating a pending exception and 20 * removing it before returning is ok. 21 * 22 * Exceptions should be handled either by invoking one of the 23 * RETURN_ON_FAILED_EXECUTION* macros. 24 * 25 * API methods that are part of the debug interface should use 26 * 27 * PREPARE_FOR_DEBUG_INTERFACE_EXECUTION_WITH_ISOLATE 28 * 29 * in a similar fashion to ENTER_V8. 30 * 31 * Don't use macros with DO_NOT_USE in their name. 32 * 33 * TODO(cbruni): Document LOG_API and other RuntimeCallStats macros. 34 * TODO(verwaest): All API methods should invoke one of the ENTER_V8* macros. 35 * TODO(verwaest): Remove calls form API methods to DO_NOT_USE macros. 36 */ 37 38#define API_RCS_SCOPE(isolate, class_name, function_name) \ 39 RCS_SCOPE(isolate, \ 40 i::RuntimeCallCounterId::kAPI_##class_name##_##function_name); 41 42#define ENTER_V8_DO_NOT_USE(isolate) i::VMState<v8::OTHER> __state__((isolate)) 43 44#define ENTER_V8_HELPER_DO_NOT_USE(isolate, context, class_name, \ 45 function_name, bailout_value, \ 46 HandleScopeClass, do_callback) \ 47 if (IsExecutionTerminatingCheck(isolate)) { \ 48 return bailout_value; \ 49 } \ 50 HandleScopeClass handle_scope(isolate); \ 51 CallDepthScope<do_callback> call_depth_scope(isolate, context); \ 52 API_RCS_SCOPE(isolate, class_name, function_name); \ 53 i::VMState<v8::OTHER> __state__((isolate)); \ 54 bool has_pending_exception = false 55 56#define PREPARE_FOR_DEBUG_INTERFACE_EXECUTION_WITH_ISOLATE(isolate, T) \ 57 if (IsExecutionTerminatingCheck(isolate)) { \ 58 return MaybeLocal<T>(); \ 59 } \ 60 InternalEscapableScope handle_scope(isolate); \ 61 CallDepthScope<false> call_depth_scope(isolate, v8::Local<v8::Context>()); \ 62 i::VMState<v8::OTHER> __state__((isolate)); \ 63 bool has_pending_exception = false 64 65#define PREPARE_FOR_EXECUTION_WITH_CONTEXT(context, class_name, function_name, \ 66 bailout_value, HandleScopeClass, \ 67 do_callback) \ 68 auto isolate = context.IsEmpty() \ 69 ? i::Isolate::Current() \ 70 : reinterpret_cast<i::Isolate*>(context->GetIsolate()); \ 71 ENTER_V8_HELPER_DO_NOT_USE(isolate, context, class_name, function_name, \ 72 bailout_value, HandleScopeClass, do_callback); 73 74#define PREPARE_FOR_EXECUTION(context, class_name, function_name, T) \ 75 PREPARE_FOR_EXECUTION_WITH_CONTEXT(context, class_name, function_name, \ 76 MaybeLocal<T>(), InternalEscapableScope, \ 77 false) 78 79#define ENTER_V8(isolate, context, class_name, function_name, bailout_value, \ 80 HandleScopeClass) \ 81 ENTER_V8_HELPER_DO_NOT_USE(isolate, context, class_name, function_name, \ 82 bailout_value, HandleScopeClass, true) 83 84#ifdef DEBUG 85#define ENTER_V8_NO_SCRIPT(isolate, context, class_name, function_name, \ 86 bailout_value, HandleScopeClass) \ 87 ENTER_V8_HELPER_DO_NOT_USE(isolate, context, class_name, function_name, \ 88 bailout_value, HandleScopeClass, false); \ 89 i::DisallowJavascriptExecutionDebugOnly __no_script__((isolate)) 90 91// Lightweight version for APIs that don't require an active context. 92#define ASSERT_NO_SCRIPT_NO_EXCEPTION(isolate) \ 93 i::DisallowJavascriptExecutionDebugOnly __no_script__((isolate)); \ 94 i::DisallowExceptions __no_exceptions__((isolate)) 95 96#define ENTER_V8_NO_SCRIPT_NO_EXCEPTION(isolate) \ 97 i::VMState<v8::OTHER> __state__((isolate)); \ 98 ASSERT_NO_SCRIPT_NO_EXCEPTION(isolate) 99 100#define ENTER_V8_FOR_NEW_CONTEXT(isolate) \ 101 i::VMState<v8::OTHER> __state__((isolate)); \ 102 i::DisallowExceptions __no_exceptions__((isolate)) 103#else 104#define ENTER_V8_NO_SCRIPT(isolate, context, class_name, function_name, \ 105 bailout_value, HandleScopeClass) \ 106 ENTER_V8_HELPER_DO_NOT_USE(isolate, context, class_name, function_name, \ 107 bailout_value, HandleScopeClass, false) 108 109#define ASSERT_NO_SCRIPT_NO_EXCEPTION(isolate) 110 111#define ENTER_V8_NO_SCRIPT_NO_EXCEPTION(isolate) \ 112 i::VMState<v8::OTHER> __state__((isolate)); 113 114#define ENTER_V8_FOR_NEW_CONTEXT(isolate) \ 115 i::VMState<v8::OTHER> __state__((isolate)); 116#endif // DEBUG 117 118#define EXCEPTION_BAILOUT_CHECK_SCOPED_DO_NOT_USE(isolate, value) \ 119 do { \ 120 if (has_pending_exception) { \ 121 call_depth_scope.Escape(); \ 122 return value; \ 123 } \ 124 } while (false) 125 126#define RETURN_ON_FAILED_EXECUTION(T) \ 127 EXCEPTION_BAILOUT_CHECK_SCOPED_DO_NOT_USE(isolate, MaybeLocal<T>()) 128 129#define RETURN_ON_FAILED_EXECUTION_PRIMITIVE(T) \ 130 EXCEPTION_BAILOUT_CHECK_SCOPED_DO_NOT_USE(isolate, Nothing<T>()) 131 132#define RETURN_ESCAPED(value) return handle_scope.Escape(value); 133