File Explorer

1// Copyright 2013 the V8 project authors. All rights reserved.2// Use of this source code is governed by a BSD-style license that can be3// found in the LICENSE file.4 5#ifndef V8_V8_PLATFORM_H_6#define V8_V8_PLATFORM_H_7 8#include <math.h>9#include <stddef.h>10#include <stdint.h>11#include <stdlib.h>  // For abort.12 13#include <memory>14#include <string>15 16#include "v8-source-location.h"  // NOLINT(build/include_directory)17#include "v8config.h"            // NOLINT(build/include_directory)18 19namespace v8 {20 21class Isolate;22 23// Valid priorities supported by the task scheduling infrastructure.24enum class TaskPriority : uint8_t {25  /**26   * Best effort tasks are not critical for performance of the application. The27   * platform implementation should preempt such tasks if higher priority tasks28   * arrive.29   */30  kBestEffort,31  /**32   * User visible tasks are long running background tasks that will33   * improve performance and memory usage of the application upon completion.34   * Example: background compilation and garbage collection.35   */36  kUserVisible,37  /**38   * User blocking tasks are highest priority tasks that block the execution39   * thread (e.g. major garbage collection). They must be finished as soon as40   * possible.41   */42  kUserBlocking,43  kMaxPriority = kUserBlocking44};45 46/**47 * A Task represents a unit of work.48 */49class Task {50 public:51  virtual ~Task() = default;52 53  virtual void Run() = 0;54};55 56/**57 * An IdleTask represents a unit of work to be performed in idle time.58 * The Run method is invoked with an argument that specifies the deadline in59 * seconds returned by MonotonicallyIncreasingTime().60 * The idle task is expected to complete by this deadline.61 */62class IdleTask {63 public:64  virtual ~IdleTask() = default;65  virtual void Run(double deadline_in_seconds) = 0;66};67 68/**69 * A TaskRunner allows scheduling of tasks. The TaskRunner may still be used to70 * post tasks after the isolate gets destructed, but these tasks may not get71 * executed anymore. All tasks posted to a given TaskRunner will be invoked in72 * sequence. Tasks can be posted from any thread.73 */74class TaskRunner {75 public:76  /**77   * Schedules a task to be invoked by this TaskRunner. The TaskRunner78   * implementation takes ownership of |task|.79   *80   * Embedders should override PostTaskImpl instead of this.81   */82  void PostTask(std::unique_ptr<Task> task,83                const SourceLocation& location = SourceLocation::Current()) {84    PostTaskImpl(std::move(task), location);85  }86 87  /**88   * Schedules a task to be invoked by this TaskRunner. The TaskRunner89   * implementation takes ownership of |task|. The |task| cannot be nested90   * within other task executions.91   *92   * Tasks which shouldn't be interleaved with JS execution must be posted with93   * |PostNonNestableTask| or |PostNonNestableDelayedTask|. This is because the94   * embedder may process tasks in a callback which is called during JS95   * execution.96   *97   * In particular, tasks which execute JS must be non-nestable, since JS98   * execution is not allowed to nest.99   *100   * Requires that |TaskRunner::NonNestableTasksEnabled()| is true.101   *102   * Embedders should override PostNonNestableTaskImpl instead of this.103   */104  void PostNonNestableTask(105      std::unique_ptr<Task> task,106      const SourceLocation& location = SourceLocation::Current()) {107    PostNonNestableTaskImpl(std::move(task), location);108  }109 110  /**111   * Schedules a task to be invoked by this TaskRunner. The task is scheduled112   * after the given number of seconds |delay_in_seconds|. The TaskRunner113   * implementation takes ownership of |task|.114   *115   * Embedders should override PostDelayedTaskImpl instead of this.116   */117  void PostDelayedTask(118      std::unique_ptr<Task> task, double delay_in_seconds,119      const SourceLocation& location = SourceLocation::Current()) {120    PostDelayedTaskImpl(std::move(task), delay_in_seconds, location);121  }122 123  /**124   * Schedules a task to be invoked by this TaskRunner. The task is scheduled125   * after the given number of seconds |delay_in_seconds|. The TaskRunner126   * implementation takes ownership of |task|. The |task| cannot be nested127   * within other task executions.128   *129   * Tasks which shouldn't be interleaved with JS execution must be posted with130   * |PostNonNestableTask| or |PostNonNestableDelayedTask|. This is because the131   * embedder may process tasks in a callback which is called during JS132   * execution.133   *134   * In particular, tasks which execute JS must be non-nestable, since JS135   * execution is not allowed to nest.136   *137   * Requires that |TaskRunner::NonNestableDelayedTasksEnabled()| is true.138   *139   * Embedders should override PostNonNestableDelayedTaskImpl instead of this.140   */141  void PostNonNestableDelayedTask(142      std::unique_ptr<Task> task, double delay_in_seconds,143      const SourceLocation& location = SourceLocation::Current()) {144    PostNonNestableDelayedTaskImpl(std::move(task), delay_in_seconds, location);145  }146 147  /**148   * Schedules an idle task to be invoked by this TaskRunner. The task is149   * scheduled when the embedder is idle. Requires that150   * |TaskRunner::IdleTasksEnabled()| is true. Idle tasks may be reordered151   * relative to other task types and may be starved for an arbitrarily long152   * time if no idle time is available. The TaskRunner implementation takes153   * ownership of |task|.154   *155   * Embedders should override PostIdleTaskImpl instead of this.156   */157  void PostIdleTask(158      std::unique_ptr<IdleTask> task,159      const SourceLocation& location = SourceLocation::Current()) {160    PostIdleTaskImpl(std::move(task), location);161  }162 163  /**164   * Returns true if idle tasks are enabled for this TaskRunner.165   */166  virtual bool IdleTasksEnabled() = 0;167 168  /**169   * Returns true if non-nestable tasks are enabled for this TaskRunner.170   */171  virtual bool NonNestableTasksEnabled() const { return false; }172 173  /**174   * Returns true if non-nestable delayed tasks are enabled for this TaskRunner.175   */176  virtual bool NonNestableDelayedTasksEnabled() const { return false; }177 178  TaskRunner() = default;179  virtual ~TaskRunner() = default;180 181  TaskRunner(const TaskRunner&) = delete;182  TaskRunner& operator=(const TaskRunner&) = delete;183 184 protected:185  /**186   * Implementation of above methods with an additional `location` argument.187   */188  virtual void PostTaskImpl(std::unique_ptr<Task> task,189                            const SourceLocation& location) {}190  virtual void PostNonNestableTaskImpl(std::unique_ptr<Task> task,191                                       const SourceLocation& location) {}192  virtual void PostDelayedTaskImpl(std::unique_ptr<Task> task,193                                   double delay_in_seconds,194                                   const SourceLocation& location) {}195  virtual void PostNonNestableDelayedTaskImpl(std::unique_ptr<Task> task,196                                              double delay_in_seconds,197                                              const SourceLocation& location) {}198  virtual void PostIdleTaskImpl(std::unique_ptr<IdleTask> task,199                                const SourceLocation& location) {}200};201 202/**203 * Delegate that's passed to Job's worker task, providing an entry point to204 * communicate with the scheduler.205 */206class JobDelegate {207 public:208  /**209   * Returns true if this thread *must* return from the worker task on the210   * current thread ASAP. Workers should periodically invoke ShouldYield (or211   * YieldIfNeeded()) as often as is reasonable.212   * After this method returned true, ShouldYield must not be called again.213   */214  virtual bool ShouldYield() = 0;215 216  /**217   * Notifies the scheduler that max concurrency was increased, and the number218   * of worker should be adjusted accordingly. See Platform::PostJob() for more219   * details.220   */221  virtual void NotifyConcurrencyIncrease() = 0;222 223  /**224   * Returns a task_id unique among threads currently running this job, such225   * that GetTaskId() < worker count. To achieve this, the same task_id may be226   * reused by a different thread after a worker_task returns.227   */228  virtual uint8_t GetTaskId() = 0;229 230  /**231   * Returns true if the current task is called from the thread currently232   * running JobHandle::Join().233   */234  virtual bool IsJoiningThread() const = 0;235};236 237/**238 * Handle returned when posting a Job. Provides methods to control execution of239 * the posted Job.240 */241class JobHandle {242 public:243  virtual ~JobHandle() = default;244 245  /**246   * Notifies the scheduler that max concurrency was increased, and the number247   * of worker should be adjusted accordingly. See Platform::PostJob() for more248   * details.249   */250  virtual void NotifyConcurrencyIncrease() = 0;251 252  /**253   * Contributes to the job on this thread. Doesn't return until all tasks have254   * completed and max concurrency becomes 0. When Join() is called and max255   * concurrency reaches 0, it should not increase again. This also promotes256   * this Job's priority to be at least as high as the calling thread's257   * priority.258   */259  virtual void Join() = 0;260 261  /**262   * Forces all existing workers to yield ASAP. Waits until they have all263   * returned from the Job's callback before returning.264   */265  virtual void Cancel() = 0;266 267  /*268   * Forces all existing workers to yield ASAP but doesn’t wait for them.269   * Warning, this is dangerous if the Job's callback is bound to or has access270   * to state which may be deleted after this call.271   */272  virtual void CancelAndDetach() = 0;273 274  /**275   * Returns true if there's any work pending or any worker running.276   */277  virtual bool IsActive() = 0;278 279  /**280   * Returns true if associated with a Job and other methods may be called.281   * Returns false after Join() or Cancel() was called. This may return true282   * even if no workers are running and IsCompleted() returns true283   */284  virtual bool IsValid() = 0;285 286  /**287   * Returns true if job priority can be changed.288   */289  virtual bool UpdatePriorityEnabled() const { return false; }290 291  /**292   *  Update this Job's priority.293   */294  virtual void UpdatePriority(TaskPriority new_priority) {}295};296 297/**298 * A JobTask represents work to run in parallel from Platform::PostJob().299 */300class JobTask {301 public:302  virtual ~JobTask() = default;303 304  virtual void Run(JobDelegate* delegate) = 0;305 306  /**307   * Controls the maximum number of threads calling Run() concurrently, given308   * the number of threads currently assigned to this job and executing Run().309   * Run() is only invoked if the number of threads previously running Run() was310   * less than the value returned. In general, this should return the latest311   * number of incomplete work items (smallest unit of work) left to process,312   * including items that are currently in progress. |worker_count| is the313   * number of threads currently assigned to this job which some callers may314   * need to determine their return value. Since GetMaxConcurrency() is a leaf315   * function, it must not call back any JobHandle methods.316   */317  virtual size_t GetMaxConcurrency(size_t worker_count) const = 0;318};319 320/**321 * A "blocking call" refers to any call that causes the calling thread to wait322 * off-CPU. It includes but is not limited to calls that wait on synchronous323 * file I/O operations: read or write a file from disk, interact with a pipe or324 * a socket, rename or delete a file, enumerate files in a directory, etc.325 * Acquiring a low contention lock is not considered a blocking call.326 */327 328/**329 * BlockingType indicates the likelihood that a blocking call will actually330 * block.331 */332enum class BlockingType {333  // The call might block (e.g. file I/O that might hit in memory cache).334  kMayBlock,335  // The call will definitely block (e.g. cache already checked and now pinging336  // server synchronously).337  kWillBlock338};339 340/**341 * This class is instantiated with CreateBlockingScope() in every scope where a342 * blocking call is made and serves as a precise annotation of the scope that343 * may/will block. May be implemented by an embedder to adjust the thread count.344 * CPU usage should be minimal within that scope. ScopedBlockingCalls can be345 * nested.346 */347class ScopedBlockingCall {348 public:349  virtual ~ScopedBlockingCall() = default;350};351 352/**353 * The interface represents complex arguments to trace events.354 */355class ConvertableToTraceFormat {356 public:357  virtual ~ConvertableToTraceFormat() = default;358 359  /**360   * Append the class info to the provided |out| string. The appended361   * data must be a valid JSON object. Strings must be properly quoted, and362   * escaped. There is no processing applied to the content after it is363   * appended.364   */365  virtual void AppendAsTraceFormat(std::string* out) const = 0;366};367 368/**369 * V8 Tracing controller.370 *371 * Can be implemented by an embedder to record trace events from V8.372 *373 * Will become obsolete in Perfetto SDK build (v8_use_perfetto = true).374 */375class TracingController {376 public:377  virtual ~TracingController() = default;378 379  // In Perfetto mode, trace events are written using Perfetto's Track Event380  // API directly without going through the embedder. However, it is still381  // possible to observe tracing being enabled and disabled.382#if !defined(V8_USE_PERFETTO)383  /**384   * Called by TRACE_EVENT* macros, don't call this directly.385   * The name parameter is a category group for example:386   * TRACE_EVENT0("v8,parse", "V8.Parse")387   * The pointer returned points to a value with zero or more of the bits388   * defined in CategoryGroupEnabledFlags.389   **/390  virtual const uint8_t* GetCategoryGroupEnabled(const char* name) {391    static uint8_t no = 0;392    return &no;393  }394 395  /**396   * Adds a trace event to the platform tracing system. These function calls are397   * usually the result of a TRACE_* macro from trace-event-no-perfetto.h when398   * tracing and the category of the particular trace are enabled. It is not399   * advisable to call these functions on their own; they are really only meant400   * to be used by the trace macros. The returned handle can be used by401   * UpdateTraceEventDuration to update the duration of COMPLETE events.402   */403  virtual uint64_t AddTraceEvent(404      char phase, const uint8_t* category_enabled_flag, const char* name,405      const char* scope, uint64_t id, uint64_t bind_id, int32_t num_args,406      const char** arg_names, const uint8_t* arg_types,407      const uint64_t* arg_values,408      std::unique_ptr<ConvertableToTraceFormat>* arg_convertables,409      unsigned int flags) {410    return 0;411  }412  virtual uint64_t AddTraceEventWithTimestamp(413      char phase, const uint8_t* category_enabled_flag, const char* name,414      const char* scope, uint64_t id, uint64_t bind_id, int32_t num_args,415      const char** arg_names, const uint8_t* arg_types,416      const uint64_t* arg_values,417      std::unique_ptr<ConvertableToTraceFormat>* arg_convertables,418      unsigned int flags, int64_t timestamp) {419    return 0;420  }421 422  /**423   * Sets the duration field of a COMPLETE trace event. It must be called with424   * the handle returned from AddTraceEvent().425   **/426  virtual void UpdateTraceEventDuration(const uint8_t* category_enabled_flag,427                                        const char* name, uint64_t handle) {}428#endif  // !defined(V8_USE_PERFETTO)429 430  class TraceStateObserver {431   public:432    virtual ~TraceStateObserver() = default;433    virtual void OnTraceEnabled() = 0;434    virtual void OnTraceDisabled() = 0;435  };436 437  /**438   * Adds tracing state change observer.439   * Does nothing in Perfetto SDK build (v8_use_perfetto = true).440   */441  virtual void AddTraceStateObserver(TraceStateObserver*) {}442 443  /**444   * Removes tracing state change observer.445   * Does nothing in Perfetto SDK build (v8_use_perfetto = true).446   */447  virtual void RemoveTraceStateObserver(TraceStateObserver*) {}448};449 450/**451 * A V8 memory page allocator.452 *453 * Can be implemented by an embedder to manage large host OS allocations.454 */455class PageAllocator {456 public:457  virtual ~PageAllocator() = default;458 459  /**460   * Gets the page granularity for AllocatePages and FreePages. Addresses and461   * lengths for those calls should be multiples of AllocatePageSize().462   */463  virtual size_t AllocatePageSize() = 0;464 465  /**466   * Gets the page granularity for SetPermissions and ReleasePages. Addresses467   * and lengths for those calls should be multiples of CommitPageSize().468   */469  virtual size_t CommitPageSize() = 0;470 471  /**472   * Sets the random seed so that GetRandomMmapAddr() will generate repeatable473   * sequences of random mmap addresses.474   */475  virtual void SetRandomMmapSeed(int64_t seed) = 0;476 477  /**478   * Returns a randomized address, suitable for memory allocation under ASLR.479   * The address will be aligned to AllocatePageSize.480   */481  virtual void* GetRandomMmapAddr() = 0;482 483  /**484   * Memory permissions.485   */486  enum Permission {487    kNoAccess,488    kRead,489    kReadWrite,490    kReadWriteExecute,491    kReadExecute,492    // Set this when reserving memory that will later require kReadWriteExecute493    // permissions. The resulting behavior is platform-specific, currently494    // this is used to set the MAP_JIT flag on Apple Silicon.495    // TODO(jkummerow): Remove this when Wasm has a platform-independent496    // w^x implementation.497    // TODO(saelo): Remove this once all JIT pages are allocated through the498    // VirtualAddressSpace API.499    kNoAccessWillJitLater500  };501 502  /**503   * Allocates memory in range with the given alignment and permission.504   */505  virtual void* AllocatePages(void* address, size_t length, size_t alignment,506                              Permission permissions) = 0;507 508  /**509   * Frees memory in a range that was allocated by a call to AllocatePages.510   */511  virtual bool FreePages(void* address, size_t length) = 0;512 513  /**514   * Releases memory in a range that was allocated by a call to AllocatePages.515   */516  virtual bool ReleasePages(void* address, size_t length,517                            size_t new_length) = 0;518 519  /**520   * Sets permissions on pages in an allocated range.521   */522  virtual bool SetPermissions(void* address, size_t length,523                              Permission permissions) = 0;524 525  /**526   * Recommits discarded pages in the given range with given permissions.527   * Discarded pages must be recommitted with their original permissions528   * before they are used again.529   */530  virtual bool RecommitPages(void* address, size_t length,531                             Permission permissions) {532    // TODO(v8:12797): make it pure once it's implemented on Chromium side.533    return false;534  }535 536  /**537   * Frees memory in the given [address, address + size) range. address and size538   * should be operating system page-aligned. The next write to this539   * memory area brings the memory transparently back. This should be treated as540   * a hint to the OS that the pages are no longer needed. It does not guarantee541   * that the pages will be discarded immediately or at all.542   */543  virtual bool DiscardSystemPages(void* address, size_t size) { return true; }544 545  /**546   * Decommits any wired memory pages in the given range, allowing the OS to547   * reclaim them, and marks the region as inacessible (kNoAccess). The address548   * range stays reserved and can be accessed again later by changing its549   * permissions. However, in that case the memory content is guaranteed to be550   * zero-initialized again. The memory must have been previously allocated by a551   * call to AllocatePages. Returns true on success, false otherwise.552   */553  virtual bool DecommitPages(void* address, size_t size) = 0;554 555  /**556   * Block any modifications to the given mapping such as changing permissions557   * or unmapping the pages on supported platforms.558   * The address space reservation will exist until the process ends, but it's559   * possible to release the memory using DiscardSystemPages. Note that this560   * might require write permissions to the page as e.g. on Linux, mseal will561   * block discarding sealed anonymous memory.562   */563  virtual bool SealPages(void* address, size_t length) {564    // TODO(360048056): make it pure once it's implemented on Chromium side.565    return false;566  }567 568  /**569   * INTERNAL ONLY: This interface has not been stabilised and may change570   * without notice from one release to another without being deprecated first.571   */572  class SharedMemoryMapping {573   public:574    // Implementations are expected to free the shared memory mapping in the575    // destructor.576    virtual ~SharedMemoryMapping() = default;577    virtual void* GetMemory() const = 0;578  };579 580  /**581   * INTERNAL ONLY: This interface has not been stabilised and may change582   * without notice from one release to another without being deprecated first.583   */584  class SharedMemory {585   public:586    // Implementations are expected to free the shared memory in the destructor.587    virtual ~SharedMemory() = default;588    virtual std::unique_ptr<SharedMemoryMapping> RemapTo(589        void* new_address) const = 0;590    virtual void* GetMemory() const = 0;591    virtual size_t GetSize() const = 0;592  };593 594  /**595   * INTERNAL ONLY: This interface has not been stabilised and may change596   * without notice from one release to another without being deprecated first.597   *598   * Reserve pages at a fixed address returning whether the reservation is599   * possible. The reserved memory is detached from the PageAllocator and so600   * should not be freed by it. It's intended for use with601   * SharedMemory::RemapTo, where ~SharedMemoryMapping would free the memory.602   */603  virtual bool ReserveForSharedMemoryMapping(void* address, size_t size) {604    return false;605  }606 607  /**608   * INTERNAL ONLY: This interface has not been stabilised and may change609   * without notice from one release to another without being deprecated first.610   *611   * Allocates shared memory pages. Not all PageAllocators need support this and612   * so this method need not be overridden.613   * Allocates a new read-only shared memory region of size |length| and copies614   * the memory at |original_address| into it.615   */616  virtual std::unique_ptr<SharedMemory> AllocateSharedPages(617      size_t length, const void* original_address) {618    return {};619  }620 621  /**622   * INTERNAL ONLY: This interface has not been stabilised and may change623   * without notice from one release to another without being deprecated first.624   *625   * If not overridden and changed to return true, V8 will not attempt to call626   * AllocateSharedPages or RemapSharedPages. If overridden, AllocateSharedPages627   * and RemapSharedPages must also be overridden.628   */629  virtual bool CanAllocateSharedPages() { return false; }630};631 632/**633 * An allocator that uses per-thread permissions to protect the memory.634 *635 * The implementation is platform/hardware specific, e.g. using pkeys on x64.636 *637 * INTERNAL ONLY: This interface has not been stabilised and may change638 * without notice from one release to another without being deprecated first.639 */640class ThreadIsolatedAllocator {641 public:642  virtual ~ThreadIsolatedAllocator() = default;643 644  virtual void* Allocate(size_t size) = 0;645 646  virtual void Free(void* object) = 0;647 648  enum class Type {649    kPkey,650  };651 652  virtual Type Type() const = 0;653 654  /**655   * Return the pkey used to implement the thread isolation if Type == kPkey.656   */657  virtual int Pkey() const { return -1; }658 659  /**660   * Per-thread permissions can be reset on signal handler entry. Even reading661   * ThreadIsolated memory will segfault in that case.662   * Call this function on signal handler entry to ensure that read permissions663   * are restored.664   */665  static void SetDefaultPermissionsForSignalHandler();666};667 668// Opaque type representing a handle to a shared memory region.669using PlatformSharedMemoryHandle = intptr_t;670static constexpr PlatformSharedMemoryHandle kInvalidSharedMemoryHandle = -1;671 672// Conversion routines from the platform-dependent shared memory identifiers673// into the opaque PlatformSharedMemoryHandle type. These use the underlying674// types (e.g. unsigned int) instead of the typedef'd ones (e.g. mach_port_t)675// to avoid pulling in large OS header files into this header file. Instead,676// the users of these routines are expected to include the respecitve OS677// headers in addition to this one.678#if V8_OS_DARWIN679// Convert between a shared memory handle and a mach_port_t referencing a memory680// entry object.681inline PlatformSharedMemoryHandle SharedMemoryHandleFromMachMemoryEntry(682    unsigned int port) {683  return static_cast<PlatformSharedMemoryHandle>(port);684}685inline unsigned int MachMemoryEntryFromSharedMemoryHandle(686    PlatformSharedMemoryHandle handle) {687  return static_cast<unsigned int>(handle);688}689#elif V8_OS_FUCHSIA690// Convert between a shared memory handle and a zx_handle_t to a VMO.691inline PlatformSharedMemoryHandle SharedMemoryHandleFromVMO(uint32_t handle) {692  return static_cast<PlatformSharedMemoryHandle>(handle);693}694inline uint32_t VMOFromSharedMemoryHandle(PlatformSharedMemoryHandle handle) {695  return static_cast<uint32_t>(handle);696}697#elif V8_OS_WIN698// Convert between a shared memory handle and a Windows HANDLE to a file mapping699// object.700inline PlatformSharedMemoryHandle SharedMemoryHandleFromFileMapping(701    void* handle) {702  return reinterpret_cast<PlatformSharedMemoryHandle>(handle);703}704inline void* FileMappingFromSharedMemoryHandle(705    PlatformSharedMemoryHandle handle) {706  return reinterpret_cast<void*>(handle);707}708#else709// Convert between a shared memory handle and a file descriptor.710inline PlatformSharedMemoryHandle SharedMemoryHandleFromFileDescriptor(int fd) {711  return static_cast<PlatformSharedMemoryHandle>(fd);712}713inline int FileDescriptorFromSharedMemoryHandle(714    PlatformSharedMemoryHandle handle) {715  return static_cast<int>(handle);716}717#endif718 719/**720 * Possible permissions for memory pages.721 */722enum class PagePermissions {723  kNoAccess,724  kRead,725  kReadWrite,726  kReadWriteExecute,727  kReadExecute,728};729 730/**731 * Class to manage a virtual memory address space.732 *733 * This class represents a contiguous region of virtual address space in which734 * sub-spaces and (private or shared) memory pages can be allocated, freed, and735 * modified. This interface is meant to eventually replace the PageAllocator736 * interface, and can be used as an alternative in the meantime.737 *738 * This API is not yet stable and may change without notice!739 */740class VirtualAddressSpace {741 public:742  using Address = uintptr_t;743 744  VirtualAddressSpace(size_t page_size, size_t allocation_granularity,745                      Address base, size_t size,746                      PagePermissions max_page_permissions)747      : page_size_(page_size),748        allocation_granularity_(allocation_granularity),749        base_(base),750        size_(size),751        max_page_permissions_(max_page_permissions) {}752 753  virtual ~VirtualAddressSpace() = default;754 755  /**756   * The page size used inside this space. Guaranteed to be a power of two.757   * Used as granularity for all page-related operations except for allocation,758   * which use the allocation_granularity(), see below.759   *760   * \returns the page size in bytes.761   */762  size_t page_size() const { return page_size_; }763 764  /**765   * The granularity of page allocations and, by extension, of subspace766   * allocations. This is guaranteed to be a power of two and a multiple of the767   * page_size(). In practice, this is equal to the page size on most OSes, but768   * on Windows it is usually 64KB, while the page size is 4KB.769   *770   * \returns the allocation granularity in bytes.771   */772  size_t allocation_granularity() const { return allocation_granularity_; }773 774  /**775   * The base address of the address space managed by this instance.776   *777   * \returns the base address of this address space.778   */779  Address base() const { return base_; }780 781  /**782   * The size of the address space managed by this instance.783   *784   * \returns the size of this address space in bytes.785   */786  size_t size() const { return size_; }787 788  /**789   * The maximum page permissions that pages allocated inside this space can790   * obtain.791   *792   * \returns the maximum page permissions.793   */794  PagePermissions max_page_permissions() const { return max_page_permissions_; }795 796  /**797   * Whether the |address| is inside the address space managed by this instance.798   *799   * \returns true if it is inside the address space, false if not.800   */801  bool Contains(Address address) const {802    return (address >= base()) && (address < base() + size());803  }804 805  /**806   * Sets the random seed so that GetRandomPageAddress() will generate807   * repeatable sequences of random addresses.808   *809   * \param The seed for the PRNG.810   */811  virtual void SetRandomSeed(int64_t seed) = 0;812 813  /**814   * Returns a random address inside this address space, suitable for page815   * allocations hints.816   *817   * \returns a random address aligned to allocation_granularity().818   */819  virtual Address RandomPageAddress() = 0;820 821  /**822   * Allocates private memory pages with the given alignment and permissions.823   *824   * \param hint If nonzero, the allocation is attempted to be placed at the825   * given address first. If that fails, the allocation is attempted to be826   * placed elsewhere, possibly nearby, but that is not guaranteed. Specifying827   * zero for the hint always causes this function to choose a random address.828   * The hint, if specified, must be aligned to the specified alignment.829   *830   * \param size The size of the allocation in bytes. Must be a multiple of the831   * allocation_granularity().832   *833   * \param alignment The alignment of the allocation in bytes. Must be a834   * multiple of the allocation_granularity() and should be a power of two.835   *836   * \param permissions The page permissions of the newly allocated pages.837   *838   * \returns the start address of the allocated pages on success, zero on839   * failure.840   */841  static constexpr Address kNoHint = 0;842  virtual V8_WARN_UNUSED_RESULT Address843  AllocatePages(Address hint, size_t size, size_t alignment,844                PagePermissions permissions) = 0;845 846  /**847   * Frees previously allocated pages.848   *849   * This function will terminate the process on failure as this implies a bug850   * in the client. As such, there is no return value.851   *852   * \param address The start address of the pages to free. This address must853   * have been obtained through a call to AllocatePages.854   *855   * \param size The size in bytes of the region to free. This must match the856   * size passed to AllocatePages when the pages were allocated.857   */858  virtual void FreePages(Address address, size_t size) = 0;859 860  /**861   * Sets permissions of all allocated pages in the given range.862   *863   * This operation can fail due to OOM, in which case false is returned. If864   * the operation fails for a reason other than OOM, this function will865   * terminate the process as this implies a bug in the client.866   *867   * \param address The start address of the range. Must be aligned to868   * page_size().869   *870   * \param size The size in bytes of the range. Must be a multiple871   * of page_size().872   *873   * \param permissions The new permissions for the range.874   *875   * \returns true on success, false on OOM.876   */877  virtual V8_WARN_UNUSED_RESULT bool SetPagePermissions(878      Address address, size_t size, PagePermissions permissions) = 0;879 880  /**881   * Creates a guard region at the specified address.882   *883   * Guard regions are guaranteed to cause a fault when accessed and generally884   * do not count towards any memory consumption limits. Further, allocating885   * guard regions can usually not fail in subspaces if the region does not886   * overlap with another region, subspace, or page allocation.887   *888   * \param address The start address of the guard region. Must be aligned to889   * the allocation_granularity().890   *891   * \param size The size of the guard region in bytes. Must be a multiple of892   * the allocation_granularity().893   *894   * \returns true on success, false otherwise.895   */896  virtual V8_WARN_UNUSED_RESULT bool AllocateGuardRegion(Address address,897                                                         size_t size) = 0;898 899  /**900   * Frees an existing guard region.901   *902   * This function will terminate the process on failure as this implies a bug903   * in the client. As such, there is no return value.904   *905   * \param address The start address of the guard region to free. This address906   * must have previously been used as address parameter in a successful907   * invocation of AllocateGuardRegion.908   *909   * \param size The size in bytes of the guard region to free. This must match910   * the size passed to AllocateGuardRegion when the region was created.911   */912  virtual void FreeGuardRegion(Address address, size_t size) = 0;913 914  /**915   * Allocates shared memory pages with the given permissions.916   *917   * \param hint Placement hint. See AllocatePages.918   *919   * \param size The size of the allocation in bytes. Must be a multiple of the920   * allocation_granularity().921   *922   * \param permissions The page permissions of the newly allocated pages.923   *924   * \param handle A platform-specific handle to a shared memory object. See925   * the SharedMemoryHandleFromX routines above for ways to obtain these.926   *927   * \param offset The offset in the shared memory object at which the mapping928   * should start. Must be a multiple of the allocation_granularity().929   *930   * \returns the start address of the allocated pages on success, zero on931   * failure.932   */933  virtual V8_WARN_UNUSED_RESULT Address934  AllocateSharedPages(Address hint, size_t size, PagePermissions permissions,935                      PlatformSharedMemoryHandle handle, uint64_t offset) = 0;936 937  /**938   * Frees previously allocated shared pages.939   *940   * This function will terminate the process on failure as this implies a bug941   * in the client. As such, there is no return value.942   *943   * \param address The start address of the pages to free. This address must944   * have been obtained through a call to AllocateSharedPages.945   *946   * \param size The size in bytes of the region to free. This must match the947   * size passed to AllocateSharedPages when the pages were allocated.948   */949  virtual void FreeSharedPages(Address address, size_t size) = 0;950 951  /**952   * Whether this instance can allocate subspaces or not.953   *954   * \returns true if subspaces can be allocated, false if not.955   */956  virtual bool CanAllocateSubspaces() = 0;957 958  /*959   * Allocate a subspace.960   *961   * The address space of a subspace stays reserved in the parent space for the962   * lifetime of the subspace. As such, it is guaranteed that page allocations963   * on the parent space cannot end up inside a subspace.964   *965   * \param hint Hints where the subspace should be allocated. See966   * AllocatePages() for more details.967   *968   * \param size The size in bytes of the subspace. Must be a multiple of the969   * allocation_granularity().970   *971   * \param alignment The alignment of the subspace in bytes. Must be a multiple972   * of the allocation_granularity() and should be a power of two.973   *974   * \param max_page_permissions The maximum permissions that pages allocated in975   * the subspace can obtain.976   *977   * \returns a new subspace or nullptr on failure.978   */979  virtual std::unique_ptr<VirtualAddressSpace> AllocateSubspace(980      Address hint, size_t size, size_t alignment,981      PagePermissions max_page_permissions) = 0;982 983  //984  // TODO(v8) maybe refactor the methods below before stabilizing the API. For985  // example by combining them into some form of page operation method that986  // takes a command enum as parameter.987  //988 989  /**990   * Recommits discarded pages in the given range with given permissions.991   * Discarded pages must be recommitted with their original permissions992   * before they are used again.993   *994   * \param address The start address of the range. Must be aligned to995   * page_size().996   *997   * \param size The size in bytes of the range. Must be a multiple998   * of page_size().999   *1000   * \param permissions The permissions for the range that the pages must have.1001   *1002   * \returns true on success, false otherwise.1003   */1004  virtual V8_WARN_UNUSED_RESULT bool RecommitPages(1005      Address address, size_t size, PagePermissions permissions) = 0;1006 1007  /**1008   * Frees memory in the given [address, address + size) range. address and1009   * size should be aligned to the page_size(). The next write to this memory1010   * area brings the memory transparently back. This should be treated as a1011   * hint to the OS that the pages are no longer needed. It does not guarantee1012   * that the pages will be discarded immediately or at all.1013   *1014   * \returns true on success, false otherwise. Since this method is only a1015   * hint, a successful invocation does not imply that pages have been removed.1016   */1017  virtual V8_WARN_UNUSED_RESULT bool DiscardSystemPages(Address address,1018                                                        size_t size) {1019    return true;1020  }1021  /**1022   * Decommits any wired memory pages in the given range, allowing the OS to1023   * reclaim them, and marks the region as inacessible (kNoAccess). The address1024   * range stays reserved and can be accessed again later by changing its1025   * permissions. However, in that case the memory content is guaranteed to be1026   * zero-initialized again. The memory must have been previously allocated by a1027   * call to AllocatePages.1028   *1029   * \returns true on success, false otherwise.1030   */1031  virtual V8_WARN_UNUSED_RESULT bool DecommitPages(Address address,1032                                                   size_t size) = 0;1033 1034 private:1035  const size_t page_size_;1036  const size_t allocation_granularity_;1037  const Address base_;1038  const size_t size_;1039  const PagePermissions max_page_permissions_;1040};1041 1042/**1043 * Observer used by V8 to notify the embedder about entering/leaving sections1044 * with high throughput of malloc/free operations.1045 */1046class HighAllocationThroughputObserver {1047 public:1048  virtual void EnterSection() {}1049  virtual void LeaveSection() {}1050};1051 1052/**1053 * V8 Platform abstraction layer.1054 *1055 * The embedder has to provide an implementation of this interface before1056 * initializing the rest of V8.1057 */1058class Platform {1059 public:1060  virtual ~Platform() = default;1061 1062  /**1063   * Allows the embedder to manage memory page allocations.1064   * Returning nullptr will cause V8 to use the default page allocator.1065   */1066  virtual PageAllocator* GetPageAllocator() { return nullptr; }1067 1068  /**1069   * Allows the embedder to provide an allocator that uses per-thread memory1070   * permissions to protect allocations.1071   * Returning nullptr will cause V8 to disable protections that rely on this1072   * feature.1073   */1074  virtual ThreadIsolatedAllocator* GetThreadIsolatedAllocator() {1075    return nullptr;1076  }1077 1078  /**1079   * Enables the embedder to respond in cases where V8 can't allocate large1080   * blocks of memory. V8 retries the failed allocation once after calling this1081   * method. On success, execution continues; otherwise V8 exits with a fatal1082   * error.1083   * Embedder overrides of this function must NOT call back into V8.1084   */1085  virtual void OnCriticalMemoryPressure() {}1086 1087  /**1088   * Gets the max number of worker threads that may be used to execute1089   * concurrent work scheduled for any single TaskPriority by1090   * Call(BlockingTask)OnWorkerThread() or PostJob(). This can be used to1091   * estimate the number of tasks a work package should be split into. A return1092   * value of 0 means that there are no worker threads available. Note that a1093   * value of 0 won't prohibit V8 from posting tasks using |CallOnWorkerThread|.1094   */1095  virtual int NumberOfWorkerThreads() = 0;1096 1097  /**1098   * Returns a TaskRunner which can be used to post a task on the foreground.1099   * The TaskRunner's NonNestableTasksEnabled() must be true. This function1100   * should only be called from a foreground thread.1101   */1102  std::shared_ptr<v8::TaskRunner> GetForegroundTaskRunner(Isolate* isolate) {1103    return GetForegroundTaskRunner(isolate, TaskPriority::kUserBlocking);1104  }1105 1106  /**1107   * Returns a TaskRunner with a specific |priority| which can be used to post a1108   * task on the foreground thread. The TaskRunner's NonNestableTasksEnabled()1109   * must be true. This function should only be called from a foreground thread.1110   */1111  virtual std::shared_ptr<v8::TaskRunner> GetForegroundTaskRunner(1112      Isolate* isolate, TaskPriority priority) = 0;1113 1114  /**1115   * Schedules a task to be invoked on a worker thread.1116   * Embedders should override PostTaskOnWorkerThreadImpl() instead of1117   * CallOnWorkerThread().1118   */1119  V8_DEPRECATE_SOON("Use PostTaskOnWorkerThread instead.")1120  void CallOnWorkerThread(1121      std::unique_ptr<Task> task,1122      const SourceLocation& location = SourceLocation::Current()) {1123    PostTaskOnWorkerThreadImpl(TaskPriority::kUserVisible, std::move(task),1124                               location);1125  }1126 1127  /**1128   * Schedules a task that blocks the main thread to be invoked with1129   * high-priority on a worker thread.1130   * Embedders should override PostTaskOnWorkerThreadImpl() instead of1131   * CallBlockingTaskOnWorkerThread().1132   */1133  V8_DEPRECATE_SOON("Use PostTaskOnWorkerThread instead.")1134  void CallBlockingTaskOnWorkerThread(1135      std::unique_ptr<Task> task,1136      const SourceLocation& location = SourceLocation::Current()) {1137    // Embedders may optionally override this to process these tasks in a high1138    // priority pool.1139    PostTaskOnWorkerThreadImpl(TaskPriority::kUserBlocking, std::move(task),1140                               location);1141  }1142 1143  /**1144   * Schedules a task to be invoked with low-priority on a worker thread.1145   * Embedders should override PostTaskOnWorkerThreadImpl() instead of1146   * CallLowPriorityTaskOnWorkerThread().1147   */1148  V8_DEPRECATE_SOON("Use PostTaskOnWorkerThread instead.")1149  void CallLowPriorityTaskOnWorkerThread(1150      std::unique_ptr<Task> task,1151      const SourceLocation& location = SourceLocation::Current()) {1152    // Embedders may optionally override this to process these tasks in a low1153    // priority pool.1154    PostTaskOnWorkerThreadImpl(TaskPriority::kBestEffort, std::move(task),1155                               location);1156  }1157 1158  /**1159   * Schedules a task to be invoked on a worker thread after |delay_in_seconds|1160   * expires.1161   * Embedders should override PostDelayedTaskOnWorkerThreadImpl() instead of1162   * CallDelayedOnWorkerThread().1163   */1164  V8_DEPRECATE_SOON("Use PostDelayedTaskOnWorkerThread instead.")1165  void CallDelayedOnWorkerThread(1166      std::unique_ptr<Task> task, double delay_in_seconds,1167      const SourceLocation& location = SourceLocation::Current()) {1168    PostDelayedTaskOnWorkerThreadImpl(TaskPriority::kUserVisible,1169                                      std::move(task), delay_in_seconds,1170                                      location);1171  }1172 1173  /**1174   * Schedules a task to be invoked on a worker thread.1175   * Embedders should override PostTaskOnWorkerThreadImpl() instead of1176   * PostTaskOnWorkerThread().1177   */1178  void PostTaskOnWorkerThread(1179      TaskPriority priority, std::unique_ptr<Task> task,1180      const SourceLocation& location = SourceLocation::Current()) {1181    PostTaskOnWorkerThreadImpl(priority, std::move(task), location);1182  }1183 1184  /**1185   * Schedules a task to be invoked on a worker thread after |delay_in_seconds|1186   * expires.1187   * Embedders should override PostDelayedTaskOnWorkerThreadImpl() instead of1188   * PostDelayedTaskOnWorkerThread().1189   */1190  void PostDelayedTaskOnWorkerThread(1191      TaskPriority priority, std::unique_ptr<Task> task,1192      double delay_in_seconds,1193      const SourceLocation& location = SourceLocation::Current()) {1194    PostDelayedTaskOnWorkerThreadImpl(priority, std::move(task),1195                                      delay_in_seconds, location);1196  }1197 1198  /**1199   * Returns true if idle tasks are enabled for the given |isolate|.1200   */1201  virtual bool IdleTasksEnabled(Isolate* isolate) { return false; }1202 1203  /**1204   * Posts |job_task| to run in parallel. Returns a JobHandle associated with1205   * the Job, which can be joined or canceled.1206   * This avoids degenerate cases:1207   * - Calling CallOnWorkerThread() for each work item, causing significant1208   *   overhead.1209   * - Fixed number of CallOnWorkerThread() calls that split the work and might1210   *   run for a long time. This is problematic when many components post1211   *   "num cores" tasks and all expect to use all the cores. In these cases,1212   *   the scheduler lacks context to be fair to multiple same-priority requests1213   *   and/or ability to request lower priority work to yield when high priority1214   *   work comes in.1215   * A canonical implementation of |job_task| looks like:1216   * class MyJobTask : public JobTask {1217   *  public:1218   *   MyJobTask(...) : worker_queue_(...) {}1219   *   // JobTask:1220   *   void Run(JobDelegate* delegate) override {1221   *     while (!delegate->ShouldYield()) {1222   *       // Smallest unit of work.1223   *       auto work_item = worker_queue_.TakeWorkItem(); // Thread safe.1224   *       if (!work_item) return;1225   *       ProcessWork(work_item);1226   *     }1227   *   }1228   *1229   *   size_t GetMaxConcurrency() const override {1230   *     return worker_queue_.GetSize(); // Thread safe.1231   *   }1232   * };1233   * auto handle = PostJob(TaskPriority::kUserVisible,1234   *                       std::make_unique<MyJobTask>(...));1235   * handle->Join();1236   *1237   * PostJob() and methods of the returned JobHandle/JobDelegate, must never be1238   * called while holding a lock that could be acquired by JobTask::Run or1239   * JobTask::GetMaxConcurrency -- that could result in a deadlock. This is1240   * because [1] JobTask::GetMaxConcurrency may be invoked while holding1241   * internal lock (A), hence JobTask::GetMaxConcurrency can only use a lock (B)1242   * if that lock is *never* held while calling back into JobHandle from any1243   * thread (A=>B/B=>A deadlock) and [2] JobTask::Run or1244   * JobTask::GetMaxConcurrency may be invoked synchronously from JobHandle1245   * (B=>JobHandle::foo=>B deadlock).1246   * Embedders should override CreateJobImpl() instead of PostJob().1247   */1248  std::unique_ptr<JobHandle> PostJob(1249      TaskPriority priority, std::unique_ptr<JobTask> job_task,1250      const SourceLocation& location = SourceLocation::Current()) {1251    auto handle = CreateJob(priority, std::move(job_task), location);1252    handle->NotifyConcurrencyIncrease();1253    return handle;1254  }1255 1256  /**1257   * Creates and returns a JobHandle associated with a Job. Unlike PostJob(),1258   * this doesn't immediately schedules |worker_task| to run; the Job is then1259   * scheduled by calling either NotifyConcurrencyIncrease() or Join().1260   *1261   * A sufficient CreateJob() implementation that uses the default Job provided1262   * in libplatform looks like:1263   *  std::unique_ptr<JobHandle> CreateJob(1264   *      TaskPriority priority, std::unique_ptr<JobTask> job_task) override {1265   *    return v8::platform::NewDefaultJobHandle(1266   *        this, priority, std::move(job_task), NumberOfWorkerThreads());1267   * }1268   *1269   * Embedders should override CreateJobImpl() instead of CreateJob().1270   */1271  std::unique_ptr<JobHandle> CreateJob(1272      TaskPriority priority, std::unique_ptr<JobTask> job_task,1273      const SourceLocation& location = SourceLocation::Current()) {1274    return CreateJobImpl(priority, std::move(job_task), location);1275  }1276 1277  /**1278   * Instantiates a ScopedBlockingCall to annotate a scope that may/will block.1279   */1280  virtual std::unique_ptr<ScopedBlockingCall> CreateBlockingScope(1281      BlockingType blocking_type) {1282    return nullptr;1283  }1284 1285  /**1286   * Monotonically increasing time in seconds from an arbitrary fixed point in1287   * the past. This function is expected to return at least1288   * millisecond-precision values. For this reason,1289   * it is recommended that the fixed point be no further in the past than1290   * the epoch.1291   **/1292  virtual double MonotonicallyIncreasingTime() = 0;1293 1294  /**1295   * Current wall-clock time in milliseconds since epoch. Use1296   * CurrentClockTimeMillisHighResolution() when higher precision is1297   * required.1298   */1299  virtual int64_t CurrentClockTimeMilliseconds() {1300    return static_cast<int64_t>(floor(CurrentClockTimeMillis()));1301  }1302 1303  /**1304   * This function is deprecated and will be deleted. Use either1305   * CurrentClockTimeMilliseconds() or1306   * CurrentClockTimeMillisecondsHighResolution().1307   */1308  virtual double CurrentClockTimeMillis() = 0;1309 1310  /**1311   * Same as CurrentClockTimeMilliseconds(), but with more precision.1312   */1313  virtual double CurrentClockTimeMillisecondsHighResolution() {1314    return CurrentClockTimeMillis();1315  }1316 1317  typedef void (*StackTracePrinter)();1318 1319  /**1320   * Returns a function pointer that print a stack trace of the current stack1321   * on invocation. Disables printing of the stack trace if nullptr.1322   */1323  virtual StackTracePrinter GetStackTracePrinter() { return nullptr; }1324 1325  /**1326   * Returns an instance of a v8::TracingController. This must be non-nullptr.1327   */1328  virtual TracingController* GetTracingController() = 0;1329 1330  /**1331   * Tells the embedder to generate and upload a crashdump during an unexpected1332   * but non-critical scenario.1333   */1334  virtual void DumpWithoutCrashing() {}1335 1336  /**1337   * Allows the embedder to observe sections with high throughput allocation1338   * operations.1339   */1340  virtual HighAllocationThroughputObserver*1341  GetHighAllocationThroughputObserver() {1342    static HighAllocationThroughputObserver default_observer;1343    return &default_observer;1344  }1345 1346 protected:1347  /**1348   * Default implementation of current wall-clock time in milliseconds1349   * since epoch. Useful for implementing |CurrentClockTimeMillis| if1350   * nothing special needed.1351   */1352  V8_EXPORT static double SystemClockTimeMillis();1353 1354  /**1355   * Creates and returns a JobHandle associated with a Job.1356   */1357  virtual std::unique_ptr<JobHandle> CreateJobImpl(1358      TaskPriority priority, std::unique_ptr<JobTask> job_task,1359      const SourceLocation& location) = 0;1360 1361  /**1362   * Schedules a task with |priority| to be invoked on a worker thread.1363   */1364  virtual void PostTaskOnWorkerThreadImpl(TaskPriority priority,1365                                          std::unique_ptr<Task> task,1366                                          const SourceLocation& location) = 0;1367 1368  /**1369   * Schedules a task with |priority| to be invoked on a worker thread after1370   * |delay_in_seconds| expires.1371   */1372  virtual void PostDelayedTaskOnWorkerThreadImpl(1373      TaskPriority priority, std::unique_ptr<Task> task,1374      double delay_in_seconds, const SourceLocation& location) = 0;1375};1376 1377}  // namespace v81378 1379#endif  // V8_V8_PLATFORM_H_1380