File Explorer

1// Copyright 2021 the V8 project authors. All rights reserved.2// Use of this source code is governed by a BSD-style license that can be3// found in the LICENSE file.4 5#ifndef INCLUDE_V8_SNAPSHOT_H_6#define INCLUDE_V8_SNAPSHOT_H_7 8#include "v8-internal.h"      // NOLINT(build/include_directory)9#include "v8-isolate.h"       // NOLINT(build/include_directory)10#include "v8-local-handle.h"  // NOLINT(build/include_directory)11#include "v8config.h"         // NOLINT(build/include_directory)12 13namespace v8 {14 15class Object;16 17namespace internal {18class SnapshotCreatorImpl;19}  // namespace internal20 21class V8_EXPORT StartupData {22 public:23  /**24   * Whether the data created can be rehashed and and the hash seed can be25   * recomputed when deserialized.26   * Only valid for StartupData returned by SnapshotCreator::CreateBlob().27   */28  bool CanBeRehashed() const;29  /**30   * Allows embedders to verify whether the data is valid for the current31   * V8 instance.32   */33  bool IsValid() const;34 35  const char* data;36  int raw_size;37};38 39/**40 * Callback and supporting data used in SnapshotCreator to implement embedder41 * logic to serialize internal fields of v8::Objects.42 * Internal fields that directly reference V8 objects are serialized without43 * calling this callback. Internal fields that contain aligned pointers are44 * serialized by this callback if it returns non-zero result. Otherwise it is45 * serialized verbatim.46 */47struct SerializeInternalFieldsCallback {48  using CallbackFunction = StartupData (*)(Local<Object> holder, int index,49                                           void* data);50  SerializeInternalFieldsCallback(CallbackFunction function = nullptr,51                                  void* data_arg = nullptr)52      : callback(function), data(data_arg) {}53  CallbackFunction callback;54  void* data;55};56 57/**58 * Similar to SerializeInternalFieldsCallback, but works with the embedder data59 * in a v8::Context.60 */61struct SerializeContextDataCallback {62  using CallbackFunction = StartupData (*)(Local<Context> holder, int index,63                                           void* data);64  SerializeContextDataCallback(CallbackFunction function = nullptr,65                               void* data_arg = nullptr)66      : callback(function), data(data_arg) {}67  CallbackFunction callback;68  void* data;69};70 71/**72 * Similar to `SerializeInternalFieldsCallback`, but is used exclusively to73 * serialize API wrappers. The pointers for API wrappers always point into the74 * CppHeap.75 */76struct SerializeAPIWrapperCallback {77  using CallbackFunction = StartupData (*)(Local<Object> holder,78                                           void* cpp_heap_pointer, void* data);79  explicit SerializeAPIWrapperCallback(CallbackFunction function = nullptr,80                                       void* data = nullptr)81      : callback(function), data(data) {}82 83  CallbackFunction callback;84  void* data;85};86 87/**88 * Callback and supporting data used to implement embedder logic to deserialize89 * internal fields of v8::Objects.90 */91struct DeserializeInternalFieldsCallback {92  using CallbackFunction = void (*)(Local<Object> holder, int index,93                                    StartupData payload, void* data);94  DeserializeInternalFieldsCallback(CallbackFunction function = nullptr,95                                    void* data_arg = nullptr)96      : callback(function), data(data_arg) {}97 98  CallbackFunction callback;99  void* data;100};101 102/**103 * Similar to DeserializeInternalFieldsCallback, but works with the embedder104 * data in a v8::Context.105 */106struct DeserializeContextDataCallback {107  using CallbackFunction = void (*)(Local<Context> holder, int index,108                                    StartupData payload, void* data);109  DeserializeContextDataCallback(CallbackFunction function = nullptr,110                                 void* data_arg = nullptr)111      : callback(function), data(data_arg) {}112  CallbackFunction callback;113  void* data;114};115 116struct DeserializeAPIWrapperCallback {117  using CallbackFunction = void (*)(Local<Object> holder, StartupData payload,118                                    void* data);119  explicit DeserializeAPIWrapperCallback(CallbackFunction function = nullptr,120                                         void* data = nullptr)121      : callback(function), data(data) {}122 123  CallbackFunction callback;124  void* data;125};126 127/**128 * Helper class to create a snapshot data blob.129 *130 * The Isolate used by a SnapshotCreator is owned by it, and will be entered131 * and exited by the constructor and destructor, respectively; The destructor132 * will also destroy the Isolate. Experimental language features, including133 * those available by default, are not available while creating a snapshot.134 */135class V8_EXPORT SnapshotCreator {136 public:137  enum class FunctionCodeHandling { kClear, kKeep };138 139  /**140   * Initialize and enter an isolate, and set it up for serialization.141   * The isolate is either created from scratch or from an existing snapshot.142   * The caller keeps ownership of the argument snapshot.143   * \param existing_blob existing snapshot from which to create this one.144   * \param external_references a null-terminated array of external references145   *        that must be equivalent to CreateParams::external_references.146   * \param owns_isolate whether this SnapshotCreator should call147   *        v8::Isolate::Dispose() during its destructor.148   */149  V8_DEPRECATE_SOON("Use the version that passes CreateParams instead.")150  explicit SnapshotCreator(Isolate* isolate,151                           const intptr_t* external_references = nullptr,152                           const StartupData* existing_blob = nullptr,153                           bool owns_isolate = true);154 155  /**156   * Create and enter an isolate, and set it up for serialization.157   * The isolate is either created from scratch or from an existing snapshot.158   * The caller keeps ownership of the argument snapshot.159   * \param existing_blob existing snapshot from which to create this one.160   * \param external_references a null-terminated array of external references161   *        that must be equivalent to CreateParams::external_references.162   */163  V8_DEPRECATE_SOON("Use the version that passes CreateParams instead.")164  explicit SnapshotCreator(const intptr_t* external_references = nullptr,165                           const StartupData* existing_blob = nullptr);166 167  /**168   * Creates an Isolate for serialization and enters it. The creator fully owns169   * the Isolate and will invoke `v8::Isolate::Dispose()` during destruction.170   *171   * \param params The parameters to initialize the Isolate for. Details:172   *               - `params.external_references` are expected to be a173   *                 null-terminated array of external references.174   *               - `params.existing_blob` is an optional snapshot blob from175   *                 which can be used to initialize the new blob.176   */177  explicit SnapshotCreator(const v8::Isolate::CreateParams& params);178 179  /**180   * Initializes an Isolate for serialization and enters it. The creator does181   * not own the Isolate but merely initialize it properly.182   *183   * \param isolate The isolate that was allocated by `Isolate::Allocate()~.184   * \param params The parameters to initialize the Isolate for. Details:185   *               - `params.external_references` are expected to be a186   *                 null-terminated array of external references.187   *               - `params.existing_blob` is an optional snapshot blob from188   *                 which can be used to initialize the new blob.189   */190  SnapshotCreator(v8::Isolate* isolate,191                  const v8::Isolate::CreateParams& params);192 193  /**194   * Destroy the snapshot creator, and exit and dispose of the Isolate195   * associated with it.196   */197  ~SnapshotCreator();198 199  /**200   * \returns the isolate prepared by the snapshot creator.201   */202  Isolate* GetIsolate();203 204  /**205   * Set the default context to be included in the snapshot blob.206   * The snapshot will not contain the global proxy, and we expect one or a207   * global object template to create one, to be provided upon deserialization.208   *209   * \param internal_fields_serializer An optional callback used to serialize210   * internal pointer fields set by211   * v8::Object::SetAlignedPointerInInternalField().212   *213   * \param context_data_serializer An optional callback used to serialize214   * context embedder data set by215   * v8::Context::SetAlignedPointerInEmbedderData().216   *217   * \param api_wrapper_serializer An optional callback used to serialize API218   * wrapper references set via `v8::Object::Wrap()`.219   */220  void SetDefaultContext(221      Local<Context> context,222      SerializeInternalFieldsCallback internal_fields_serializer =223          SerializeInternalFieldsCallback(),224      SerializeContextDataCallback context_data_serializer =225          SerializeContextDataCallback(),226      SerializeAPIWrapperCallback api_wrapper_serializer =227          SerializeAPIWrapperCallback());228 229  /**230   * Add additional context to be included in the snapshot blob.231   * The snapshot will include the global proxy.232   *233   * \param internal_fields_serializer Similar to internal_fields_serializer234   * in SetDefaultContext() but only applies to the context being added.235   *236   * \param context_data_serializer Similar to context_data_serializer237   * in SetDefaultContext() but only applies to the context being added.238   *239   * \param api_wrapper_serializer Similar to api_wrapper_serializer240   * in SetDefaultContext() but only applies to the context being added.241   */242  size_t AddContext(Local<Context> context,243                    SerializeInternalFieldsCallback internal_fields_serializer =244                        SerializeInternalFieldsCallback(),245                    SerializeContextDataCallback context_data_serializer =246                        SerializeContextDataCallback(),247                    SerializeAPIWrapperCallback api_wrapper_serializer =248                        SerializeAPIWrapperCallback());249 250  /**251   * Attach arbitrary V8::Data to the context snapshot, which can be retrieved252   * via Context::GetDataFromSnapshotOnce after deserialization. This data does253   * not survive when a new snapshot is created from an existing snapshot.254   * \returns the index for retrieval.255   */256  template <class T>257  V8_INLINE size_t AddData(Local<Context> context, Local<T> object);258 259  /**260   * Attach arbitrary V8::Data to the isolate snapshot, which can be retrieved261   * via Isolate::GetDataFromSnapshotOnce after deserialization. This data does262   * not survive when a new snapshot is created from an existing snapshot.263   * \returns the index for retrieval.264   */265  template <class T>266  V8_INLINE size_t AddData(Local<T> object);267 268  /**269   * Created a snapshot data blob.270   * This must not be called from within a handle scope.271   * \param function_code_handling whether to include compiled function code272   *        in the snapshot.273   * \returns { nullptr, 0 } on failure, and a startup snapshot on success. The274   *        caller acquires ownership of the data array in the return value.275   */276  StartupData CreateBlob(FunctionCodeHandling function_code_handling);277 278  // Disallow copying and assigning.279  SnapshotCreator(const SnapshotCreator&) = delete;280  void operator=(const SnapshotCreator&) = delete;281 282 private:283  size_t AddData(Local<Context> context, internal::Address object);284  size_t AddData(internal::Address object);285 286  internal::SnapshotCreatorImpl* impl_;287  friend class internal::SnapshotCreatorImpl;288};289 290template <class T>291size_t SnapshotCreator::AddData(Local<Context> context, Local<T> object) {292  return AddData(context, internal::ValueHelper::ValueAsAddress(*object));293}294 295template <class T>296size_t SnapshotCreator::AddData(Local<T> object) {297  return AddData(internal::ValueHelper::ValueAsAddress(*object));298}299 300}  // namespace v8301 302#endif  // INCLUDE_V8_SNAPSHOT_H_303