include/node/v8-snapshot.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_SNAPSHOT_H_
0006 #define INCLUDE_V8_SNAPSHOT_H_
0007
0008 #include "v8-internal.h"      // NOLINT(build/include_directory)
0009 #include "v8-isolate.h"       // NOLINT(build/include_directory)
0010 #include "v8-local-handle.h"  // NOLINT(build/include_directory)
0011 #include "v8config.h"         // NOLINT(build/include_directory)
0012
0013 namespace v8 {
0014
0015 class Object;
0016
0017 namespace internal {
0018 class SnapshotCreatorImpl;
0019 }  // namespace internal
0020
0021 class V8_EXPORT StartupData {
0022  public:
0023   /**
0024    * Whether the data created can be rehashed and and the hash seed can be
0025    * recomputed when deserialized.
0026    * Only valid for StartupData returned by SnapshotCreator::CreateBlob().
0027    */
0028   bool CanBeRehashed() const;
0029   /**
0030    * Allows embedders to verify whether the data is valid for the current
0031    * V8 instance.
0032    */
0033   bool IsValid() const;
0034
0035   const char* data;
0036   int raw_size;
0037 };
0038
0039 /**
0040  * Callback and supporting data used in SnapshotCreator to implement embedder
0041  * logic to serialize internal fields of v8::Objects.
0042  * Internal fields that directly reference V8 objects are serialized without
0043  * calling this callback. Internal fields that contain aligned pointers are
0044  * serialized by this callback if it returns non-zero result. Otherwise it is
0045  * serialized verbatim.
0046  */
0047 struct SerializeInternalFieldsCallback {
0048   using CallbackFunction = StartupData (*)(Local<Object> holder, int index,
0049                                            void* data);
0050   SerializeInternalFieldsCallback(CallbackFunction function = nullptr,
0051                                   void* data_arg = nullptr)
0052       : callback(function), data(data_arg) {}
0053   CallbackFunction callback;
0054   void* data;
0055 };
0056
0057 /**
0058  * Similar to SerializeInternalFieldsCallback, but works with the embedder data
0059  * in a v8::Context.
0060  */
0061 struct SerializeContextDataCallback {
0062   using CallbackFunction = StartupData (*)(Local<Context> holder, int index,
0063                                            void* data);
0064   SerializeContextDataCallback(CallbackFunction function = nullptr,
0065                                void* data_arg = nullptr)
0066       : callback(function), data(data_arg) {}
0067   CallbackFunction callback;
0068   void* data;
0069 };
0070
0071 /**
0072  * Similar to `SerializeInternalFieldsCallback`, but is used exclusively to
0073  * serialize API wrappers. The pointers for API wrappers always point into the
0074  * CppHeap.
0075  */
0076 struct SerializeAPIWrapperCallback {
0077   using CallbackFunction = StartupData (*)(Local<Object> holder,
0078                                            void* cpp_heap_pointer, void* data);
0079   explicit SerializeAPIWrapperCallback(CallbackFunction function = nullptr,
0080                                        void* data = nullptr)
0081       : callback(function), data(data) {}
0082
0083   CallbackFunction callback;
0084   void* data;
0085 };
0086
0087 /**
0088  * Callback and supporting data used to implement embedder logic to deserialize
0089  * internal fields of v8::Objects.
0090  */
0091 struct DeserializeInternalFieldsCallback {
0092   using CallbackFunction = void (*)(Local<Object> holder, int index,
0093                                     StartupData payload, void* data);
0094   DeserializeInternalFieldsCallback(CallbackFunction function = nullptr,
0095                                     void* data_arg = nullptr)
0096       : callback(function), data(data_arg) {}
0097
0098   CallbackFunction callback;
0099   void* data;
0100 };
0101
0102 /**
0103  * Similar to DeserializeInternalFieldsCallback, but works with the embedder
0104  * data in a v8::Context.
0105  */
0106 struct DeserializeContextDataCallback {
0107   using CallbackFunction = void (*)(Local<Context> holder, int index,
0108                                     StartupData payload, void* data);
0109   DeserializeContextDataCallback(CallbackFunction function = nullptr,
0110                                  void* data_arg = nullptr)
0111       : callback(function), data(data_arg) {}
0112   CallbackFunction callback;
0113   void* data;
0114 };
0115
0116 struct DeserializeAPIWrapperCallback {
0117   using CallbackFunction = void (*)(Local<Object> holder, StartupData payload,
0118                                     void* data);
0119   explicit DeserializeAPIWrapperCallback(CallbackFunction function = nullptr,
0120                                          void* data = nullptr)
0121       : callback(function), data(data) {}
0122
0123   CallbackFunction callback;
0124   void* data;
0125 };
0126
0127 /**
0128  * Helper class to create a snapshot data blob.
0129  *
0130  * The Isolate used by a SnapshotCreator is owned by it, and will be entered
0131  * and exited by the constructor and destructor, respectively; The destructor
0132  * will also destroy the Isolate. Experimental language features, including
0133  * those available by default, are not available while creating a snapshot.
0134  */
0135 class V8_EXPORT SnapshotCreator {
0136  public:
0137   enum class FunctionCodeHandling { kClear, kKeep };
0138
0139   /**
0140    * Initialize and enter an isolate, and set it up for serialization.
0141    * The isolate is either created from scratch or from an existing snapshot.
0142    * The caller keeps ownership of the argument snapshot.
0143    * \param existing_blob existing snapshot from which to create this one.
0144    * \param external_references a null-terminated array of external references
0145    *        that must be equivalent to CreateParams::external_references.
0146    * \param owns_isolate whether this SnapshotCreator should call
0147    *        v8::Isolate::Dispose() during its destructor.
0148    */
0149   V8_DEPRECATE_SOON("Use the version that passes CreateParams instead.")
0150   explicit SnapshotCreator(Isolate* isolate,
0151                            const intptr_t* external_references = nullptr,
0152                            const StartupData* existing_blob = nullptr,
0153                            bool owns_isolate = true);
0154
0155   /**
0156    * Create and enter an isolate, and set it up for serialization.
0157    * The isolate is either created from scratch or from an existing snapshot.
0158    * The caller keeps ownership of the argument snapshot.
0159    * \param existing_blob existing snapshot from which to create this one.
0160    * \param external_references a null-terminated array of external references
0161    *        that must be equivalent to CreateParams::external_references.
0162    */
0163   V8_DEPRECATE_SOON("Use the version that passes CreateParams instead.")
0164   explicit SnapshotCreator(const intptr_t* external_references = nullptr,
0165                            const StartupData* existing_blob = nullptr);
0166
0167   /**
0168    * Creates an Isolate for serialization and enters it. The creator fully owns
0169    * the Isolate and will invoke `v8::Isolate::Dispose()` during destruction.
0170    *
0171    * \param params The parameters to initialize the Isolate for. Details:
0172    *               - `params.external_references` are expected to be a
0173    *                 null-terminated array of external references.
0174    *               - `params.existing_blob` is an optional snapshot blob from
0175    *                 which can be used to initialize the new blob.
0176    */
0177   explicit SnapshotCreator(const v8::Isolate::CreateParams& params);
0178
0179   /**
0180    * Initializes an Isolate for serialization and enters it. The creator does
0181    * not own the Isolate but merely initialize it properly.
0182    *
0183    * \param isolate The isolate that was allocated by `Isolate::Allocate()~.
0184    * \param params The parameters to initialize the Isolate for. Details:
0185    *               - `params.external_references` are expected to be a
0186    *                 null-terminated array of external references.
0187    *               - `params.existing_blob` is an optional snapshot blob from
0188    *                 which can be used to initialize the new blob.
0189    */
0190   SnapshotCreator(v8::Isolate* isolate,
0191                   const v8::Isolate::CreateParams& params);
0192
0193   /**
0194    * Destroy the snapshot creator, and exit and dispose of the Isolate
0195    * associated with it.
0196    */
0197   ~SnapshotCreator();
0198
0199   /**
0200    * \returns the isolate prepared by the snapshot creator.
0201    */
0202   Isolate* GetIsolate();
0203
0204   /**
0205    * Set the default context to be included in the snapshot blob.
0206    * The snapshot will not contain the global proxy, and we expect one or a
0207    * global object template to create one, to be provided upon deserialization.
0208    *
0209    * \param internal_fields_serializer An optional callback used to serialize
0210    * internal pointer fields set by
0211    * v8::Object::SetAlignedPointerInInternalField().
0212    *
0213    * \param context_data_serializer An optional callback used to serialize
0214    * context embedder data set by
0215    * v8::Context::SetAlignedPointerInEmbedderData().
0216    *
0217    * \param api_wrapper_serializer An optional callback used to serialize API
0218    * wrapper references set via `v8::Object::Wrap()`.
0219    */
0220   void SetDefaultContext(
0221       Local<Context> context,
0222       SerializeInternalFieldsCallback internal_fields_serializer =
0223           SerializeInternalFieldsCallback(),
0224       SerializeContextDataCallback context_data_serializer =
0225           SerializeContextDataCallback(),
0226       SerializeAPIWrapperCallback api_wrapper_serializer =
0227           SerializeAPIWrapperCallback());
0228
0229   /**
0230    * Add additional context to be included in the snapshot blob.
0231    * The snapshot will include the global proxy.
0232    *
0233    * \param internal_fields_serializer Similar to internal_fields_serializer
0234    * in SetDefaultContext() but only applies to the context being added.
0235    *
0236    * \param context_data_serializer Similar to context_data_serializer
0237    * in SetDefaultContext() but only applies to the context being added.
0238    *
0239    * \param api_wrapper_serializer Similar to api_wrapper_serializer
0240    * in SetDefaultContext() but only applies to the context being added.
0241    */
0242   size_t AddContext(Local<Context> context,
0243                     SerializeInternalFieldsCallback internal_fields_serializer =
0244                         SerializeInternalFieldsCallback(),
0245                     SerializeContextDataCallback context_data_serializer =
0246                         SerializeContextDataCallback(),
0247                     SerializeAPIWrapperCallback api_wrapper_serializer =
0248                         SerializeAPIWrapperCallback());
0249
0250   /**
0251    * Attach arbitrary V8::Data to the context snapshot, which can be retrieved
0252    * via Context::GetDataFromSnapshotOnce after deserialization. This data does
0253    * not survive when a new snapshot is created from an existing snapshot.
0254    * \returns the index for retrieval.
0255    */
0256   template <class T>
0257   V8_INLINE size_t AddData(Local<Context> context, Local<T> object);
0258
0259   /**
0260    * Attach arbitrary V8::Data to the isolate snapshot, which can be retrieved
0261    * via Isolate::GetDataFromSnapshotOnce after deserialization. This data does
0262    * not survive when a new snapshot is created from an existing snapshot.
0263    * \returns the index for retrieval.
0264    */
0265   template <class T>
0266   V8_INLINE size_t AddData(Local<T> object);
0267
0268   /**
0269    * Created a snapshot data blob.
0270    * This must not be called from within a handle scope.
0271    * \param function_code_handling whether to include compiled function code
0272    *        in the snapshot.
0273    * \returns { nullptr, 0 } on failure, and a startup snapshot on success. The
0274    *        caller acquires ownership of the data array in the return value.
0275    */
0276   StartupData CreateBlob(FunctionCodeHandling function_code_handling);
0277
0278   // Disallow copying and assigning.
0279   SnapshotCreator(const SnapshotCreator&) = delete;
0280   void operator=(const SnapshotCreator&) = delete;
0281
0282  private:
0283   size_t AddData(Local<Context> context, internal::Address object);
0284   size_t AddData(internal::Address object);
0285
0286   internal::SnapshotCreatorImpl* impl_;
0287   friend class internal::SnapshotCreatorImpl;
0288 };
0289
0290 template <class T>
0291 size_t SnapshotCreator::AddData(Local<Context> context, Local<T> object) {
0292   return AddData(context, internal::ValueHelper::ValueAsAddress(*object));
0293 }
0294
0295 template <class T>
0296 size_t SnapshotCreator::AddData(Local<T> object) {
0297   return AddData(internal::ValueHelper::ValueAsAddress(*object));
0298 }
0299
0300 }  // namespace v8
0301
0302 #endif  // INCLUDE_V8_SNAPSHOT_H_