chromium/v8/include/v8-platform.h

// Copyright 2013 the V8 project authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef V8_V8_PLATFORM_H_
#define V8_V8_PLATFORM_H_

#include <math.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>  // For abort.

#include <memory>
#include <string>

#include "v8-source-location.h"  // NOLINT(build/include_directory)
#include "v8config.h"            // NOLINT(build/include_directory)

namespace v8 {

class Isolate;

// Valid priorities supported by the task scheduling infrastructure.
enum class TaskPriority : uint8_t { … };

/**
 * A Task represents a unit of work.
 */
class Task { … };

/**
 * An IdleTask represents a unit of work to be performed in idle time.
 * The Run method is invoked with an argument that specifies the deadline in
 * seconds returned by MonotonicallyIncreasingTime().
 * The idle task is expected to complete by this deadline.
 */
class IdleTask { … };

/**
 * A TaskRunner allows scheduling of tasks. The TaskRunner may still be used to
 * post tasks after the isolate gets destructed, but these tasks may not get
 * executed anymore. All tasks posted to a given TaskRunner will be invoked in
 * sequence. Tasks can be posted from any thread.
 */
class TaskRunner { … };

/**
 * Delegate that's passed to Job's worker task, providing an entry point to
 * communicate with the scheduler.
 */
class JobDelegate { … };

/**
 * Handle returned when posting a Job. Provides methods to control execution of
 * the posted Job.
 */
class JobHandle { … };

/**
 * A JobTask represents work to run in parallel from Platform::PostJob().
 */
class JobTask { … };

/**
 * A "blocking call" refers to any call that causes the calling thread to wait
 * off-CPU. It includes but is not limited to calls that wait on synchronous
 * file I/O operations: read or write a file from disk, interact with a pipe or
 * a socket, rename or delete a file, enumerate files in a directory, etc.
 * Acquiring a low contention lock is not considered a blocking call.
 */

/**
 * BlockingType indicates the likelihood that a blocking call will actually
 * block.
 */
enum class BlockingType { … };

/**
 * This class is instantiated with CreateBlockingScope() in every scope where a
 * blocking call is made and serves as a precise annotation of the scope that
 * may/will block. May be implemented by an embedder to adjust the thread count.
 * CPU usage should be minimal within that scope. ScopedBlockingCalls can be
 * nested.
 */
class ScopedBlockingCall { … };

/**
 * The interface represents complex arguments to trace events.
 */
class ConvertableToTraceFormat { … };

/**
 * V8 Tracing controller.
 *
 * Can be implemented by an embedder to record trace events from V8.
 *
 * Will become obsolete in Perfetto SDK build (v8_use_perfetto = true).
 */
class TracingController { … };

/**
 * A V8 memory page allocator.
 *
 * Can be implemented by an embedder to manage large host OS allocations.
 */
class PageAllocator { … };

/**
 * An allocator that uses per-thread permissions to protect the memory.
 *
 * The implementation is platform/hardware specific, e.g. using pkeys on x64.
 *
 * INTERNAL ONLY: This interface has not been stabilised and may change
 * without notice from one release to another without being deprecated first.
 */
class ThreadIsolatedAllocator { … };

// Opaque type representing a handle to a shared memory region.
PlatformSharedMemoryHandle;
static constexpr PlatformSharedMemoryHandle kInvalidSharedMemoryHandle = …;

// Conversion routines from the platform-dependent shared memory identifiers
// into the opaque PlatformSharedMemoryHandle type. These use the underlying
// types (e.g. unsigned int) instead of the typedef'd ones (e.g. mach_port_t)
// to avoid pulling in large OS header files into this header file. Instead,
// the users of these routines are expected to include the respecitve OS
// headers in addition to this one.
#if V8_OS_DARWIN
// Convert between a shared memory handle and a mach_port_t referencing a memory
// entry object.
inline PlatformSharedMemoryHandle SharedMemoryHandleFromMachMemoryEntry(
    unsigned int port) {
  return static_cast<PlatformSharedMemoryHandle>(port);
}
inline unsigned int MachMemoryEntryFromSharedMemoryHandle(
    PlatformSharedMemoryHandle handle) {
  return static_cast<unsigned int>(handle);
}
#elif V8_OS_FUCHSIA
// Convert between a shared memory handle and a zx_handle_t to a VMO.
inline PlatformSharedMemoryHandle SharedMemoryHandleFromVMO(uint32_t handle) {
  return static_cast<PlatformSharedMemoryHandle>(handle);
}
inline uint32_t VMOFromSharedMemoryHandle(PlatformSharedMemoryHandle handle) {
  return static_cast<uint32_t>(handle);
}
#elif V8_OS_WIN
// Convert between a shared memory handle and a Windows HANDLE to a file mapping
// object.
inline PlatformSharedMemoryHandle SharedMemoryHandleFromFileMapping(
    void* handle) {
  return reinterpret_cast<PlatformSharedMemoryHandle>(handle);
}
inline void* FileMappingFromSharedMemoryHandle(
    PlatformSharedMemoryHandle handle) {
  return reinterpret_cast<void*>(handle);
}
#else
// Convert between a shared memory handle and a file descriptor.
inline PlatformSharedMemoryHandle SharedMemoryHandleFromFileDescriptor(int fd) { … }
inline int FileDescriptorFromSharedMemoryHandle(
    PlatformSharedMemoryHandle handle) { … }
#endif

/**
 * Possible permissions for memory pages.
 */
enum class PagePermissions { … };

/**
 * Class to manage a virtual memory address space.
 *
 * This class represents a contiguous region of virtual address space in which
 * sub-spaces and (private or shared) memory pages can be allocated, freed, and
 * modified. This interface is meant to eventually replace the PageAllocator
 * interface, and can be used as an alternative in the meantime.
 *
 * This API is not yet stable and may change without notice!
 */
class VirtualAddressSpace { … };

/**
 * Observer used by V8 to notify the embedder about entering/leaving sections
 * with high throughput of malloc/free operations.
 */
class HighAllocationThroughputObserver { … };

/**
 * V8 Platform abstraction layer.
 *
 * The embedder has to provide an implementation of this interface before
 * initializing the rest of V8.
 */
class Platform { … };

}  // namespace v8

#endif  // V8_V8_PLATFORM_H_