node/libplatform/libplatform.h

0001 // Copyright 2014 the V8 project authors. All rights reserved.
0002 // Use of this source code is governed by a BSD-style license that can be
0003 // found in the LICENSE file.
0004
0005 #ifndef V8_LIBPLATFORM_LIBPLATFORM_H_
0006 #define V8_LIBPLATFORM_LIBPLATFORM_H_
0007
0008 #include <memory>
0009
0010 #include "libplatform/libplatform-export.h"
0011 #include "libplatform/v8-tracing.h"
0012 #include "v8-platform.h"  // NOLINT(build/include_directory)
0013 #include "v8config.h"     // NOLINT(build/include_directory)
0014
0015 namespace v8 {
0016 namespace platform {
0017
0018 enum class IdleTaskSupport { kDisabled, kEnabled };
0019 enum class InProcessStackDumping { kDisabled, kEnabled };
0020
0021 enum class MessageLoopBehavior : bool {
0022   kDoNotWait = false,
0023   kWaitForWork = true
0024 };
0025
0026 enum class PriorityMode : bool { kDontApply, kApply };
0027
0028 /**
0029  * Returns a new instance of the default v8::Platform implementation.
0030  *
0031  * The caller will take ownership of the returned pointer. |thread_pool_size|
0032  * is the number of worker threads to allocate for background jobs. If a value
0033  * of zero is passed, a suitable default based on the current number of
0034  * processors online will be chosen.
0035  * If |idle_task_support| is enabled then the platform will accept idle
0036  * tasks (IdleTasksEnabled will return true) and will rely on the embedder
0037  * calling v8::platform::RunIdleTasks to process the idle tasks.
0038  * If |tracing_controller| is nullptr, the default platform will create a
0039  * v8::platform::TracingController instance and use it.
0040  * If |priority_mode| is PriorityMode::kApply, the default platform will use
0041  * multiple task queues executed by threads different system-level priorities
0042  * (where available) to schedule tasks.
0043  */
0044 V8_PLATFORM_EXPORT std::unique_ptr<v8::Platform> NewDefaultPlatform(
0045     int thread_pool_size = 0,
0046     IdleTaskSupport idle_task_support = IdleTaskSupport::kDisabled,
0047     InProcessStackDumping in_process_stack_dumping =
0048         InProcessStackDumping::kDisabled,
0049     std::unique_ptr<v8::TracingController> tracing_controller = {},
0050     PriorityMode priority_mode = PriorityMode::kDontApply);
0051
0052 /**
0053  * The same as NewDefaultPlatform but disables the worker thread pool.
0054  * It must be used with the --single-threaded V8 flag.
0055  */
0056 V8_PLATFORM_EXPORT std::unique_ptr<v8::Platform>
0057 NewSingleThreadedDefaultPlatform(
0058     IdleTaskSupport idle_task_support = IdleTaskSupport::kDisabled,
0059     InProcessStackDumping in_process_stack_dumping =
0060         InProcessStackDumping::kDisabled,
0061     std::unique_ptr<v8::TracingController> tracing_controller = {});
0062
0063 /**
0064  * Returns a new instance of the default v8::JobHandle implementation.
0065  *
0066  * The job will be executed by spawning up to |num_worker_threads| many worker
0067  * threads on the provided |platform| with the given |priority|.
0068  */
0069 V8_PLATFORM_EXPORT std::unique_ptr<v8::JobHandle> NewDefaultJobHandle(
0070     v8::Platform* platform, v8::TaskPriority priority,
0071     std::unique_ptr<v8::JobTask> job_task, size_t num_worker_threads);
0072
0073 /**
0074  * Pumps the message loop for the given isolate.
0075  *
0076  * The caller has to make sure that this is called from the right thread.
0077  * Returns true if a task was executed, and false otherwise. If the call to
0078  * PumpMessageLoop is nested within another call to PumpMessageLoop, only
0079  * nestable tasks may run. Otherwise, any task may run. Unless requested through
0080  * the |behavior| parameter, this call does not block if no task is pending. The
0081  * |platform| has to be created using |NewDefaultPlatform|.
0082  */
0083 V8_PLATFORM_EXPORT bool PumpMessageLoop(
0084     v8::Platform* platform, v8::Isolate* isolate,
0085     MessageLoopBehavior behavior = MessageLoopBehavior::kDoNotWait);
0086
0087 /**
0088  * Runs pending idle tasks for at most |idle_time_in_seconds| seconds.
0089  *
0090  * The caller has to make sure that this is called from the right thread.
0091  * This call does not block if no task is pending. The |platform| has to be
0092  * created using |NewDefaultPlatform|.
0093  */
0094 V8_PLATFORM_EXPORT void RunIdleTasks(v8::Platform* platform,
0095                                      v8::Isolate* isolate,
0096                                      double idle_time_in_seconds);
0097
0098 /**
0099  * Notifies the given platform about the Isolate getting deleted soon. Has to be
0100  * called for all Isolates which are deleted - unless we're shutting down the
0101  * platform.
0102  *
0103  * The |platform| has to be created using |NewDefaultPlatform|.
0104  *
0105  */
0106 V8_PLATFORM_EXPORT void NotifyIsolateShutdown(v8::Platform* platform,
0107                                               Isolate* isolate);
0108
0109 }  // namespace platform
0110 }  // namespace v8
0111
0112 #endif  // V8_LIBPLATFORM_LIBPLATFORM_H_