include/node/v8-external.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_EXTERNAL_H_
0006 #define INCLUDE_V8_EXTERNAL_H_
0007
0008 #include "v8-value.h"  // NOLINT(build/include_directory)
0009 #include "v8config.h"  // NOLINT(build/include_directory)
0010
0011 namespace v8 {
0012
0013 class Isolate;
0014
0015 /**
0016  * A tag for external pointers. Objects with different C++ types should use
0017  * different values of ExternalPointerTypeTag when using v8::External. The
0018  * allowed range is 0..V8_EXTERNAL_POINTER_TAG_COUNT - 1. If this is not
0019  * sufficient, V8_EXTERNAL_POINTER_TAG_COUNT can be increased.
0020  */
0021 using ExternalPointerTypeTag = uint16_t;
0022
0023 constexpr ExternalPointerTypeTag kExternalPointerTypeTagDefault = 0;
0024
0025 /**
0026  * A JavaScript value that wraps a C++ void*. This type of value is mainly used
0027  * to associate C++ data structures with JavaScript objects.
0028  */
0029 class V8_EXPORT External : public Value {
0030  public:
0031   V8_DEPRECATED("Use the version with the type tag.")
0032   static Local<External> New(Isolate* isolate, void* value) {
0033     return New(isolate, value, kExternalPointerTypeTagDefault);
0034   }
0035   /**
0036    * Creates a new External object.
0037    *
0038    * \param isolate The isolate for the external object.
0039    * \param value The C++ pointer value.
0040    * \param tag The type tag of the external pointer. If type tags are not used
0041    * in the embedder, the default value `kExternalPointerTypeTagDefault` can be
0042    * used.
0043    * \return The new External object.
0044    */
0045   static Local<External> New(Isolate* isolate, void* value,
0046                              ExternalPointerTypeTag tag);
0047   V8_INLINE static External* Cast(Data* value) {
0048 #ifdef V8_ENABLE_CHECKS
0049     CheckCast(value);
0050 #endif
0051     return static_cast<External*>(value);
0052   }
0053
0054   V8_DEPRECATED("Use the version with the type tag.")
0055   void* Value() const { return Value(kExternalPointerTypeTagDefault); }
0056
0057   /**
0058    * Returns the value of the external pointer.
0059    *
0060    * \param tag The type tag of the external pointer. If type tags are not used
0061    * in the embedder, the default value `kExternalPointerTypeTagDefault` can be
0062    * used.
0063    * \return The value of the external pointer.
0064    */
0065   void* Value(ExternalPointerTypeTag tag) const;
0066
0067  private:
0068   static void CheckCast(v8::Data* obj);
0069 };
0070
0071 }  // namespace v8
0072
0073 #endif  // INCLUDE_V8_EXTERNAL_H_