node-darwin-x64 25.8.2 → 26.0.0

package/include/node/v8-platform.h

@@ -316,6 +316,29 @@ class JobTask {
   virtual size_t GetMaxConcurrency(size_t worker_count) const = 0;
 };
 
+// Allows a thread to temporarily boost another thread's priority to match its
+// own priority. The priority is reset when the object is destroyed, which must
+// happens on the boosted thread.
+class ScopedBoostablePriority {
+ public:
+  ScopedBoostablePriority() = default;
+  virtual ~ScopedBoostablePriority() = default;
+  ScopedBoostablePriority(const ScopedBoostablePriority&) = delete;
+  ScopedBoostablePriority& operator=(const ScopedBoostablePriority& other) =
+      delete;
+
+  // Boosts the priority of the thread where this ScopedBoostablePriority was
+  // created. Can be called from any thread, but requires proper external
+  // synchronization with the constructor, destructor and any other call to
+  // BoostPriority/Reset(). If called multiple times, only the first call takes
+  // effect.
+  virtual bool BoostPriority() = 0;
+
+  // Resets the priority of the thread where this ScopedBoostablePriority was
+  // created to its original priority.
+  virtual void Reset() = 0;
+};
+
 /**
  * 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
@@ -369,7 +392,7 @@ class ConvertableToTraceFormat {
  *
  * Can be implemented by an embedder to record trace events from V8.
  *
- * Will become obsolete in Perfetto SDK build (v8_use_perfetto = true).
+ * Will become obsolete in Perfetto build (v8_use_perfetto = true).
  */
 class TracingController {
  public:
@@ -446,6 +469,77 @@ class TracingController {
   virtual void RemoveTraceStateObserver(TraceStateObserver*) {}
 };
 
+// Opaque type representing a handle to a shared memory region.
+class SharedMemoryHandle {
+ public:
+  // For the handle itself, we use the underlying type (e.g. unsigned int)
+  // instead of 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 respective OS headers in addition to this one.
+
+#if V8_OS_DARWIN
+  // A mach_port_t referencing a memory entry object.
+  using PlatformHandle = unsigned int;
+#elif V8_OS_FUCHSIA
+  // A zx_handle_t to a VMO.
+  using PlatformHandle = uint32_t;
+#elif V8_OS_WIN
+  // A Windows HANDLE to a file mapping object.
+  using PlatformHandle = void*;
+#else
+  // A file descriptor.
+  using PlatformHandle = int;
+#endif
+
+  static constexpr SharedMemoryHandle FromPlatformHandle(
+      PlatformHandle handle) {
+    return SharedMemoryHandle(handle);
+  }
+
+  PlatformHandle GetPlatformHandle() const { return handle_; }
+
+ private:
+  SharedMemoryHandle() = delete;
+  explicit constexpr SharedMemoryHandle(PlatformHandle handle)
+      : handle_(handle) {}
+
+  PlatformHandle handle_;
+};
+
+#define DEFINE_SHARED_MEMORY_HANDLE_WRAPPERS(Wrap, Unwrap)                    \
+  V8_DEPRECATE_SOON("Use SharedMemoryHandle::FromPlatformHandle instead")     \
+  inline SharedMemoryHandle Wrap(SharedMemoryHandle::PlatformHandle handle) { \
+    return SharedMemoryHandle::FromPlatformHandle(handle);                    \
+  }                                                                           \
+  V8_DEPRECATE_SOON("Use SharedMemoryHandle::GetPlatformHandle instead")      \
+  inline SharedMemoryHandle::PlatformHandle Unwrap(                           \
+      SharedMemoryHandle handle) {                                            \
+    return handle.GetPlatformHandle();                                        \
+  }
+
+#if V8_OS_DARWIN
+DEFINE_SHARED_MEMORY_HANDLE_WRAPPERS(SharedMemoryHandleFromMachMemoryEntry,
+                                     MachMemoryEntryFromSharedMemoryHandle)
+#elif V8_OS_FUCHSIA
+DEFINE_SHARED_MEMORY_HANDLE_WRAPPERS(SharedMemoryHandleFromVMO,
+                                     VMOFromSharedMemoryHandle)
+#elif V8_OS_WIN
+DEFINE_SHARED_MEMORY_HANDLE_WRAPPERS(SharedMemoryHandleFromFileMapping,
+                                     FileMappingFromSharedMemoryHandle)
+#else
+DEFINE_SHARED_MEMORY_HANDLE_WRAPPERS(SharedMemoryHandleFromFileDescriptor,
+                                     FileDescriptorFromSharedMemoryHandle)
+#endif
+
+#undef DEFINE_SHARED_MEMORY_HANDLE_WRAPPERS
+
+// TODO(https://crbug.com/463925491): Remove this type alias once Chromium's
+// "gin" V8 binding migrates off it.
+using PlatformSharedMemoryHandle = std::optional<SharedMemoryHandle>;
+V8_DEPRECATE_SOON("Use std::nullopt instead")
+static constexpr PlatformSharedMemoryHandle kInvalidSharedMemoryHandle =
+    std::nullopt;
+
 /**
  * A V8 memory page allocator.
  *
@@ -703,67 +797,44 @@ class ThreadIsolatedAllocator {
   virtual int Pkey() const { return -1; }
 };
 
-// Opaque type representing a handle to a shared memory region.
-using PlatformSharedMemoryHandle = intptr_t;
-static constexpr PlatformSharedMemoryHandle kInvalidSharedMemoryHandle = -1;
-
-// 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);
+/**
+ * Possible permissions for memory pages.
+ */
+enum class PagePermissions {
+  kNoAccess = 0,
+  kRead = 1,
+  kWrite = 2,
+  kExecute = 4,
+  kReadWrite = kRead | kWrite,
+  kReadExecute = kRead | kExecute,
+  kWriteExecute = kWrite | kExecute,
+  kReadWriteExecute = kRead | kWrite | kExecute,
+};
+
+inline constexpr PagePermissions operator|(PagePermissions lhs,
+                                           PagePermissions rhs) {
+  return static_cast<PagePermissions>(static_cast<int>(lhs) |
+                                      static_cast<int>(rhs));
 }
-#else
-// Convert between a shared memory handle and a file descriptor.
-inline PlatformSharedMemoryHandle SharedMemoryHandleFromFileDescriptor(int fd) {
-  return static_cast<PlatformSharedMemoryHandle>(fd);
+
+inline constexpr PagePermissions operator&(PagePermissions lhs,
+                                           PagePermissions rhs) {
+  return static_cast<PagePermissions>(static_cast<int>(lhs) &
+                                      static_cast<int>(rhs));
 }
-inline int FileDescriptorFromSharedMemoryHandle(
-    PlatformSharedMemoryHandle handle) {
-  return static_cast<int>(handle);
+
+inline PagePermissions& operator|=(PagePermissions& lhs, PagePermissions rhs) {
+  lhs = lhs | rhs;
+  return lhs;
 }
-#endif
 
 /**
- * Possible permissions for memory pages.
+ * Helper routine to determine whether one set of page permissions (the lhs) is
+ * a subset of another one (the rhs).
  */
-enum class PagePermissions {
-  kNoAccess,
-  kRead,
-  kReadWrite,
-  kReadWriteExecute,
-  kReadExecute,
-};
+inline constexpr bool IsSubset(PagePermissions lhs, PagePermissions rhs) {
+  return (lhs & rhs) == lhs;
+}
 
 /**
  * Class to manage a virtual memory address space.
@@ -970,7 +1041,16 @@ class VirtualAddressSpace {
    */
   virtual V8_WARN_UNUSED_RESULT Address
   AllocateSharedPages(Address hint, size_t size, PagePermissions permissions,
-                      PlatformSharedMemoryHandle handle, uint64_t offset) = 0;
+                      SharedMemoryHandle handle, uint64_t offset) = 0;
+
+  // TODO(https://crbug.com/463925491): Remove me once API users change from
+  // PlatformSharedMemoryHandle to SharedMemoryHandle.
+  V8_DEPRECATE_SOON("Use AllocateSharedPages() with SharedMemoryHandle")
+  V8_WARN_UNUSED_RESULT Address AllocateSharedPages(
+      Address hint, size_t size, PagePermissions permissions,
+      std::optional<SharedMemoryHandle> handle, uint64_t offset) {
+    return AllocateSharedPages(hint, size, permissions, *handle, offset);
+  }
 
   /**
    * Frees previously allocated shared pages.
@@ -1038,12 +1118,17 @@ class VirtualAddressSpace {
    * \param key Optional memory protection key for the subspace. If used, the
    * returned subspace will use this key for all its memory pages.
    *
+   * \param handle Optional file descriptor for the subspace. If used, the
+   * returned subspace will use this file descriptor with 0 offset as the
+   * space's underlying file.
+   *
    * \returns a new subspace or nullptr on failure.
    */
   virtual std::unique_ptr<VirtualAddressSpace> AllocateSubspace(
       Address hint, size_t size, size_t alignment,
       PagePermissions max_page_permissions,
-      std::optional<MemoryProtectionKeyId> key = std::nullopt) = 0;
+      std::optional<MemoryProtectionKeyId> key = std::nullopt,
+      std::optional<SharedMemoryHandle> handle = std::nullopt) = 0;
 
   //
   // TODO(v8) maybe refactor the methods below before stabilizing the API. For
@@ -1096,6 +1181,22 @@ class VirtualAddressSpace {
   virtual V8_WARN_UNUSED_RESULT bool DecommitPages(Address address,
                                                    size_t size) = 0;
 
+  /**
+   * Sets a name for the address space.
+   *
+   * This is mostly useful for debugging tools. If supported by the system, the
+   * name will for example show up in /proc/$pid/maps next to the virtual
+   * address reservation:
+   *
+   *     2ae700000000-2ae700010000 r--p 00000000 00:00 0  [anon:foo-bar]
+   *
+   * \param name The name of the address space. The name must only contain
+   * alphanumeric characters or dashes.
+   *
+   * \returns true on success, false otherwise.
+   */
+  virtual bool SetName(const std::string& name) { return false; }
+
  private:
   const size_t page_size_;
   const size_t allocation_granularity_;
@@ -1338,6 +1439,14 @@ class Platform {
     return CreateJobImpl(priority, std::move(job_task), location);
   }
 
+  /**
+   * Instantiates a ScopedBoostablePriority to boost a thread's priority.
+   */
+  virtual std::unique_ptr<ScopedBoostablePriority>
+  CreateBoostablePriorityScope() {
+    return nullptr;
+  }
+
   /**
    * Instantiates a ScopedBlockingCall to annotate a scope that may/will block.
    */

package/include/node/v8-primitive.h

@@ -136,15 +136,9 @@ class V8_EXPORT String : public Name {
    */
   int Length() const;
 
-  /**
-   * Returns the number of bytes in the UTF-8 encoded
-   * representation of this string.
-   */
-  V8_DEPRECATED("Use Utf8LengthV2 instead.")
-  int Utf8Length(Isolate* isolate) const;
-
   /**
    * Returns the number of bytes needed for the Utf8 encoding of this string.
+   * TODO(http://crbug.com/373485796): rename back to Utf8Length().
    */
   size_t Utf8LengthV2(Isolate* isolate) const;
 
@@ -163,55 +157,6 @@ class V8_EXPORT String : public Name {
    */
   bool ContainsOnlyOneByte() const;
 
-  /**
-   * Write the contents of the string to an external buffer.
-   * If no arguments are given, expects the buffer to be large
-   * enough to hold the entire string and NULL terminator. Copies
-   * the contents of the string and the NULL terminator into the
-   * buffer.
-   *
-   * WriteUtf8 will not write partial UTF-8 sequences, preferring to stop
-   * before the end of the buffer.
-   *
-   * Copies up to length characters into the output buffer.
-   * Only null-terminates if there is enough space in the buffer.
-   *
-   * \param buffer The buffer into which the string will be copied.
-   * \param start The starting position within the string at which
-   * copying begins.
-   * \param length The number of characters to copy from the string.  For
-   *    WriteUtf8 the number of bytes in the buffer.
-   * \param nchars_ref The number of characters written, can be NULL.
-   * \param options Various options that might affect performance of this or
-   *    subsequent operations.
-   * \return The number of characters copied to the buffer excluding the null
-   *    terminator.  For WriteUtf8: The number of bytes copied to the buffer
-   *    including the null terminator (if written).
-   */
-  enum WriteOptions {
-    NO_OPTIONS = 0,
-    HINT_MANY_WRITES_EXPECTED = 1,
-    NO_NULL_TERMINATION = 2,
-    PRESERVE_ONE_BYTE_NULL = 4,
-    // Used by WriteUtf8 to replace orphan surrogate code units with the
-    // unicode replacement character. Needs to be set to guarantee valid UTF-8
-    // output.
-    REPLACE_INVALID_UTF8 = 8
-  };
-
-  // 16-bit character codes.
-  V8_DEPRECATED("Use WriteV2 instead.")
-  int Write(Isolate* isolate, uint16_t* buffer, int start = 0, int length = -1,
-            int options = NO_OPTIONS) const;
-  // One byte characters.
-  V8_DEPRECATED("Use WriteOneByteV2 instead.")
-  int WriteOneByte(Isolate* isolate, uint8_t* buffer, int start = 0,
-                   int length = -1, int options = NO_OPTIONS) const;
-  // UTF-8 encoded characters.
-  V8_DEPRECATED("Use WriteUtf8V2 instead.")
-  int WriteUtf8(Isolate* isolate, char* buffer, int length = -1,
-                int* nchars_ref = nullptr, int options = NO_OPTIONS) const;
-
   struct WriteFlags {
     enum {
       kNone = 0,
@@ -237,6 +182,8 @@ class V8_EXPORT String : public Name {
    * \param length The number of characters to copy from the string.
    * \param buffer The buffer into which the string will be copied.
    * \param flags Various flags that influence the behavior of this operation.
+   * TODO(http://crbug.com/373485796): rename back to Write() and
+   * WriteOneByte().
    */
   void WriteV2(Isolate* isolate, uint32_t offset, uint32_t length,
                uint16_t* buffer, int flags = WriteFlags::kNone) const;
@@ -252,7 +199,7 @@ class V8_EXPORT String : public Name {
    * the end of the buffer. If null termination is requested, the output buffer
    * will always be null terminated even if not all characters fit. In that
    * case, the capacity must be at least one. The required size of the output
-   * buffer can be determined using Utf8Length().
+   * buffer can be determined using Utf8LengthV2().
    *
    * \param buffer The buffer into which the string will be written.
    * \param capacity The number of bytes available in the output buffer.
@@ -261,6 +208,7 @@ class V8_EXPORT String : public Name {
    * the buffer.
    * \return The number of bytes copied to the buffer including the null
    * terminator (if written).
+   * TODO(http://crbug.com/373485796): rename back to WriteUtf8().
    */
   size_t WriteUtf8V2(Isolate* isolate, char* buffer, size_t capacity,
                      int flags = WriteFlags::kNone,

package/include/node/v8-profiler.h

@@ -48,6 +48,21 @@ template class V8_EXPORT std::vector<v8::CpuProfileDeoptFrame>;
 
 namespace v8 {
 
+/**
+ * Identifies which component initiated CPU profiling for proper attribution.
+ */
+enum class CpuProfileSource : uint8_t {
+  /** Default value when no explicit source is specified. */
+  kUnspecified = 0,
+  /** Profiling initiated via the DevTools Inspector protocol. */
+  kInspector = 1,
+  /** Profiling initiated by the embedder (e.g., Blink) via self-profiling API.
+   */
+  kSelfProfiling = 2,
+  /** Profiling initiated internally by V8 (e.g., tracing CPU profiler). */
+  kInternal = 3,
+};
+
 struct V8_EXPORT CpuProfileDeoptInfo {
   /** A pointer to a static string owned by v8. */
   const char* deopt_reason;
@@ -378,11 +393,13 @@ class V8_EXPORT CpuProfilingOptions {
    *                             the profiler's sampling interval.
    * \param filter_context If specified, profiles will only contain frames
    *                       using this context. Other frames will be elided.
+   * \param profile_source Identifies the source of this CPU profile.
    */
   CpuProfilingOptions(
       CpuProfilingMode mode = kLeafNodeLineNumbers,
       unsigned max_samples = kNoSampleLimit, int sampling_interval_us = 0,
-      MaybeLocal<Context> filter_context = MaybeLocal<Context>());
+      MaybeLocal<Context> filter_context = MaybeLocal<Context>(),
+      CpuProfileSource profile_source = CpuProfileSource::kUnspecified);
 
   CpuProfilingOptions(CpuProfilingOptions&&) = default;
   CpuProfilingOptions& operator=(CpuProfilingOptions&&) = default;
@@ -390,6 +407,7 @@ class V8_EXPORT CpuProfilingOptions {
   CpuProfilingMode mode() const { return mode_; }
   unsigned max_samples() const { return max_samples_; }
   int sampling_interval_us() const { return sampling_interval_us_; }
+  CpuProfileSource profile_source() const { return profile_source_; }
 
  private:
   friend class internal::CpuProfile;
@@ -401,6 +419,7 @@ class V8_EXPORT CpuProfilingOptions {
   unsigned max_samples_;
   int sampling_interval_us_;
   Global<Context> filter_context_;
+  CpuProfileSource profile_source_;
 };
 
 /**
@@ -811,6 +830,12 @@ class V8_EXPORT AllocationProfile {
      * what samples were added or removed between two snapshots.
      */
     uint64_t sample_id;
+
+    /**
+     * Indicates whether the sampled allocation is still live or has already
+     * been collected by GC.
+     */
+    bool is_live;
   };
 
   /**
@@ -1041,6 +1066,8 @@ class V8_EXPORT HeapProfiler {
 
   /**
    * Callback interface for retrieving user friendly names of global objects.
+   *
+   * This interface will soon be deprecated in favour of ContextNameResolver.
    */
   class ObjectNameResolver {
    public:
@@ -1054,6 +1081,23 @@ class V8_EXPORT HeapProfiler {
     virtual ~ObjectNameResolver() = default;
   };
 
+  /**
+   * Callback interface for retrieving user friendly names of a V8::Context
+   * objects.
+   */
+  class ContextNameResolver {
+   public:
+    /**
+     * Returns name to be used in the heap snapshot for given node. Returned
+     * string must stay alive until snapshot collection is completed.
+     * If no user friendly name is available return nullptr.
+     */
+    virtual const char* GetName(Local<Context> context) = 0;
+
+   protected:
+    virtual ~ContextNameResolver() = default;
+  };
+
   enum class HeapSnapshotMode {
     /**
      * Heap snapshot for regular developers.
@@ -1083,6 +1127,10 @@ class V8_EXPORT HeapProfiler {
     // NOLINTNEXTLINE
     HeapSnapshotOptions() {}
 
+    // TODO(https://crbug.com/333672197): remove once ObjectNameResolver is
+    // removed.
+    ALLOW_COPY_AND_MOVE_WITH_DEPRECATED_FIELDS(HeapSnapshotOptions)
+
     /**
      * The control used to report intermediate progress to.
      */
@@ -1090,7 +1138,15 @@ class V8_EXPORT HeapProfiler {
     /**
      * The resolver used by the snapshot generator to get names for V8 objects.
      */
+    V8_DEPRECATED("Use context_name_resolver callback instead.")
     ObjectNameResolver* global_object_name_resolver = nullptr;
+    /**
+     * The resolver used by the snapshot generator to get names for v8::Context
+     * objects.
+     * In case both this and |global_object_name_resolver| callbacks are
+     * provided, this one will be used.
+     */
+    ContextNameResolver* context_name_resolver = nullptr;
     /**
      * Mode for taking the snapshot, see `HeapSnapshotMode`.
      */
@@ -1120,10 +1176,20 @@ class V8_EXPORT HeapProfiler {
    *
    * \returns the snapshot.
    */
+  V8_DEPRECATED("Use overload with ContextNameResolver* resolver instead.")
   const HeapSnapshot* TakeHeapSnapshot(
-      ActivityControl* control,
-      ObjectNameResolver* global_object_name_resolver = nullptr,
+      ActivityControl* control, ObjectNameResolver* global_object_name_resolver,
       bool hide_internals = true, bool capture_numeric_value = false);
+  const HeapSnapshot* TakeHeapSnapshot(ActivityControl* control,
+                                       ContextNameResolver* resolver,
+                                       bool hide_internals = true,
+                                       bool capture_numeric_value = false);
+  // TODO(333672197): remove this version once ObjectNameResolver* overload
+  // is removed.
+  const HeapSnapshot* TakeHeapSnapshot(ActivityControl* control,
+                                       std::nullptr_t resolver = nullptr,
+                                       bool hide_internals = true,
+                                       bool capture_numeric_value = false);
 
   /**
    * Obtains list of Detached JS Wrapper Objects. This functon calls garbage

package/include/node/v8-promise.h

@@ -19,7 +19,7 @@ class Context;
 #endif
 
 /**
- * An instance of the built-in Promise constructor (ES6 draft).
+ * An instance of the built-in Promise constructor.
  */
 class V8_EXPORT Promise : public Object {
  public:
@@ -65,10 +65,21 @@ class V8_EXPORT Promise : public Object {
   };
 
   /**
-   * Register a resolution/rejection handler with a promise.
-   * The handler is given the respective resolution/rejection value as
-   * an argument. If the promise is already resolved/rejected, the handler is
-   * invoked at the end of turn.
+   * Register a resolution/rejection handler with a promise. The handler is
+   * given the respective resolution/rejection value as an argument. If the
+   * promise is already resolved/rejected, the handler is invoked at the end of
+   * turn.
+   *
+   * This performs the PerformPromiseThen abstract operation with a fresh native
+   * promise as result, rather than the similar Promise.prototype.then
+   * operation. In particular, it does not do species lookup on the Promise
+   * constructor, and is therefore guaranteed to return a Promise.
+   *
+   * https://tc39.es/ecma262/#sec-performpromisethen
+   *
+   * This is consistent with Promise reactions in WebIDL:
+   *
+   * https://webidl.spec.whatwg.org/#dfn-perform-steps-once-promise-is-settled
    */
   V8_WARN_UNUSED_RESULT MaybeLocal<Promise> Catch(Local<Context> context,
                                                   Local<Function> handler);