v8-jsi/src/node-api/js_runtime_api.h at main · microsoft/v8-jsi · GitHub

History

255 lines (202 loc) · 10.1 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

// Copyright (c) Microsoft Corporation.

// Licensed under the MIT License.

#ifndef SRC_JS_RUNTIME_API_H_

#define SRC_JS_RUNTIME_API_H_

#include "js_native_api.h"

// jsi_runtime forward declaration for jsr_runtime_get_jsi_runtime.

// The full opaque type is declared in jsi_abi/jsi_abi.h; forward-declared

// here so consumers do not need to pull in the JSI ABI header just to use

// jsr_runtime_get_jsi_runtime.

struct jsi_runtime;

// Node-API extensions required for JavaScript engine hosting.

// EXPERIMENTAL - NOT YET ABI-STABLE.

// This is a very early version of the APIs, which we consider experimental.

// They are not stable yet and are subject to change while we continue their

// development. Although they are C-based, they are NOT ABI-safe yet:

// signatures, struct fields, and enum values may change without notice. Do not

// depend on binary compatibility across builds. After some time we will

// stabilize the APIs, make them ABI-stable, and mark them "officially stable".

#define JSR_API NAPI_EXTERN napi_status NAPI_CDECL

EXTERN_C_START

typedef struct jsr_runtime_s* jsr_runtime;

typedef struct jsr_config_s* jsr_config;

typedef struct jsr_prepared_script_s* jsr_prepared_script;

typedef struct jsr_napi_env_scope_s* jsr_napi_env_scope;

typedef void(NAPI_CDECL* jsr_data_delete_cb)(void* data, void* deleter_data);

//=============================================================================

// jsr_runtime

//=============================================================================

JSR_API jsr_create_runtime(jsr_config config, jsr_runtime* runtime);

JSR_API jsr_delete_runtime(jsr_runtime runtime);

JSR_API jsr_runtime_get_node_api_env(jsr_runtime runtime, napi_env* env);

// dual-API accessor. Returns the underlying jsi_runtime so a consumer

// that started with jsr_create_runtime can also build a jsi::Runtime over

// the same V8 isolate (via JsiAbiRuntime). Output borrows from the

// jsr_runtime; do not call jsi_release on it.

JSR_API jsr_runtime_get_jsi_runtime(jsr_runtime runtime,

struct jsi_runtime** abi_runtime);

//=============================================================================

// jsr_config

//=============================================================================

JSR_API jsr_create_config(jsr_config* config);

JSR_API jsr_delete_config(jsr_config config);

JSR_API jsr_config_enable_inspector(jsr_config config, bool value);

JSR_API jsr_config_set_inspector_runtime_name(jsr_config config,

const char* name);

JSR_API jsr_config_set_inspector_port(jsr_config config, uint16_t port);

JSR_API jsr_config_set_inspector_break_on_start(jsr_config config, bool value);

JSR_API jsr_config_enable_gc_api(jsr_config config, bool value);

//=============================================================================

// jsr_config task runner

//=============================================================================

// A callback to run task

typedef void(NAPI_CDECL* jsr_task_run_cb)(void* task_data);

// A callback to post task to the task runner

typedef void(NAPI_CDECL* jsr_task_runner_post_task_cb)(

void* task_runner_data,

void* task_data,

jsr_task_run_cb task_run_cb,

jsr_data_delete_cb task_data_delete_cb,

void* deleter_data);

JSR_API jsr_config_set_task_runner(

jsr_config config,

void* task_runner_data,

jsr_task_runner_post_task_cb task_runner_post_task_cb,

jsr_data_delete_cb task_runner_data_delete_cb,

void* deleter_data);

//=============================================================================

// jsr_config script cache

//=============================================================================

typedef void(NAPI_CDECL* jsr_script_cache_load_cb)(

void* script_cache_data,

const char* source_url,

uint64_t source_hash,

const char* runtime_name,

uint64_t runtime_version,

const char* cache_tag,

const uint8_t** buffer,

size_t* buffer_size,

jsr_data_delete_cb* buffer_delete_cb,

void** deleter_data);

typedef void(NAPI_CDECL* jsr_script_cache_store_cb)(

void* script_cache_data,

const char* source_url,

uint64_t source_hash,

const char* runtime_name,

uint64_t runtime_version,

const char* cache_tag,

const uint8_t* buffer,

size_t buffer_size,

jsr_data_delete_cb buffer_delete_cb,

void* deleter_data);

JSR_API jsr_config_set_script_cache(

jsr_config config,

void* script_cache_data,

jsr_script_cache_load_cb script_cache_load_cb,

jsr_script_cache_store_cb script_cache_store_cb,

jsr_data_delete_cb script_cache_data_delete_cb,

void* deleter_data);

