include/node/v8-weak-callback-info.h

0001 // Copyright 2021 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 INCLUDE_V8_WEAK_CALLBACK_INFO_H_
0006 #define INCLUDE_V8_WEAK_CALLBACK_INFO_H_
0007
0008 #include <cstring>
0009
0010 #include "cppgc/internal/conditional-stack-allocated.h"  // NOLINT(build/include_directory)
0011 #include "v8config.h"  // NOLINT(build/include_directory)
0012
0013 namespace v8 {
0014
0015 class Isolate;
0016
0017 namespace api_internal {
0018 V8_EXPORT void InternalFieldOutOfBounds(int index);
0019 }  // namespace api_internal
0020
0021 static constexpr int kInternalFieldsInWeakCallback = 2;
0022 static constexpr int kEmbedderFieldsInWeakCallback = 2;
0023
0024 template <typename T>
0025 class WeakCallbackInfo
0026     : public cppgc::internal::ConditionalStackAllocatedBase<T> {
0027  public:
0028   using Callback = void (*)(const WeakCallbackInfo<T>& data);
0029
0030   WeakCallbackInfo(Isolate* isolate, T* parameter,
0031                    void* embedder_fields[kEmbedderFieldsInWeakCallback],
0032                    Callback* callback)
0033       : isolate_(isolate), parameter_(parameter), callback_(callback) {
0034     memcpy(embedder_fields_, embedder_fields,
0035            sizeof(embedder_fields[0]) * kEmbedderFieldsInWeakCallback);
0036   }
0037
0038   V8_INLINE Isolate* GetIsolate() const { return isolate_; }
0039   V8_INLINE T* GetParameter() const { return parameter_; }
0040   V8_INLINE void* GetInternalField(int index) const;
0041
0042   /**
0043    * When a weak callback is first invoked the embedders _must_ Reset() the
0044    * handle which triggered the callback. The handle itself is unusable for
0045    * anything else. No other V8 API calls may be called in the first callback.
0046    * Additional work requires scheduling a second invocation via
0047    * `SetSecondPassCallback()` which will be called some time after all the
0048    * initial callbacks are processed.
0049    *
0050    * The second pass callback is prohibited from executing JavaScript. Embedders
0051    * should schedule another callback in case this is required.
0052    */
0053   void SetSecondPassCallback(Callback callback) const { *callback_ = callback; }
0054
0055  private:
0056   Isolate* isolate_;
0057   T* parameter_;
0058   Callback* callback_;
0059   void* embedder_fields_[kEmbedderFieldsInWeakCallback];
0060 };
0061
0062 /**
0063  * Weakness type for weak handles.
0064  */
0065 enum class WeakCallbackType {
0066   /**
0067    * Passes a user-defined void* parameter back to the callback.
0068    */
0069   kParameter,
0070   /**
0071    * Passes the first two internal fields of the object back to the callback.
0072    */
0073   kInternalFields,
0074 };
0075
0076 template <class T>
0077 void* WeakCallbackInfo<T>::GetInternalField(int index) const {
0078 #ifdef V8_ENABLE_CHECKS
0079   if (index < 0 || index >= kEmbedderFieldsInWeakCallback) {
0080     api_internal::InternalFieldOutOfBounds(index);
0081   }
0082 #endif
0083   return embedder_fields_[index];
0084 }
0085
0086 }  // namespace v8
0087
0088 #endif  // INCLUDE_V8_WEAK_CALLBACK_INFO_H_