123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196 |
- // Copyright 2021 the V8 project authors. All rights reserved.
- // Use of this source code is governed by a BSD-style license that can be
- // found in the LICENSE file.
- #ifndef INCLUDE_V8_SNAPSHOT_H_
- #define INCLUDE_V8_SNAPSHOT_H_
- #include "v8-internal.h" // NOLINT(build/include_directory)
- #include "v8-local-handle.h" // NOLINT(build/include_directory)
- #include "v8config.h" // NOLINT(build/include_directory)
- namespace v8 {
- class Object;
- class V8_EXPORT StartupData {
- public:
- /**
- * Whether the data created can be rehashed and and the hash seed can be
- * recomputed when deserialized.
- * Only valid for StartupData returned by SnapshotCreator::CreateBlob().
- */
- bool CanBeRehashed() const;
- /**
- * Allows embedders to verify whether the data is valid for the current
- * V8 instance.
- */
- bool IsValid() const;
- const char* data;
- int raw_size;
- };
- /**
- * Callback and supporting data used in SnapshotCreator to implement embedder
- * logic to serialize internal fields.
- * Internal fields that directly reference V8 objects are serialized without
- * calling this callback. Internal fields that contain aligned pointers are
- * serialized by this callback if it returns non-zero result. Otherwise it is
- * serialized verbatim.
- */
- struct SerializeInternalFieldsCallback {
- using CallbackFunction = StartupData (*)(Local<Object> holder, int index,
- void* data);
- SerializeInternalFieldsCallback(CallbackFunction function = nullptr,
- void* data_arg = nullptr)
- : callback(function), data(data_arg) {}
- CallbackFunction callback;
- void* data;
- };
- // Note that these fields are called "internal fields" in the API and called
- // "embedder fields" within V8.
- using SerializeEmbedderFieldsCallback = SerializeInternalFieldsCallback;
- /**
- * Callback and supporting data used to implement embedder logic to deserialize
- * internal fields.
- */
- struct DeserializeInternalFieldsCallback {
- using CallbackFunction = void (*)(Local<Object> holder, int index,
- StartupData payload, void* data);
- DeserializeInternalFieldsCallback(CallbackFunction function = nullptr,
- void* data_arg = nullptr)
- : callback(function), data(data_arg) {}
- void (*callback)(Local<Object> holder, int index, StartupData payload,
- void* data);
- void* data;
- };
- using DeserializeEmbedderFieldsCallback = DeserializeInternalFieldsCallback;
- /**
- * Helper class to create a snapshot data blob.
- *
- * The Isolate used by a SnapshotCreator is owned by it, and will be entered
- * and exited by the constructor and destructor, respectively; The destructor
- * will also destroy the Isolate. Experimental language features, including
- * those available by default, are not available while creating a snapshot.
- */
- class V8_EXPORT SnapshotCreator {
- public:
- enum class FunctionCodeHandling { kClear, kKeep };
- /**
- * Initialize and enter an isolate, and set it up for serialization.
- * The isolate is either created from scratch or from an existing snapshot.
- * The caller keeps ownership of the argument snapshot.
- * \param existing_blob existing snapshot from which to create this one.
- * \param external_references a null-terminated array of external references
- * that must be equivalent to CreateParams::external_references.
- */
- SnapshotCreator(Isolate* isolate,
- const intptr_t* external_references = nullptr,
- StartupData* existing_blob = nullptr);
- /**
- * Create and enter an isolate, and set it up for serialization.
- * The isolate is either created from scratch or from an existing snapshot.
- * The caller keeps ownership of the argument snapshot.
- * \param existing_blob existing snapshot from which to create this one.
- * \param external_references a null-terminated array of external references
- * that must be equivalent to CreateParams::external_references.
- */
- SnapshotCreator(const intptr_t* external_references = nullptr,
- StartupData* existing_blob = nullptr);
- /**
- * Destroy the snapshot creator, and exit and dispose of the Isolate
- * associated with it.
- */
- ~SnapshotCreator();
- /**
- * \returns the isolate prepared by the snapshot creator.
- */
- Isolate* GetIsolate();
- /**
- * Set the default context to be included in the snapshot blob.
- * The snapshot will not contain the global proxy, and we expect one or a
- * global object template to create one, to be provided upon deserialization.
- *
- * \param callback optional callback to serialize internal fields.
- */
- void SetDefaultContext(Local<Context> context,
- SerializeInternalFieldsCallback callback =
- SerializeInternalFieldsCallback());
- /**
- * Add additional context to be included in the snapshot blob.
- * The snapshot will include the global proxy.
- *
- * \param callback optional callback to serialize internal fields.
- *
- * \returns the index of the context in the snapshot blob.
- */
- size_t AddContext(Local<Context> context,
- SerializeInternalFieldsCallback callback =
- SerializeInternalFieldsCallback());
- /**
- * Attach arbitrary V8::Data to the context snapshot, which can be retrieved
- * via Context::GetDataFromSnapshotOnce after deserialization. This data does
- * not survive when a new snapshot is created from an existing snapshot.
- * \returns the index for retrieval.
- */
- template <class T>
- V8_INLINE size_t AddData(Local<Context> context, Local<T> object);
- /**
- * Attach arbitrary V8::Data to the isolate snapshot, which can be retrieved
- * via Isolate::GetDataFromSnapshotOnce after deserialization. This data does
- * not survive when a new snapshot is created from an existing snapshot.
- * \returns the index for retrieval.
- */
- template <class T>
- V8_INLINE size_t AddData(Local<T> object);
- /**
- * Created a snapshot data blob.
- * This must not be called from within a handle scope.
- * \param function_code_handling whether to include compiled function code
- * in the snapshot.
- * \returns { nullptr, 0 } on failure, and a startup snapshot on success. The
- * caller acquires ownership of the data array in the return value.
- */
- StartupData CreateBlob(FunctionCodeHandling function_code_handling);
- // Disallow copying and assigning.
- SnapshotCreator(const SnapshotCreator&) = delete;
- void operator=(const SnapshotCreator&) = delete;
- private:
- size_t AddData(Local<Context> context, internal::Address object);
- size_t AddData(internal::Address object);
- void* data_;
- };
- template <class T>
- size_t SnapshotCreator::AddData(Local<Context> context, Local<T> object) {
- T* object_ptr = *object;
- internal::Address* p = reinterpret_cast<internal::Address*>(object_ptr);
- return AddData(context, *p);
- }
- template <class T>
- size_t SnapshotCreator::AddData(Local<T> object) {
- T* object_ptr = *object;
- internal::Address* p = reinterpret_cast<internal::Address*>(object_ptr);
- return AddData(*p);
- }
- } // namespace v8
- #endif // INCLUDE_V8_SNAPSHOT_H_
|