1// Copyright 2014 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#ifndef V8_LIBPLATFORM_LIBPLATFORM_H_
6#define V8_LIBPLATFORM_LIBPLATFORM_H_
7
8#include <memory>
9
10#include "libplatform/libplatform-export.h"
11#include "libplatform/v8-tracing.h"
12#include "v8-platform.h"  // NOLINT(build/include_directory)
13#include "v8config.h"     // NOLINT(build/include_directory)
14
15namespace v8 {
16namespace platform {
17
18enum class IdleTaskSupport { kDisabled, kEnabled };
19enum class InProcessStackDumping { kDisabled, kEnabled };
20
21enum class MessageLoopBehavior : bool {
22  kDoNotWait = false,
23  kWaitForWork = true
24};
25
26/**
27 * Returns a new instance of the default v8::Platform implementation.
28 *
29 * The caller will take ownership of the returned pointer. |thread_pool_size|
30 * is the number of worker threads to allocate for background jobs. If a value
31 * of zero is passed, a suitable default based on the current number of
32 * processors online will be chosen.
33 * If |idle_task_support| is enabled then the platform will accept idle
34 * tasks (IdleTasksEnabled will return true) and will rely on the embedder
35 * calling v8::platform::RunIdleTasks to process the idle tasks.
36 * If |tracing_controller| is nullptr, the default platform will create a
37 * v8::platform::TracingController instance and use it.
38 */
39V8_PLATFORM_EXPORT std::unique_ptr<v8::Platform> NewDefaultPlatform(
40    int thread_pool_size = 0,
41    IdleTaskSupport idle_task_support = IdleTaskSupport::kDisabled,
42    InProcessStackDumping in_process_stack_dumping =
43        InProcessStackDumping::kDisabled,
44    std::unique_ptr<v8::TracingController> tracing_controller = {});
45
46/**
47 * The same as NewDefaultPlatform but disables the worker thread pool.
48 * It must be used with the --single-threaded V8 flag.
49 */
50V8_PLATFORM_EXPORT std::unique_ptr<v8::Platform>
51NewSingleThreadedDefaultPlatform(
52    IdleTaskSupport idle_task_support = IdleTaskSupport::kDisabled,
53    InProcessStackDumping in_process_stack_dumping =
54        InProcessStackDumping::kDisabled,
55    std::unique_ptr<v8::TracingController> tracing_controller = {});
56
57/**
58 * Returns a new instance of the default v8::JobHandle implementation.
59 *
60 * The job will be executed by spawning up to |num_worker_threads| many worker
61 * threads on the provided |platform| with the given |priority|.
62 */
63V8_PLATFORM_EXPORT std::unique_ptr<v8::JobHandle> NewDefaultJobHandle(
64    v8::Platform* platform, v8::TaskPriority priority,
65    std::unique_ptr<v8::JobTask> job_task, size_t num_worker_threads);
66
67/**
68 * Pumps the message loop for the given isolate.
69 *
70 * The caller has to make sure that this is called from the right thread.
71 * Returns true if a task was executed, and false otherwise. If the call to
72 * PumpMessageLoop is nested within another call to PumpMessageLoop, only
73 * nestable tasks may run. Otherwise, any task may run. Unless requested through
74 * the |behavior| parameter, this call does not block if no task is pending. The
75 * |platform| has to be created using |NewDefaultPlatform|.
76 */
77V8_PLATFORM_EXPORT bool PumpMessageLoop(
78    v8::Platform* platform, v8::Isolate* isolate,
79    MessageLoopBehavior behavior = MessageLoopBehavior::kDoNotWait);
80
81/**
82 * Runs pending idle tasks for at most |idle_time_in_seconds| seconds.
83 *
84 * The caller has to make sure that this is called from the right thread.
85 * This call does not block if no task is pending. The |platform| has to be
86 * created using |NewDefaultPlatform|.
87 */
88V8_PLATFORM_EXPORT void RunIdleTasks(v8::Platform* platform,
89                                     v8::Isolate* isolate,
90                                     double idle_time_in_seconds);
91
92/**
93 * Notifies the given platform about the Isolate getting deleted soon. Has to be
94 * called for all Isolates which are deleted - unless we're shutting down the
95 * platform.
96 *
97 * The |platform| has to be created using |NewDefaultPlatform|.
98 *
99 */
100V8_PLATFORM_EXPORT void NotifyIsolateShutdown(v8::Platform* platform,
101                                              Isolate* isolate);
102
103}  // namespace platform
104}  // namespace v8
105
106#endif  // V8_LIBPLATFORM_LIBPLATFORM_H_
107