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  * Callback and supporting data used to implement embedder logic to deserialize
0073  * internal fields of v8::Objects.
0074  */
0075 struct DeserializeInternalFieldsCallback {
0076   using CallbackFunction = void (*)(Local<Object> holder, int index,
0077                                     StartupData payload, void* data);
0078   DeserializeInternalFieldsCallback(CallbackFunction function = nullptr,
0079                                     void* data_arg = nullptr)
0080       : callback(function), data(data_arg) {}
0081
0082   CallbackFunction callback;
0083   void* data;
0084 };
0085
0086 /**
0087  * Similar to DeserializeInternalFieldsCallback, but works with the embedder
0088  * data in a v8::Context.
0089  */
0090 struct DeserializeContextDataCallback {
0091   using CallbackFunction = void (*)(Local<Context> holder, int index,
0092                                     StartupData payload, void* data);
0093   DeserializeContextDataCallback(CallbackFunction function = nullptr,
0094                                  void* data_arg = nullptr)
0095       : callback(function), data(data_arg) {}
0096   CallbackFunction callback;
0097   void* data;
0098 };
0099
0100 /**
0101  * Helper class to create a snapshot data blob.
0102  *
0103  * The Isolate used by a SnapshotCreator is owned by it, and will be entered
0104  * and exited by the constructor and destructor, respectively; The destructor
0105  * will also destroy the Isolate. Experimental language features, including
0106  * those available by default, are not available while creating a snapshot.
0107  */
0108 class V8_EXPORT SnapshotCreator {
0109  public:
0110   enum class FunctionCodeHandling { kClear, kKeep };
0111
0112   /**
0113    * Initialize and enter an isolate, and set it up for serialization.
0114    * The isolate is either created from scratch or from an existing snapshot.
0115    * The caller keeps ownership of the argument snapshot.
0116    * \param existing_blob existing snapshot from which to create this one.
0117    * \param external_references a null-terminated array of external references
0118    *        that must be equivalent to CreateParams::external_references.
0119    * \param owns_isolate whether this SnapshotCreator should call
0120    *        v8::Isolate::Dispose() during its destructor.
0121    */
0122   V8_DEPRECATE_SOON("Use the version that passes CreateParams instead.")
0123   explicit SnapshotCreator(Isolate* isolate,
0124                            const intptr_t* external_references = nullptr,
0125                            const StartupData* existing_blob = nullptr,
0126                            bool owns_isolate = true);
0127
0128   /**
0129    * Create and enter an isolate, and set it up for serialization.
0130    * The isolate is either created from scratch or from an existing snapshot.
0131    * The caller keeps ownership of the argument snapshot.
0132    * \param existing_blob existing snapshot from which to create this one.
0133    * \param external_references a null-terminated array of external references
0134    *        that must be equivalent to CreateParams::external_references.
0135    */
0136   V8_DEPRECATE_SOON("Use the version that passes CreateParams instead.")
0137   explicit SnapshotCreator(const intptr_t* external_references = nullptr,
0138                            const StartupData* existing_blob = nullptr);
0139
0140   /**
0141    * Creates an Isolate for serialization and enters it. The creator fully owns
0142    * the Isolate and will invoke `v8::Isolate::Dispose()` during destruction.
0143    *
0144    * \param params The parameters to initialize the Isolate for. Details:
0145    *               - `params.external_references` are expected to be a
0146    *                 null-terminated array of external references.
0147    *               - `params.existing_blob` is an optional snapshot blob from
0148    *                 which can be used to initialize the new blob.
0149    */
0150   explicit SnapshotCreator(const v8::Isolate::CreateParams& params);
0151
0152   /**
0153    * Initializes an Isolate for serialization and enters it. The creator does
0154    * not own the Isolate but merely initialize it properly.
0155    *
0156    * \param isolate The isolate that was allocated by `Isolate::Allocate()~.
0157    * \param params The parameters to initialize the Isolate for. Details:
0158    *               - `params.external_references` are expected to be a
0159    *                 null-terminated array of external references.
0160    *               - `params.existing_blob` is an optional snapshot blob from
0161    *                 which can be used to initialize the new blob.
0162    */
0163   SnapshotCreator(v8::Isolate* isolate,
0164                   const v8::Isolate::CreateParams& params);
0165
0166   /**
0167    * Destroy the snapshot creator, and exit and dispose of the Isolate
0168    * associated with it.
0169    */
0170   ~SnapshotCreator();
0171
0172   /**
0173    * \returns the isolate prepared by the snapshot creator.
0174    */
0175   Isolate* GetIsolate();
0176
0177   /**
0178    * Set the default context to be included in the snapshot blob.
0179    * The snapshot will not contain the global proxy, and we expect one or a
0180    * global object template to create one, to be provided upon deserialization.
0181    *
0182    * \param internal_fields_serializer An optional callback used to serialize
0183    * internal pointer fields set by
0184    * v8::Object::SetAlignedPointerInInternalField().
0185    *
0186    * \param context_data_serializer An optional callback used to serialize
0187    * context embedder data set by
0188    * v8::Context::SetAlignedPointerInEmbedderData().
0189    *
0190    */
0191   void SetDefaultContext(
0192       Local<Context> context,
0193       SerializeInternalFieldsCallback internal_fields_serializer =
0194           SerializeInternalFieldsCallback(),
0195       SerializeContextDataCallback context_data_serializer =
0196           SerializeContextDataCallback());
0197
0198   /**
0199    * Add additional context to be included in the snapshot blob.
0200    * The snapshot will include the global proxy.
0201    *
0202    * \param internal_fields_serializer Similar to internal_fields_serializer
0203    * in SetDefaultContext() but only applies to the context being added.
0204    *
0205    * \param context_data_serializer Similar to context_data_serializer
0206    * in SetDefaultContext() but only applies to the context being added.
0207    */
0208   size_t AddContext(Local<Context> context,
0209                     SerializeInternalFieldsCallback internal_fields_serializer =
0210                         SerializeInternalFieldsCallback(),
0211                     SerializeContextDataCallback context_data_serializer =
0212                         SerializeContextDataCallback());
0213
0214   /**
0215    * Attach arbitrary V8::Data to the context snapshot, which can be retrieved
0216    * via Context::GetDataFromSnapshotOnce after deserialization. This data does
0217    * not survive when a new snapshot is created from an existing snapshot.
0218    * \returns the index for retrieval.
0219    */
0220   template <class T>
0221   V8_INLINE size_t AddData(Local<Context> context, Local<T> object);
0222
0223   /**
0224    * Attach arbitrary V8::Data to the isolate snapshot, which can be retrieved
0225    * via Isolate::GetDataFromSnapshotOnce after deserialization. This data does
0226    * not survive when a new snapshot is created from an existing snapshot.
0227    * \returns the index for retrieval.
0228    */
0229   template <class T>
0230   V8_INLINE size_t AddData(Local<T> object);
0231
0232   /**
0233    * Created a snapshot data blob.
0234    * This must not be called from within a handle scope.
0235    * \param function_code_handling whether to include compiled function code
0236    *        in the snapshot.
0237    * \returns { nullptr, 0 } on failure, and a startup snapshot on success. The
0238    *        caller acquires ownership of the data array in the return value.
0239    */
0240   StartupData CreateBlob(FunctionCodeHandling function_code_handling);
0241
0242   // Disallow copying and assigning.
0243   SnapshotCreator(const SnapshotCreator&) = delete;
0244   void operator=(const SnapshotCreator&) = delete;
0245
0246  private:
0247   size_t AddData(Local<Context> context, internal::Address object);
0248   size_t AddData(internal::Address object);
0249
0250   internal::SnapshotCreatorImpl* impl_;
0251   friend class internal::SnapshotCreatorImpl;
0252 };
0253
0254 template <class T>
0255 size_t SnapshotCreator::AddData(Local<Context> context, Local<T> object) {
0256   return AddData(context, internal::ValueHelper::ValueAsAddress(*object));
0257 }
0258
0259 template <class T>
0260 size_t SnapshotCreator::AddData(Local<T> object) {
0261   return AddData(internal::ValueHelper::ValueAsAddress(*object));
0262 }
0263
0264 }  // namespace v8
0265
0266 #endif  // INCLUDE_V8_SNAPSHOT_H_