//=============================================================================

// napi_env scope

//=============================================================================

// Opens the napi_env scope in the current thread.

// Calling Node-API functions without the opened scope may cause a failure.

// The scope must be closed by the jsr_close_napi_env_scope call.

JSR_API jsr_open_napi_env_scope(napi_env env, jsr_napi_env_scope* scope);

// Closes the napi_env scope in the current thread. It must match to the

// jsr_open_napi_env_scope call.

JSR_API jsr_close_napi_env_scope(napi_env env, jsr_napi_env_scope scope);

//=============================================================================

// Additional functions to implement JSI

//=============================================================================

// To implement JSI description()

JSR_API jsr_get_description(napi_env env, const char** result);

// To implement JSI queueMicrotask()

JSR_API

jsr_queue_microtask(napi_env env, napi_value callback);

// To implement JSI drainMicrotasks()

JSR_API

jsr_drain_microtasks(napi_env env, int32_t max_count_hint, bool* result);

// To implement JSI isInspectable()

JSR_API jsr_is_inspectable(napi_env env, bool* result);

//=============================================================================

// Script preparing and running.

// Script is usually converted to byte code, or in other words - prepared - for

// execution. Then, we can run the prepared script.

//=============================================================================

// Run script with source URL.

JSR_API jsr_run_script(napi_env env,

napi_value source,

const char* source_url,

napi_value* result);

// Prepare the script for running.

JSR_API jsr_create_prepared_script(napi_env env,

const uint8_t* script_data,

size_t script_length,

jsr_data_delete_cb script_delete_cb,

void* deleter_data,

const char* source_url,

jsr_prepared_script* result);

// Delete the prepared script.

JSR_API jsr_delete_prepared_script(napi_env env,

jsr_prepared_script prepared_script);

// Run the prepared script.

JSR_API jsr_prepared_script_run(napi_env env,

jsr_prepared_script prepared_script,

napi_value* result);

//=============================================================================

// JSI instrumentation

//=============================================================================

// Generic callback for string output

typedef void(NAPI_CDECL* jsr_string_output_cb)(void* ctx,

const char* data,

size_t len);

// Gets garbage collection statistics as a JSON-encoded string

JSR_API jsr_instrumentation_get_gc_stats(napi_env env,

jsr_string_output_cb cb,

void* cb_ctx);

typedef void(NAPI_CDECL* jsr_heap_info_cb)(void* ctx,

const char* key,

int64_t value);

// Gets current heap information as a struct

JSR_API jsr_instrumentation_get_heap_info(napi_env env,

bool include_expensive,

jsr_heap_info_cb cb,

void* cb_ctx);

JSR_API jsr_instrumentation_collect_garbage(napi_env env, const char* cause);

// Starts heap sampling profiler

JSR_API jsr_instrumentation_start_heap_sampling(napi_env env,

size_t sampling_interval);

// Stops heap sampling profiler and returns the result as JSON

JSR_API jsr_instrumentation_stop_heap_sampling(napi_env env,

jsr_string_output_cb cb,

void* cb_ctx);

// Creates a heap snapshot and saves it to a file

JSR_API jsr_instrumentation_create_heap_snapshot(napi_env env,

bool capture_numeric_value,

jsr_string_output_cb cb,

void* cb_ctx);

//=============================================================================

// Functions to support unit tests.

//=============================================================================

// Provides a hint to run garbage collection.

// It is typically used for unit tests.

// It requires enabling GC by calling jsr_config_enable_gc_api.

JSR_API jsr_collect_garbage(napi_env env);

// Checks if the environment has an unhandled promise rejection.

JSR_API jsr_has_unhandled_promise_rejection(napi_env env, bool* result);

// Gets and clears the last unhandled promise rejection.

JSR_API jsr_get_and_clear_last_unhandled_promise_rejection(napi_env env,

napi_value* result);

// Create new napi_env for the runtime.

JSR_API jsr_create_node_api_env(napi_env root_env,

int32_t api_version,

napi_env* env);

// Run task in the environment context.

JSR_API jsr_run_task(napi_env env, jsr_task_run_cb task_cb, void* data);

EXTERN_C_END

#endif // !SRC_JS_RUNTIME_API_H_

v8-jsi/src/node-api/js_runtime_api.h at main · microsoft/v8-jsi · GitHub

Uh oh!

Expand file tree

Breadcrumbs

js_runtime_api.h

Latest commit

History

Breadcrumbs

js_runtime_api.h

File metadata and controls