1 // Copyright Joyent, Inc. and other Node contributors.
2 //
3 // Permission is hereby granted, free of charge, to any person obtaining a
4 // copy of this software and associated documentation files (the
5 // "Software"), to deal in the Software without restriction, including
6 // without limitation the rights to use, copy, modify, merge, publish,
7 // distribute, sublicense, and/or sell copies of the Software, and to permit
8 // persons to whom the Software is furnished to do so, subject to the
9 // following conditions:
10 //
11 // The above copyright notice and this permission notice shall be included
12 // in all copies or substantial portions of the Software.
13 //
14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
15 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
17 // NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
18 // DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
19 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
20 // USE OR OTHER DEALINGS IN THE SOFTWARE.
21
22 #ifndef SRC_NODE_H_
23 #define SRC_NODE_H_
24
25 #ifdef _WIN32
26 # ifndef BUILDING_NODE_EXTENSION
27 # define NODE_EXTERN __declspec(dllexport)
28 # else
29 # define NODE_EXTERN __declspec(dllimport)
30 # endif
31 #else
32 # define NODE_EXTERN __attribute__((visibility("default")))
33 #endif
34
35 #ifdef BUILDING_NODE_EXTENSION
36 # undef BUILDING_V8_SHARED
37 # undef BUILDING_UV_SHARED
38 # define USING_V8_SHARED 1
39 # define USING_UV_SHARED 1
40 #endif
41
42 // This should be defined in make system.
43 // See issue https://github.com/nodejs/node-v0.x-archive/issues/1236
44 #if defined(__MINGW32__) || defined(_MSC_VER)
45 #ifndef _WIN32_WINNT
46 # define _WIN32_WINNT 0x0600 // Windows Server 2008
47 #endif
48
49 #ifndef NOMINMAX
50 # define NOMINMAX
51 #endif
52
53 #endif
54
55 #if defined(_MSC_VER)
56 #define PATH_MAX MAX_PATH
57 #endif
58
59 #ifdef _WIN32
60 # define SIGKILL 9
61 #endif
62
63 #if (__GNUC__ >= 8) && !defined(__clang__)
64 #pragma GCC diagnostic push
65 #pragma GCC diagnostic ignored "-Wcast-function-type"
66 #endif
67 #include "v8.h" // NOLINT(build/include_order)
68 #if (__GNUC__ >= 8) && !defined(__clang__)
69 #pragma GCC diagnostic pop
70 #endif
71
72 #include "v8-platform.h" // NOLINT(build/include_order)
73 #include "node_version.h" // NODE_MODULE_VERSION
74
75 #include <memory>
76 #include <functional>
77
78 #define NODE_MAKE_VERSION(major, minor, patch) \
79 ((major) * 0x1000 + (minor) * 0x100 + (patch))
80
81 #ifdef __clang__
82 # define NODE_CLANG_AT_LEAST(major, minor, patch) \
83 (NODE_MAKE_VERSION(major, minor, patch) <= \
84 NODE_MAKE_VERSION(__clang_major__, __clang_minor__, __clang_patchlevel__))
85 #else
86 # define NODE_CLANG_AT_LEAST(major, minor, patch) (0)
87 #endif
88
89 #ifdef __GNUC__
90 # define NODE_GNUC_AT_LEAST(major, minor, patch) \
91 (NODE_MAKE_VERSION(major, minor, patch) <= \
92 NODE_MAKE_VERSION(__GNUC__, __GNUC_MINOR__, __GNUC_PATCHLEVEL__))
93 #else
94 # define NODE_GNUC_AT_LEAST(major, minor, patch) (0)
95 #endif
96
97 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
98 # define NODE_DEPRECATED(message, declarator) declarator
99 #else // NODE_WANT_INTERNALS
100 # if NODE_CLANG_AT_LEAST(2, 9, 0) || NODE_GNUC_AT_LEAST(4, 5, 0)
101 # define NODE_DEPRECATED(message, declarator) \
102 __attribute__((deprecated(message))) declarator
103 # elif defined(_MSC_VER)
104 # define NODE_DEPRECATED(message, declarator) \
105 __declspec(deprecated) declarator
106 # else
107 # define NODE_DEPRECATED(message, declarator) declarator
108 # endif
109 #endif
110
111 // Forward-declare libuv loop
112 struct uv_loop_s;
113
114 // Forward-declare these functions now to stop MSVS from becoming
115 // terminally confused when it's done in node_internals.h
116 namespace node {
117
118 namespace tracing {
119
120 class TracingController;
121
122 }
123
124 NODE_EXTERN v8::Local<v8::Value> ErrnoException(v8::Isolate* isolate,
125 int errorno,
126 const char* syscall = nullptr,
127 const char* message = nullptr,
128 const char* path = nullptr);
129 NODE_EXTERN v8::Local<v8::Value> UVException(v8::Isolate* isolate,
130 int errorno,
131 const char* syscall = nullptr,
132 const char* message = nullptr,
133 const char* path = nullptr,
134 const char* dest = nullptr);
135
136 NODE_DEPRECATED("Use ErrnoException(isolate, ...)",
137 inline v8::Local<v8::Value> ErrnoException(
138 int errorno,
139 const char* syscall = nullptr,
140 const char* message = nullptr,
141 const char* path = nullptr) {
142 return ErrnoException(v8::Isolate::GetCurrent(),
143 errorno,
144 syscall,
145 message,
146 path);
147 })
148
149 NODE_DEPRECATED("Use UVException(isolate, ...)",
150 inline v8::Local<v8::Value> UVException(int errorno,
151 const char* syscall = nullptr,
152 const char* message = nullptr,
153 const char* path = nullptr) {
154 return UVException(v8::Isolate::GetCurrent(),
155 errorno,
156 syscall,
157 message,
158 path);
159 })
160
161 /*
162 * These methods need to be called in a HandleScope.
163 *
164 * It is preferred that you use the `MakeCallback` overloads taking
165 * `async_context` arguments.
166 */
167
168 NODE_DEPRECATED("Use MakeCallback(..., async_context)",
169 NODE_EXTERN v8::Local<v8::Value> MakeCallback(
170 v8::Isolate* isolate,
171 v8::Local<v8::Object> recv,
172 const char* method,
173 int argc,
174 v8::Local<v8::Value>* argv));
175 NODE_DEPRECATED("Use MakeCallback(..., async_context)",
176 NODE_EXTERN v8::Local<v8::Value> MakeCallback(
177 v8::Isolate* isolate,
178 v8::Local<v8::Object> recv,
179 v8::Local<v8::String> symbol,
180 int argc,
181 v8::Local<v8::Value>* argv));
182 NODE_DEPRECATED("Use MakeCallback(..., async_context)",
183 NODE_EXTERN v8::Local<v8::Value> MakeCallback(
184 v8::Isolate* isolate,
185 v8::Local<v8::Object> recv,
186 v8::Local<v8::Function> callback,
187 int argc,
188 v8::Local<v8::Value>* argv));
189
190 } // namespace node
191
192 #include <cassert>
193 #include <cstdint>
194
195 #ifndef NODE_STRINGIFY
196 # define NODE_STRINGIFY(n) NODE_STRINGIFY_HELPER(n)
197 # define NODE_STRINGIFY_HELPER(n) #n
198 #endif
199
200 #ifdef _WIN32
201 #if !defined(_SSIZE_T_) && !defined(_SSIZE_T_DEFINED)
202 typedef intptr_t ssize_t;
203 # define _SSIZE_T_
204 # define _SSIZE_T_DEFINED
205 #endif
206 #else // !_WIN32
207 # include <sys/types.h> // size_t, ssize_t
208 #endif // _WIN32
209
210
211 namespace node {
212
213 class IsolateData;
214 class Environment;
215
216 // TODO(addaleax): Officially deprecate this and replace it with something
217 // better suited for a public embedder API.
218 NODE_EXTERN int Start(int argc, char* argv[]);
219
220 // Tear down Node.js while it is running (there are active handles
221 // in the loop and / or actively executing JavaScript code). This also stops
222 // all Workers that may have been started earlier.
223 NODE_EXTERN int Stop(Environment* env);
224
225 // TODO(addaleax): Officially deprecate this and replace it with something
226 // better suited for a public embedder API.
227 // It is recommended to use InitializeNodeWithArgs() instead as an embedder.
228 // Init() calls InitializeNodeWithArgs() and exits the process with the exit
229 // code returned from it.
230 NODE_EXTERN void Init(int* argc,
231 const char** argv,
232 int* exec_argc,
233 const char*** exec_argv);
234 // Set up per-process state needed to run Node.js. This will consume arguments
235 // from argv, fill exec_argv, and possibly add errors resulting from parsing
236 // the arguments to `errors`. The return value is a suggested exit code for the
237 // program; If it is 0, then initializing Node.js succeeded.
238 NODE_EXTERN int InitializeNodeWithArgs(std::vector<std::string>* argv,
239 std::vector<std::string>* exec_argv,
240 std::vector<std::string>* errors);
241
242 enum OptionEnvvarSettings {
243 kAllowedInEnvironment,
244 kDisallowedInEnvironment
245 };
246
247 NODE_EXTERN int ProcessGlobalArgs(std::vector<std::string>* args,
248 std::vector<std::string>* exec_args,
249 std::vector<std::string>* errors,
250 OptionEnvvarSettings settings);
251
252 class NodeArrayBufferAllocator;
253
254 // An ArrayBuffer::Allocator class with some Node.js-specific tweaks. If you do
255 // not have to use another allocator, using this class is recommended:
256 // - It supports Buffer.allocUnsafe() and Buffer.allocUnsafeSlow() with
257 // uninitialized memory.
258 // - It supports transferring, rather than copying, ArrayBuffers when using
259 // MessagePorts.
260 class NODE_EXTERN ArrayBufferAllocator : public v8::ArrayBuffer::Allocator {
261 public:
262 // If `always_debug` is true, create an ArrayBuffer::Allocator instance
263 // that performs additional integrity checks (e.g. make sure that only memory
264 // that was allocated by the it is also freed by it).
265 // This can also be set using the --debug-arraybuffer-allocations flag.
266 static std::unique_ptr<ArrayBufferAllocator> Create(
267 bool always_debug = false);
268
269 private:
270 virtual NodeArrayBufferAllocator* GetImpl() = 0;
271
272 friend class IsolateData;
273 };
274
275 // Legacy equivalents for ArrayBufferAllocator::Create().
276 NODE_EXTERN ArrayBufferAllocator* CreateArrayBufferAllocator();
277 NODE_EXTERN void FreeArrayBufferAllocator(ArrayBufferAllocator* allocator);
278
279 class NODE_EXTERN MultiIsolatePlatform : public v8::Platform {
280 public:
281 ~MultiIsolatePlatform() override = default;
282 // Returns true if work was dispatched or executed. New tasks that are
283 // posted during flushing of the queue are postponed until the next
284 // flushing.
285 virtual bool FlushForegroundTasks(v8::Isolate* isolate) = 0;
286 virtual void DrainTasks(v8::Isolate* isolate) = 0;
287
288 // TODO(addaleax): Remove this, it is unnecessary.
289 // This would currently be called before `UnregisterIsolate()` but will be
290 // folded into it in the future.
291 virtual void CancelPendingDelayedTasks(v8::Isolate* isolate);
292
293 // This needs to be called between the calls to `Isolate::Allocate()` and
294 // `Isolate::Initialize()`, so that initialization can already start
295 // using the platform.
296 // When using `NewIsolate()`, this is taken care of by that function.
297 // This function may only be called once per `Isolate`.
298 virtual void RegisterIsolate(v8::Isolate* isolate,
299 struct uv_loop_s* loop) = 0;
300
301 // This function may only be called once per `Isolate`, and discard any
302 // pending delayed tasks scheduled for that isolate.
303 // This needs to be called right before calling `Isolate::Dispose()`.
304 virtual void UnregisterIsolate(v8::Isolate* isolate) = 0;
305
306 // The platform should call the passed function once all state associated
307 // with the given isolate has been cleaned up. This can, but does not have to,
308 // happen asynchronously.
309 virtual void AddIsolateFinishedCallback(v8::Isolate* isolate,
310 void (*callback)(void*),
311 void* data) = 0;
312
313 static std::unique_ptr<MultiIsolatePlatform> Create(
314 int thread_pool_size,
315 v8::TracingController* tracing_controller = nullptr);
316 };
317
318 enum IsolateSettingsFlags {
319 MESSAGE_LISTENER_WITH_ERROR_LEVEL = 1 << 0,
320 DETAILED_SOURCE_POSITIONS_FOR_PROFILING = 1 << 1,
321 SHOULD_NOT_SET_PROMISE_REJECTION_CALLBACK = 1 << 2
322 };
323
324 struct IsolateSettings {
325 uint64_t flags = MESSAGE_LISTENER_WITH_ERROR_LEVEL |
326 DETAILED_SOURCE_POSITIONS_FOR_PROFILING;
327 v8::MicrotasksPolicy policy = v8::MicrotasksPolicy::kExplicit;
328
329 // Error handling callbacks
330 v8::Isolate::AbortOnUncaughtExceptionCallback
331 should_abort_on_uncaught_exception_callback = nullptr;
332 v8::FatalErrorCallback fatal_error_callback = nullptr;
333 v8::PrepareStackTraceCallback prepare_stack_trace_callback = nullptr;
334
335 // Miscellaneous callbacks
336 v8::PromiseRejectCallback promise_reject_callback = nullptr;
337 v8::AllowWasmCodeGenerationCallback
338 allow_wasm_code_generation_callback = nullptr;
339 v8::HostCleanupFinalizationGroupCallback
340 host_cleanup_finalization_group_callback = nullptr;
341 };
342
343 // Overriding IsolateSettings may produce unexpected behavior
344 // in Node.js core functionality, so proceed at your own risk.
345 NODE_EXTERN void SetIsolateUpForNode(v8::Isolate* isolate,
346 const IsolateSettings& settings);
347
348 // Set a number of callbacks for the `isolate`, in particular the Node.js
349 // uncaught exception listener.
350 NODE_EXTERN void SetIsolateUpForNode(v8::Isolate* isolate);
351
352 // Creates a new isolate with Node.js-specific settings.
353 // This is a convenience method equivalent to using SetIsolateCreateParams(),
354 // Isolate::Allocate(), MultiIsolatePlatform::RegisterIsolate(),
355 // Isolate::Initialize(), and SetIsolateUpForNode().
356 NODE_EXTERN v8::Isolate* NewIsolate(ArrayBufferAllocator* allocator,
357 struct uv_loop_s* event_loop);
358 NODE_EXTERN v8::Isolate* NewIsolate(ArrayBufferAllocator* allocator,
359 struct uv_loop_s* event_loop,
360 MultiIsolatePlatform* platform);
361
362 // Creates a new context with Node.js-specific tweaks.
363 NODE_EXTERN v8::Local<v8::Context> NewContext(
364 v8::Isolate* isolate,
365 v8::Local<v8::ObjectTemplate> object_template =
366 v8::Local<v8::ObjectTemplate>());
367
368 // Runs Node.js-specific tweaks on an already constructed context
369 // Return value indicates success of operation
370 NODE_EXTERN bool InitializeContext(v8::Local<v8::Context> context);
371
372 // If `platform` is passed, it will be used to register new Worker instances.
373 // It can be `nullptr`, in which case creating new Workers inside of
374 // Environments that use this `IsolateData` will not work.
375 NODE_EXTERN IsolateData* CreateIsolateData(
376 v8::Isolate* isolate,
377 struct uv_loop_s* loop,
378 MultiIsolatePlatform* platform = nullptr,
379 ArrayBufferAllocator* allocator = nullptr);
380 NODE_EXTERN void FreeIsolateData(IsolateData* isolate_data);
381
382 struct ThreadId {
383 uint64_t id = static_cast<uint64_t>(-1);
384 };
385 NODE_EXTERN ThreadId AllocateEnvironmentThreadId();
386
387 namespace EnvironmentFlags {
388 enum Flags : uint64_t {
389 kNoFlags = 0,
390 // Use the default behaviour for Node.js instances.
391 kDefaultFlags = 1 << 0,
392 // Controls whether this Environment is allowed to affect per-process state
393 // (e.g. cwd, process title, uid, etc.).
394 // This is set when using kDefaultFlags.
395 kOwnsProcessState = 1 << 1,
396 // Set if this Environment instance is associated with the global inspector
397 // handling code (i.e. listening on SIGUSR1).
398 // This is set when using kDefaultFlags.
399 kOwnsInspector = 1 << 2,
400 // Set if Node.js should not run its own esm loader. This is needed by some
401 // embedders, because it's possible for the Node.js esm loader to conflict
402 // with another one in an embedder environment, e.g. Blink's in Chromium.
403 kNoRegisterESMLoader = 1 << 3,
404 // Set this flag to make Node.js track "raw" file descriptors, i.e. managed
405 // by fs.open() and fs.close(), and close them during FreeEnvironment().
406 kTrackUnmanagedFds = 1 << 4
407 };
408 } // namespace EnvironmentFlags
409
410 struct InspectorParentHandle {
411 virtual ~InspectorParentHandle();
412 };
413
414 // TODO(addaleax): Maybe move per-Environment options parsing here.
415 // Returns nullptr when the Environment cannot be created e.g. there are
416 // pending JavaScript exceptions.
417 // It is recommended to use the second variant taking a flags argument.
418 NODE_EXTERN Environment* CreateEnvironment(IsolateData* isolate_data,
419 v8::Local<v8::Context> context,
420 int argc,
421 const char* const* argv,
422 int exec_argc,
423 const char* const* exec_argv);
424 NODE_EXTERN Environment* CreateEnvironment(
425 IsolateData* isolate_data,
426 v8::Local<v8::Context> context,
427 const std::vector<std::string>& args,
428 const std::vector<std::string>& exec_args,
429 EnvironmentFlags::Flags flags = EnvironmentFlags::kDefaultFlags,
430 ThreadId thread_id = {} /* allocates a thread id automatically */,
431 std::unique_ptr<InspectorParentHandle> inspector_parent_handle = {});
432
433 // Returns a handle that can be passed to `LoadEnvironment()`, making the
434 // child Environment accessible to the inspector as if it were a Node.js Worker.
435 // `child_thread_id` can be created using `AllocateEnvironmentThreadId()`
436 // and then later passed on to `CreateEnvironment()` to create the child
437 // Environment, together with the inspector handle.
438 // This method should not be called while the parent Environment is active
439 // on another thread.
440 NODE_EXTERN std::unique_ptr<InspectorParentHandle> GetInspectorParentHandle(
441 Environment* parent_env,
442 ThreadId child_thread_id,
443 const char* child_url);
444
445 struct StartExecutionCallbackInfo {
446 v8::Local<v8::Object> process_object;
447 v8::Local<v8::Function> native_require;
448 };
449
450 using StartExecutionCallback =
451 std::function<v8::MaybeLocal<v8::Value>(const StartExecutionCallbackInfo&)>;
452
453 // TODO(addaleax): Deprecate this in favour of the MaybeLocal<> overload.
454 NODE_EXTERN void LoadEnvironment(Environment* env);
455 // The `InspectorParentHandle` arguments here are ignored and not used.
456 // For passing `InspectorParentHandle`, use `CreateEnvironment()`.
457 NODE_EXTERN v8::MaybeLocal<v8::Value> LoadEnvironment(
458 Environment* env,
459 StartExecutionCallback cb,
460 std::unique_ptr<InspectorParentHandle> ignored_donotuse_removeme = {});
461 NODE_EXTERN v8::MaybeLocal<v8::Value> LoadEnvironment(
462 Environment* env,
463 const char* main_script_source_utf8,
464 std::unique_ptr<InspectorParentHandle> ignored_donotuse_removeme = {});
465 NODE_EXTERN void FreeEnvironment(Environment* env);
466
467 // Set a callback that is called when process.exit() is called from JS,
468 // overriding the default handler.
469 // It receives the Environment* instance and the exit code as arguments.
470 // This could e.g. call Stop(env); in order to terminate execution and stop
471 // the event loop.
472 // The default handler calls Stop(), disposes of the global V8 platform
473 // instance, if one is being used, and calls exit().
474 NODE_EXTERN void SetProcessExitHandler(
475 Environment* env,
476 std::function<void(Environment*, int)>&& handler);
477 NODE_EXTERN void DefaultProcessExitHandler(Environment* env, int exit_code);
478
479 // This may return nullptr if context is not associated with a Node instance.
480 NODE_EXTERN Environment* GetCurrentEnvironment(v8::Local<v8::Context> context);
481
482 NODE_EXTERN void OnFatalError(const char* location, const char* message);
483 NODE_EXTERN void PromiseRejectCallback(v8::PromiseRejectMessage message);
484 NODE_EXTERN bool AllowWasmCodeGenerationCallback(v8::Local<v8::Context> context,
485 v8::Local<v8::String>);
486 NODE_EXTERN bool ShouldAbortOnUncaughtException(v8::Isolate* isolate);
487 NODE_EXTERN v8::MaybeLocal<v8::Value> PrepareStackTraceCallback(
488 v8::Local<v8::Context> context,
489 v8::Local<v8::Value> exception,
490 v8::Local<v8::Array> trace);
491
492 // This returns the MultiIsolatePlatform used in the main thread of Node.js.
493 // If NODE_USE_V8_PLATFORM has not been defined when Node.js was built,
494 // it returns nullptr.
495 // TODO(addaleax): Deprecate in favour of GetMultiIsolatePlatform().
496 NODE_EXTERN MultiIsolatePlatform* GetMainThreadMultiIsolatePlatform();
497 // This returns the MultiIsolatePlatform used for an Environment or IsolateData
498 // instance, if one exists.
499 NODE_EXTERN MultiIsolatePlatform* GetMultiIsolatePlatform(Environment* env);
500 NODE_EXTERN MultiIsolatePlatform* GetMultiIsolatePlatform(IsolateData* env);
501
502 // Legacy variants of MultiIsolatePlatform::Create().
503 // TODO(addaleax): Deprecate in favour of the v8::TracingController variant.
504 NODE_EXTERN MultiIsolatePlatform* CreatePlatform(
505 int thread_pool_size,
506 node::tracing::TracingController* tracing_controller);
507 NODE_EXTERN MultiIsolatePlatform* CreatePlatform(
508 int thread_pool_size,
509 v8::TracingController* tracing_controller);
510 NODE_EXTERN void FreePlatform(MultiIsolatePlatform* platform);
511
512 // Get/set the currently active tracing controller. Using CreatePlatform()
513 // will implicitly set this by default. This is global and should be initialized
514 // along with the v8::Platform instance that is being used. `controller`
515 // is allowed to be `nullptr`.
516 // This is used for tracing events from Node.js itself. V8 uses the tracing
517 // controller returned from the active `v8::Platform` instance.
518 NODE_EXTERN v8::TracingController* GetTracingController();
519 NODE_EXTERN void SetTracingController(v8::TracingController* controller);
520
521 NODE_EXTERN void EmitBeforeExit(Environment* env);
522 NODE_EXTERN int EmitExit(Environment* env);
523 NODE_EXTERN void RunAtExit(Environment* env);
524
525 // This may return nullptr if the current v8::Context is not associated
526 // with a Node instance.
527 NODE_EXTERN struct uv_loop_s* GetCurrentEventLoop(v8::Isolate* isolate);
528
529 /* Converts a unixtime to V8 Date */
530 NODE_DEPRECATED("Use v8::Date::New() directly",
531 inline v8::Local<v8::Value> NODE_UNIXTIME_V8(double time) {
532 return v8::Date::New(
533 v8::Isolate::GetCurrent()->GetCurrentContext(),
534 1000 * time)
535 .ToLocalChecked();
536 })
537 #define NODE_UNIXTIME_V8 node::NODE_UNIXTIME_V8
538 NODE_DEPRECATED("Use v8::Date::ValueOf() directly",
NODE_V8_UNIXTIME(v8::Local<v8::Date> date)539 inline double NODE_V8_UNIXTIME(v8::Local<v8::Date> date) {
540 return date->ValueOf() / 1000;
541 })
542 #define NODE_V8_UNIXTIME node::NODE_V8_UNIXTIME
543
544 #define NODE_DEFINE_CONSTANT(target, constant) \
545 do { \
546 v8::Isolate* isolate = target->GetIsolate(); \
547 v8::Local<v8::Context> context = isolate->GetCurrentContext(); \
548 v8::Local<v8::String> constant_name = \
549 v8::String::NewFromUtf8(isolate, #constant, \
550 v8::NewStringType::kInternalized).ToLocalChecked(); \
551 v8::Local<v8::Number> constant_value = \
552 v8::Number::New(isolate, static_cast<double>(constant)); \
553 v8::PropertyAttribute constant_attributes = \
554 static_cast<v8::PropertyAttribute>(v8::ReadOnly | v8::DontDelete); \
555 (target)->DefineOwnProperty(context, \
556 constant_name, \
557 constant_value, \
558 constant_attributes).Check(); \
559 } \
560 while (0)
561
562 #define NODE_DEFINE_HIDDEN_CONSTANT(target, constant) \
563 do { \
564 v8::Isolate* isolate = target->GetIsolate(); \
565 v8::Local<v8::Context> context = isolate->GetCurrentContext(); \
566 v8::Local<v8::String> constant_name = \
567 v8::String::NewFromUtf8(isolate, #constant, \
568 v8::NewStringType::kInternalized) \
569 .ToLocalChecked(); \
570 v8::Local<v8::Number> constant_value = \
571 v8::Number::New(isolate, static_cast<double>(constant)); \
572 v8::PropertyAttribute constant_attributes = \
573 static_cast<v8::PropertyAttribute>(v8::ReadOnly | \
574 v8::DontDelete | \
575 v8::DontEnum); \
576 (target)->DefineOwnProperty(context, \
577 constant_name, \
578 constant_value, \
579 constant_attributes).Check(); \
580 } \
581 while (0)
582
583 // Used to be a macro, hence the uppercase name.
584 inline void NODE_SET_METHOD(v8::Local<v8::Template> recv,
585 const char* name,
586 v8::FunctionCallback callback) {
587 v8::Isolate* isolate = v8::Isolate::GetCurrent();
588 v8::HandleScope handle_scope(isolate);
589 v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New(isolate,
590 callback);
591 v8::Local<v8::String> fn_name = v8::String::NewFromUtf8(isolate, name,
592 v8::NewStringType::kInternalized).ToLocalChecked();
593 t->SetClassName(fn_name);
594 recv->Set(fn_name, t);
595 }
596
597 // Used to be a macro, hence the uppercase name.
NODE_SET_METHOD(v8::Local<v8::Object> recv,const char * name,v8::FunctionCallback callback)598 inline void NODE_SET_METHOD(v8::Local<v8::Object> recv,
599 const char* name,
600 v8::FunctionCallback callback) {
601 v8::Isolate* isolate = v8::Isolate::GetCurrent();
602 v8::HandleScope handle_scope(isolate);
603 v8::Local<v8::Context> context = isolate->GetCurrentContext();
604 v8::Local<v8::FunctionTemplate> t = v8::FunctionTemplate::New(isolate,
605 callback);
606 v8::Local<v8::Function> fn = t->GetFunction(context).ToLocalChecked();
607 v8::Local<v8::String> fn_name = v8::String::NewFromUtf8(isolate, name,
608 v8::NewStringType::kInternalized).ToLocalChecked();
609 fn->SetName(fn_name);
610 recv->Set(context, fn_name, fn).Check();
611 }
612 #define NODE_SET_METHOD node::NODE_SET_METHOD
613
614 // Used to be a macro, hence the uppercase name.
615 // Not a template because it only makes sense for FunctionTemplates.
NODE_SET_PROTOTYPE_METHOD(v8::Local<v8::FunctionTemplate> recv,const char * name,v8::FunctionCallback callback)616 inline void NODE_SET_PROTOTYPE_METHOD(v8::Local<v8::FunctionTemplate> recv,
617 const char* name,
618 v8::FunctionCallback callback) {
619 v8::Isolate* isolate = v8::Isolate::GetCurrent();
620 v8::HandleScope handle_scope(isolate);
621 v8::Local<v8::Signature> s = v8::Signature::New(isolate, recv);
622 v8::Local<v8::FunctionTemplate> t =
623 v8::FunctionTemplate::New(isolate, callback, v8::Local<v8::Value>(), s);
624 v8::Local<v8::String> fn_name = v8::String::NewFromUtf8(isolate, name,
625 v8::NewStringType::kInternalized).ToLocalChecked();
626 t->SetClassName(fn_name);
627 recv->PrototypeTemplate()->Set(fn_name, t);
628 }
629 #define NODE_SET_PROTOTYPE_METHOD node::NODE_SET_PROTOTYPE_METHOD
630
631 // BINARY is a deprecated alias of LATIN1.
632 enum encoding {ASCII, UTF8, BASE64, UCS2, BINARY, HEX, BUFFER, LATIN1 = BINARY};
633
634 NODE_EXTERN enum encoding ParseEncoding(
635 v8::Isolate* isolate,
636 v8::Local<v8::Value> encoding_v,
637 enum encoding default_encoding = LATIN1);
638
639 NODE_EXTERN void FatalException(v8::Isolate* isolate,
640 const v8::TryCatch& try_catch);
641
642 NODE_EXTERN v8::Local<v8::Value> Encode(v8::Isolate* isolate,
643 const char* buf,
644 size_t len,
645 enum encoding encoding = LATIN1);
646
647 // Warning: This reverses endianness on Big Endian platforms, even though the
648 // signature using uint16_t implies that it should not.
649 NODE_EXTERN v8::Local<v8::Value> Encode(v8::Isolate* isolate,
650 const uint16_t* buf,
651 size_t len);
652
653 // Returns -1 if the handle was not valid for decoding
654 NODE_EXTERN ssize_t DecodeBytes(v8::Isolate* isolate,
655 v8::Local<v8::Value>,
656 enum encoding encoding = LATIN1);
657 // returns bytes written.
658 NODE_EXTERN ssize_t DecodeWrite(v8::Isolate* isolate,
659 char* buf,
660 size_t buflen,
661 v8::Local<v8::Value>,
662 enum encoding encoding = LATIN1);
663 #ifdef _WIN32
664 NODE_EXTERN v8::Local<v8::Value> WinapiErrnoException(
665 v8::Isolate* isolate,
666 int errorno,
667 const char* syscall = nullptr,
668 const char* msg = "",
669 const char* path = nullptr);
670 #endif
671
672 const char* signo_string(int errorno);
673
674
675 typedef void (*addon_register_func)(
676 v8::Local<v8::Object> exports,
677 v8::Local<v8::Value> module,
678 void* priv);
679
680 typedef void (*addon_context_register_func)(
681 v8::Local<v8::Object> exports,
682 v8::Local<v8::Value> module,
683 v8::Local<v8::Context> context,
684 void* priv);
685
686 enum ModuleFlags {
687 kLinked = 0x02
688 };
689
690 struct node_module {
691 int nm_version;
692 unsigned int nm_flags;
693 void* nm_dso_handle;
694 const char* nm_filename;
695 node::addon_register_func nm_register_func;
696 node::addon_context_register_func nm_context_register_func;
697 const char* nm_modname;
698 void* nm_priv;
699 struct node_module* nm_link;
700 };
701
702 extern "C" NODE_EXTERN void node_module_register(void* mod);
703
704 #ifdef _WIN32
705 # define NODE_MODULE_EXPORT __declspec(dllexport)
706 #else
707 # define NODE_MODULE_EXPORT __attribute__((visibility("default")))
708 #endif
709
710 #ifdef NODE_SHARED_MODE
711 # define NODE_CTOR_PREFIX
712 #else
713 # define NODE_CTOR_PREFIX static
714 #endif
715
716 #if defined(_MSC_VER)
717 #pragma section(".CRT$XCU", read)
718 #define NODE_C_CTOR(fn) \
719 NODE_CTOR_PREFIX void __cdecl fn(void); \
720 __declspec(dllexport, allocate(".CRT$XCU")) \
721 void (__cdecl*fn ## _)(void) = fn; \
722 NODE_CTOR_PREFIX void __cdecl fn(void)
723 #else
724 #define NODE_C_CTOR(fn) \
725 NODE_CTOR_PREFIX void fn(void) __attribute__((constructor)); \
726 NODE_CTOR_PREFIX void fn(void)
727 #endif
728
729 #define NODE_MODULE_X(modname, regfunc, priv, flags) \
730 extern "C" { \
731 static node::node_module _module = \
732 { \
733 NODE_MODULE_VERSION, \
734 flags, \
735 NULL, /* NOLINT (readability/null_usage) */ \
736 __FILE__, \
737 (node::addon_register_func) (regfunc), \
738 NULL, /* NOLINT (readability/null_usage) */ \
739 NODE_STRINGIFY(modname), \
740 priv, \
741 NULL /* NOLINT (readability/null_usage) */ \
742 }; \
743 NODE_C_CTOR(_register_ ## modname) { \
744 node_module_register(&_module); \
745 } \
746 }
747
748 #define NODE_MODULE_CONTEXT_AWARE_X(modname, regfunc, priv, flags) \
749 extern "C" { \
750 static node::node_module _module = \
751 { \
752 NODE_MODULE_VERSION, \
753 flags, \
754 NULL, /* NOLINT (readability/null_usage) */ \
755 __FILE__, \
756 NULL, /* NOLINT (readability/null_usage) */ \
757 (node::addon_context_register_func) (regfunc), \
758 NODE_STRINGIFY(modname), \
759 priv, \
760 NULL /* NOLINT (readability/null_usage) */ \
761 }; \
762 NODE_C_CTOR(_register_ ## modname) { \
763 node_module_register(&_module); \
764 } \
765 }
766
767 // Usage: `NODE_MODULE(NODE_GYP_MODULE_NAME, InitializerFunction)`
768 // If no NODE_MODULE is declared, Node.js looks for the well-known
769 // symbol `node_register_module_v${NODE_MODULE_VERSION}`.
770 #define NODE_MODULE(modname, regfunc) \
771 NODE_MODULE_X(modname, regfunc, NULL, 0) // NOLINT (readability/null_usage)
772
773 #define NODE_MODULE_CONTEXT_AWARE(modname, regfunc) \
774 /* NOLINTNEXTLINE (readability/null_usage) */ \
775 NODE_MODULE_CONTEXT_AWARE_X(modname, regfunc, NULL, 0)
776
777 // Embedders can use this type of binding for statically linked native bindings.
778 // It is used the same way addon bindings are used, except that linked bindings
779 // can be accessed through `process._linkedBinding(modname)`.
780 #define NODE_MODULE_LINKED(modname, regfunc) \
781 /* NOLINTNEXTLINE (readability/null_usage) */ \
782 NODE_MODULE_CONTEXT_AWARE_X(modname, regfunc, NULL, \
783 node::ModuleFlags::kLinked)
784
785 /*
786 * For backward compatibility in add-on modules.
787 */
788 #define NODE_MODULE_DECL /* nothing */
789
790 #define NODE_MODULE_INITIALIZER_BASE node_register_module_v
791
792 #define NODE_MODULE_INITIALIZER_X(base, version) \
793 NODE_MODULE_INITIALIZER_X_HELPER(base, version)
794
795 #define NODE_MODULE_INITIALIZER_X_HELPER(base, version) base##version
796
797 #define NODE_MODULE_INITIALIZER \
798 NODE_MODULE_INITIALIZER_X(NODE_MODULE_INITIALIZER_BASE, \
799 NODE_MODULE_VERSION)
800
801 #define NODE_MODULE_INIT() \
802 extern "C" NODE_MODULE_EXPORT void \
803 NODE_MODULE_INITIALIZER(v8::Local<v8::Object> exports, \
804 v8::Local<v8::Value> module, \
805 v8::Local<v8::Context> context); \
806 NODE_MODULE_CONTEXT_AWARE(NODE_GYP_MODULE_NAME, \
807 NODE_MODULE_INITIALIZER) \
808 void NODE_MODULE_INITIALIZER(v8::Local<v8::Object> exports, \
809 v8::Local<v8::Value> module, \
810 v8::Local<v8::Context> context)
811
812 // Allows embedders to add a binding to the current Environment* that can be
813 // accessed through process._linkedBinding() in the target Environment and all
814 // Worker threads that it creates.
815 // In each variant, the registration function needs to be usable at least for
816 // the time during which the Environment exists.
817 NODE_EXTERN void AddLinkedBinding(Environment* env, const node_module& mod);
818 NODE_EXTERN void AddLinkedBinding(Environment* env,
819 const char* name,
820 addon_context_register_func fn,
821 void* priv);
822
823 /* Called after the event loop exits but before the VM is disposed.
824 * Callbacks are run in reverse order of registration, i.e. newest first.
825 *
826 * You should always use the three-argument variant (or, for addons,
827 * AddEnvironmentCleanupHook) in order to avoid relying on global state.
828 */
829 NODE_DEPRECATED(
830 "Use the three-argument variant of AtExit() or AddEnvironmentCleanupHook()",
831 NODE_EXTERN void AtExit(void (*cb)(void* arg), void* arg = nullptr));
832
833 /* Registers a callback with the passed-in Environment instance. The callback
834 * is called after the event loop exits, but before the VM is disposed.
835 * Callbacks are run in reverse order of registration, i.e. newest first.
836 */
837 NODE_EXTERN void AtExit(Environment* env,
838 void (*cb)(void* arg),
839 void* arg);
840 NODE_DEPRECATED(
841 "Use the three-argument variant of AtExit() or AddEnvironmentCleanupHook()",
842 inline void AtExit(Environment* env,
843 void (*cb)(void* arg)) {
844 AtExit(env, cb, nullptr);
845 })
846
847 typedef double async_id;
848 struct async_context {
849 ::node::async_id async_id;
850 ::node::async_id trigger_async_id;
851 };
852
853 /* This is a lot like node::AtExit, except that the hooks added via this
854 * function are run before the AtExit ones and will always be registered
855 * for the current Environment instance.
856 * These functions are safe to use in an addon supporting multiple
857 * threads/isolates. */
858 NODE_EXTERN void AddEnvironmentCleanupHook(v8::Isolate* isolate,
859 void (*fun)(void* arg),
860 void* arg);
861
862 NODE_EXTERN void RemoveEnvironmentCleanupHook(v8::Isolate* isolate,
863 void (*fun)(void* arg),
864 void* arg);
865
866 /* These are async equivalents of the above. After the cleanup hook is invoked,
867 * `cb(cbarg)` *must* be called, and attempting to remove the cleanup hook will
868 * have no effect. */
869 struct ACHHandle;
870 struct NODE_EXTERN DeleteACHHandle { void operator()(ACHHandle*) const; };
871 typedef std::unique_ptr<ACHHandle, DeleteACHHandle> AsyncCleanupHookHandle;
872
873 NODE_EXTERN AsyncCleanupHookHandle AddEnvironmentCleanupHook(
874 v8::Isolate* isolate,
875 void (*fun)(void* arg, void (*cb)(void*), void* cbarg),
876 void* arg);
877
878 NODE_EXTERN void RemoveEnvironmentCleanupHook(AsyncCleanupHookHandle holder);
879
880 /* Returns the id of the current execution context. If the return value is
881 * zero then no execution has been set. This will happen if the user handles
882 * I/O from native code. */
883 NODE_EXTERN async_id AsyncHooksGetExecutionAsyncId(v8::Isolate* isolate);
884
885 /* Return same value as async_hooks.triggerAsyncId(); */
886 NODE_EXTERN async_id AsyncHooksGetTriggerAsyncId(v8::Isolate* isolate);
887
888 /* If the native API doesn't inherit from the helper class then the callbacks
889 * must be triggered manually. This triggers the init() callback. The return
890 * value is the async id assigned to the resource.
891 *
892 * The `trigger_async_id` parameter should correspond to the resource which is
893 * creating the new resource, which will usually be the return value of
894 * `AsyncHooksGetTriggerAsyncId()`. */
895 NODE_EXTERN async_context EmitAsyncInit(v8::Isolate* isolate,
896 v8::Local<v8::Object> resource,
897 const char* name,
898 async_id trigger_async_id = -1);
899
900 NODE_EXTERN async_context EmitAsyncInit(v8::Isolate* isolate,
901 v8::Local<v8::Object> resource,
902 v8::Local<v8::String> name,
903 async_id trigger_async_id = -1);
904
905 /* Emit the destroy() callback. The overload taking an `Environment*` argument
906 * should be used when the Isolate’s current Context is not associated with
907 * a Node.js Environment, or when there is no current Context, for example
908 * when calling this function during garbage collection. In that case, the
909 * `Environment*` value should have been acquired previously, e.g. through
910 * `GetCurrentEnvironment()`. */
911 NODE_EXTERN void EmitAsyncDestroy(v8::Isolate* isolate,
912 async_context asyncContext);
913 NODE_EXTERN void EmitAsyncDestroy(Environment* env,
914 async_context asyncContext);
915
916 class InternalCallbackScope;
917
918 /* This class works like `MakeCallback()` in that it sets up a specific
919 * asyncContext as the current one and informs the async_hooks and domains
920 * modules that this context is currently active.
921 *
922 * `MakeCallback()` is a wrapper around this class as well as
923 * `Function::Call()`. Either one of these mechanisms needs to be used for
924 * top-level calls into JavaScript (i.e. without any existing JS stack).
925 *
926 * This object should be stack-allocated to ensure that it is contained in a
927 * valid HandleScope.
928 *
929 * Exceptions happening within this scope will be treated like uncaught
930 * exceptions. If this behaviour is undesirable, a new `v8::TryCatch` scope
931 * needs to be created inside of this scope.
932 */
933 class NODE_EXTERN CallbackScope {
934 public:
935 CallbackScope(v8::Isolate* isolate,
936 v8::Local<v8::Object> resource,
937 async_context asyncContext);
938 ~CallbackScope();
939
940 void operator=(const CallbackScope&) = delete;
941 void operator=(CallbackScope&&) = delete;
942 CallbackScope(const CallbackScope&) = delete;
943 CallbackScope(CallbackScope&&) = delete;
944
945 private:
946 InternalCallbackScope* private_;
947 v8::TryCatch try_catch_;
948 };
949
950 /* An API specific to emit before/after callbacks is unnecessary because
951 * MakeCallback will automatically call them for you.
952 *
953 * These methods may create handles on their own, so run them inside a
954 * HandleScope.
955 *
956 * `asyncId` and `triggerAsyncId` should correspond to the values returned by
957 * `EmitAsyncInit()` and `AsyncHooksGetTriggerAsyncId()`, respectively, when the
958 * invoking resource was created. If these values are unknown, 0 can be passed.
959 * */
960 NODE_EXTERN
961 v8::MaybeLocal<v8::Value> MakeCallback(v8::Isolate* isolate,
962 v8::Local<v8::Object> recv,
963 v8::Local<v8::Function> callback,
964 int argc,
965 v8::Local<v8::Value>* argv,
966 async_context asyncContext);
967 NODE_EXTERN
968 v8::MaybeLocal<v8::Value> MakeCallback(v8::Isolate* isolate,
969 v8::Local<v8::Object> recv,
970 const char* method,
971 int argc,
972 v8::Local<v8::Value>* argv,
973 async_context asyncContext);
974 NODE_EXTERN
975 v8::MaybeLocal<v8::Value> MakeCallback(v8::Isolate* isolate,
976 v8::Local<v8::Object> recv,
977 v8::Local<v8::String> symbol,
978 int argc,
979 v8::Local<v8::Value>* argv,
980 async_context asyncContext);
981
982 /* Helper class users can optionally inherit from. If
983 * `AsyncResource::MakeCallback()` is used, then all four callbacks will be
984 * called automatically. */
985 class NODE_EXTERN AsyncResource {
986 public:
987 AsyncResource(v8::Isolate* isolate,
988 v8::Local<v8::Object> resource,
989 const char* name,
990 async_id trigger_async_id = -1);
991
992 virtual ~AsyncResource();
993
994 AsyncResource(const AsyncResource&) = delete;
995 void operator=(const AsyncResource&) = delete;
996
997 v8::MaybeLocal<v8::Value> MakeCallback(
998 v8::Local<v8::Function> callback,
999 int argc,
1000 v8::Local<v8::Value>* argv);
1001
1002 v8::MaybeLocal<v8::Value> MakeCallback(
1003 const char* method,
1004 int argc,
1005 v8::Local<v8::Value>* argv);
1006
1007 v8::MaybeLocal<v8::Value> MakeCallback(
1008 v8::Local<v8::String> symbol,
1009 int argc,
1010 v8::Local<v8::Value>* argv);
1011
1012 v8::Local<v8::Object> get_resource();
1013 async_id get_async_id() const;
1014 async_id get_trigger_async_id() const;
1015
1016 protected:
1017 class NODE_EXTERN CallbackScope : public node::CallbackScope {
1018 public:
1019 explicit CallbackScope(AsyncResource* res);
1020 };
1021
1022 private:
1023 Environment* env_;
1024 v8::Global<v8::Object> resource_;
1025 async_context async_context_;
1026 };
1027
1028 } // namespace node
1029
1030 #endif // SRC_NODE_H_
1031