v8-snapshot.h 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196
  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 be
  3. // found in the LICENSE file.
  4. #ifndef INCLUDE_V8_SNAPSHOT_H_
  5. #define INCLUDE_V8_SNAPSHOT_H_
  6. #include "v8-internal.h" // NOLINT(build/include_directory)
  7. #include "v8-local-handle.h" // NOLINT(build/include_directory)
  8. #include "v8config.h" // NOLINT(build/include_directory)
  9. namespace v8 {
  10. class Object;
  11. class V8_EXPORT StartupData {
  12. public:
  13. /**
  14. * Whether the data created can be rehashed and and the hash seed can be
  15. * recomputed when deserialized.
  16. * Only valid for StartupData returned by SnapshotCreator::CreateBlob().
  17. */
  18. bool CanBeRehashed() const;
  19. /**
  20. * Allows embedders to verify whether the data is valid for the current
  21. * V8 instance.
  22. */
  23. bool IsValid() const;
  24. const char* data;
  25. int raw_size;
  26. };
  27. /**
  28. * Callback and supporting data used in SnapshotCreator to implement embedder
  29. * logic to serialize internal fields.
  30. * Internal fields that directly reference V8 objects are serialized without
  31. * calling this callback. Internal fields that contain aligned pointers are
  32. * serialized by this callback if it returns non-zero result. Otherwise it is
  33. * serialized verbatim.
  34. */
  35. struct SerializeInternalFieldsCallback {
  36. using CallbackFunction = StartupData (*)(Local<Object> holder, int index,
  37. void* data);
  38. SerializeInternalFieldsCallback(CallbackFunction function = nullptr,
  39. void* data_arg = nullptr)
  40. : callback(function), data(data_arg) {}
  41. CallbackFunction callback;
  42. void* data;
  43. };
  44. // Note that these fields are called "internal fields" in the API and called
  45. // "embedder fields" within V8.
  46. using SerializeEmbedderFieldsCallback = SerializeInternalFieldsCallback;
  47. /**
  48. * Callback and supporting data used to implement embedder logic to deserialize
  49. * internal fields.
  50. */
  51. struct DeserializeInternalFieldsCallback {
  52. using CallbackFunction = void (*)(Local<Object> holder, int index,
  53. StartupData payload, void* data);
  54. DeserializeInternalFieldsCallback(CallbackFunction function = nullptr,
  55. void* data_arg = nullptr)
  56. : callback(function), data(data_arg) {}
  57. void (*callback)(Local<Object> holder, int index, StartupData payload,
  58. void* data);
  59. void* data;
  60. };
  61. using DeserializeEmbedderFieldsCallback = DeserializeInternalFieldsCallback;
  62. /**
  63. * Helper class to create a snapshot data blob.
  64. *
  65. * The Isolate used by a SnapshotCreator is owned by it, and will be entered
  66. * and exited by the constructor and destructor, respectively; The destructor
  67. * will also destroy the Isolate. Experimental language features, including
  68. * those available by default, are not available while creating a snapshot.
  69. */
  70. class V8_EXPORT SnapshotCreator {
  71. public:
  72. enum class FunctionCodeHandling { kClear, kKeep };
  73. /**
  74. * Initialize and enter an isolate, and set it up for serialization.
  75. * The isolate is either created from scratch or from an existing snapshot.
  76. * The caller keeps ownership of the argument snapshot.
  77. * \param existing_blob existing snapshot from which to create this one.
  78. * \param external_references a null-terminated array of external references
  79. * that must be equivalent to CreateParams::external_references.
  80. */
  81. SnapshotCreator(Isolate* isolate,
  82. const intptr_t* external_references = nullptr,
  83. StartupData* existing_blob = nullptr);
  84. /**
  85. * Create and enter an isolate, and set it up for serialization.
  86. * The isolate is either created from scratch or from an existing snapshot.
  87. * The caller keeps ownership of the argument snapshot.
  88. * \param existing_blob existing snapshot from which to create this one.
  89. * \param external_references a null-terminated array of external references
  90. * that must be equivalent to CreateParams::external_references.
  91. */
  92. SnapshotCreator(const intptr_t* external_references = nullptr,
  93. StartupData* existing_blob = nullptr);
  94. /**
  95. * Destroy the snapshot creator, and exit and dispose of the Isolate
  96. * associated with it.
  97. */
  98. ~SnapshotCreator();
  99. /**
  100. * \returns the isolate prepared by the snapshot creator.
  101. */
  102. Isolate* GetIsolate();
  103. /**
  104. * Set the default context to be included in the snapshot blob.
  105. * The snapshot will not contain the global proxy, and we expect one or a
  106. * global object template to create one, to be provided upon deserialization.
  107. *
  108. * \param callback optional callback to serialize internal fields.
  109. */
  110. void SetDefaultContext(Local<Context> context,
  111. SerializeInternalFieldsCallback callback =
  112. SerializeInternalFieldsCallback());
  113. /**
  114. * Add additional context to be included in the snapshot blob.
  115. * The snapshot will include the global proxy.
  116. *
  117. * \param callback optional callback to serialize internal fields.
  118. *
  119. * \returns the index of the context in the snapshot blob.
  120. */
  121. size_t AddContext(Local<Context> context,
  122. SerializeInternalFieldsCallback callback =
  123. SerializeInternalFieldsCallback());
  124. /**
  125. * Attach arbitrary V8::Data to the context snapshot, which can be retrieved
  126. * via Context::GetDataFromSnapshotOnce after deserialization. This data does
  127. * not survive when a new snapshot is created from an existing snapshot.
  128. * \returns the index for retrieval.
  129. */
  130. template <class T>
  131. V8_INLINE size_t AddData(Local<Context> context, Local<T> object);
  132. /**
  133. * Attach arbitrary V8::Data to the isolate snapshot, which can be retrieved
  134. * via Isolate::GetDataFromSnapshotOnce after deserialization. This data does
  135. * not survive when a new snapshot is created from an existing snapshot.
  136. * \returns the index for retrieval.
  137. */
  138. template <class T>
  139. V8_INLINE size_t AddData(Local<T> object);
  140. /**
  141. * Created a snapshot data blob.
  142. * This must not be called from within a handle scope.
  143. * \param function_code_handling whether to include compiled function code
  144. * in the snapshot.
  145. * \returns { nullptr, 0 } on failure, and a startup snapshot on success. The
  146. * caller acquires ownership of the data array in the return value.
  147. */
  148. StartupData CreateBlob(FunctionCodeHandling function_code_handling);
  149. // Disallow copying and assigning.
  150. SnapshotCreator(const SnapshotCreator&) = delete;
  151. void operator=(const SnapshotCreator&) = delete;
  152. private:
  153. size_t AddData(Local<Context> context, internal::Address object);
  154. size_t AddData(internal::Address object);
  155. void* data_;
  156. };
  157. template <class T>
  158. size_t SnapshotCreator::AddData(Local<Context> context, Local<T> object) {
  159. T* object_ptr = *object;
  160. internal::Address* p = reinterpret_cast<internal::Address*>(object_ptr);
  161. return AddData(context, *p);
  162. }
  163. template <class T>
  164. size_t SnapshotCreator::AddData(Local<T> object) {
  165. T* object_ptr = *object;
  166. internal::Address* p = reinterpret_cast<internal::Address*>(object_ptr);
  167. return AddData(*p);
  168. }
  169. } // namespace v8
  170. #endif // INCLUDE_V8_SNAPSHOT_H_