AuroraMiddleware/v8
1
0
Fork 0
Code Issues 2 Pull Requests Releases Wiki Activity

[api] Improve documentation for API handle types.

Browse Source 
Add a few explanations to the documentation several methods and classes,
in particular Local, MaybeLocal, the HandleScopes.

Drive-by-fix: turn a few regular comments into documentation comments.

BUG=

Review-Url: https://codereview.chromium.org/2783843002
Cr-Commit-Position: refs/heads/master@{#44243}
This commit is contained in:
addaleax 2017-03-29 11:50:44 -07:00 committed by Commit bot
parent 891bbe2c85
commit a63744d50d
1 changed files with 150 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
include/v8.h
View File

@ -158,7 +158,6 @@ class GlobalHandles;
*(static_cast<T* volatile*>(0)) = static_cast<S*>(0); \
}
/**
* An object reference managed by the v8 garbage collector.
*
@ -172,10 +171,16 @@ class GlobalHandles;
* allocated on the heap.
*
* There are two types of handles: local and persistent handles.
*
* Local handles are light-weight and transient and typically used in
* local operations. They are managed by HandleScopes. Persistent
* handles can be used when storing objects across several independent
* operations and have to be explicitly deallocated when they're no
* local operations. They are managed by HandleScopes. That means that a
* HandleScope must exist on the stack when they are created and that they are
* only valid inside of the HandleScope active during their creation.
* For passing a local handle to an outer HandleScope, an EscapableHandleScope
* and its Escape() method must be used.
*
* Persistent handles can be used when storing objects across several
* independent operations and have to be explicitly deallocated when they're no
* longer used.
*
* It is safe to extract the object stored in the handle by
@ -253,6 +258,11 @@ class Local {
return !operator==(that);
}
/**
* Cast a handle to a subclass, e.g. Local<Value> to Local<Object>.
* This is only valid if the handle actually refers to a value of the
* target type.
*/
template <class S> V8_INLINE static Local<T> Cast(Local<S> that) {
#ifdef V8_ENABLE_CHECKS
// If we're going to perform the type check then we have to check
@ -262,6 +272,11 @@ class Local {
return Local<T>(T::Cast(*that));
}
/**
* Calling this is equivalent to Local<S>::Cast().
* In particular, this is only valid if the handle actually refers to a value
* of the target type.
*/
template <class S>
V8_INLINE Local<S> As() const {
return Local<S>::Cast(*this);
@ -338,15 +353,26 @@ class MaybeLocal {
V8_INLINE bool IsEmpty() const { return val_ == nullptr; }
/**
* Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
* |false| is returned and |out| is left untouched.
*/
template <class S>
V8_WARN_UNUSED_RESULT V8_INLINE bool ToLocal(Local<S>* out) const {
out->val_ = IsEmpty() ? nullptr : this->val_;
return !IsEmpty();
}
// Will crash if the MaybeLocal<> is empty.
/**
* Converts this MaybeLocal<> to a Local<>. If this MaybeLocal<> is empty,
* V8 will crash the process.
*/
V8_INLINE Local<T> ToLocalChecked();
/**
* Converts this MaybeLocal<> to a Local<>, using a default value if this
* MaybeLocal<> is empty.
*/
template <class S>
V8_INLINE Local<S> FromMaybe(Local<S> default_value) const {
return IsEmpty() ? default_value : Local<S>(val_);
@ -356,8 +382,10 @@ class MaybeLocal {
T* val_;
};
// Eternal handles are set-once handles that live for the life of the isolate.
/**
* Eternal handles are set-once handles that live for the lifetime of the
* isolate.
*/
template <class T> class Eternal {
public:
V8_INLINE Eternal() : val_(nullptr) {}
@ -437,10 +465,10 @@ enum class WeakCallbackType { kParameter, kInternalFields, kFinalizer };
* An object reference that is independent of any handle scope. Where
* a Local handle only lives as long as the HandleScope in which it was
* allocated, a PersistentBase handle remains valid until it is explicitly
* disposed.
* disposed using Reset().
*
* A persistent handle contains a reference to a storage cell within
* the v8 engine which holds an object value and which is updated by
* the V8 engine which holds an object value and which is updated by
* the garbage collector whenever the object is moved. A new storage
* cell can be created using the constructor or PersistentBase::Reset and
* existing handles can be disposed using PersistentBase::Reset.
@ -898,6 +926,11 @@ class V8_EXPORT EscapableHandleScope : public HandleScope {
internal::Object** escape_slot_;
};
/**
* A SealHandleScope acts like a handle scope in which no handle allocations
* are allowed. It can be useful for debugging handle leaks.
* Handles can be allocated within inner normal HandleScopes.
*/
class V8_EXPORT SealHandleScope {
public:
SealHandleScope(Isolate* isolate);
@ -1362,7 +1395,7 @@ class V8_EXPORT ScriptCompiler {
* CachedData instance is still valid; the tag has no other meaing.
*
* Background: The data carried by CachedData may depend on the exact
* V8 version number or currently compiler flags. This means when
* V8 version number or current compiler flags. This means that when
* persisting CachedData, the embedder must take care to not pass in
* data from another V8 version, or the same version with different
* features enabled.
@ -1682,21 +1715,21 @@ class V8_EXPORT ValueSerializer {
public:
virtual ~Delegate() {}
/*
/**
* Handles the case where a DataCloneError would be thrown in the structured
* clone spec. Other V8 embedders may throw some other appropriate exception
* type.
*/
virtual void ThrowDataCloneError(Local<String> message) = 0;
/*
/**
* The embedder overrides this method to write some kind of host object, if
* possible. If not, a suitable exception should be thrown and
* Nothing<bool>() returned.
*/
virtual Maybe<bool> WriteHostObject(Isolate* isolate, Local<Object> object);
/*
/**
* Called when the ValueSerializer is going to serialize a
* SharedArrayBuffer object. The embedder must return an ID for the
* object, using the same ID if this SharedArrayBuffer has already been
@ -1711,7 +1744,7 @@ class V8_EXPORT ValueSerializer {
virtual Maybe<uint32_t> GetWasmModuleTransferId(
Isolate* isolate, Local<WasmCompiledModule> module);
/*
/**
* Allocates memory for the buffer of at least the size provided. The actual
* size (which may be greater or equal) is written to |actual_size|. If no
* buffer has been allocated yet, nullptr will be provided.
@ -1723,7 +1756,7 @@ class V8_EXPORT ValueSerializer {
virtual void* ReallocateBufferMemory(void* old_buffer, size_t size,
size_t* actual_size);
/*
/**
* Frees a buffer allocated with |ReallocateBufferMemory|.
*/
virtual void FreeBufferMemory(void* buffer);
@ -1733,24 +1766,24 @@ class V8_EXPORT ValueSerializer {
ValueSerializer(Isolate* isolate, Delegate* delegate);
~ValueSerializer();
/*
/**
* Writes out a header, which includes the format version.
*/
void WriteHeader();
/*
/**
* Serializes a JavaScript value into the buffer.
*/
V8_WARN_UNUSED_RESULT Maybe<bool> WriteValue(Local<Context> context,
Local<Value> value);
/*
/**
* Returns the stored data. This serializer should not be used once the buffer
* is released. The contents are undefined if a previous write has failed.
*/
V8_DEPRECATE_SOON("Use Release()", std::vector<uint8_t> ReleaseBuffer());
/*
/**
* Returns the stored data (allocated using the delegate's
* AllocateBufferMemory) and its size. This serializer should not be used once
* the buffer is released. The contents are undefined if a previous write has
@ -1758,7 +1791,7 @@ class V8_EXPORT ValueSerializer {
*/
V8_WARN_UNUSED_RESULT std::pair<uint8_t*, size_t> Release();
/*
/**
* Marks an ArrayBuffer as havings its contents transferred out of band.
* Pass the corresponding ArrayBuffer in the deserializing context to
* ValueDeserializer::TransferArrayBuffer.
@ -1766,7 +1799,7 @@ class V8_EXPORT ValueSerializer {
void TransferArrayBuffer(uint32_t transfer_id,
Local<ArrayBuffer> array_buffer);
/*
/**
* Similar to TransferArrayBuffer, but for SharedArrayBuffer.
*/
V8_DEPRECATE_SOON("Use Delegate::GetSharedArrayBufferId",
@ -1774,7 +1807,7 @@ class V8_EXPORT ValueSerializer {
uint32_t transfer_id,
Local<SharedArrayBuffer> shared_array_buffer));
/*
/**
* Indicate whether to treat ArrayBufferView objects as host objects,
* i.e. pass them to Delegate::WriteHostObject. This should not be
* called when no Delegate was passed.
@ -1783,7 +1816,7 @@ class V8_EXPORT ValueSerializer {
*/
void SetTreatArrayBufferViewsAsHostObjects(bool mode);
/*
/**
* Write raw data in various common formats to the buffer.
* Note that integer types are written in base-128 varint format, not with a
* binary copy. For use during an override of Delegate::WriteHostObject.
@ -1815,14 +1848,14 @@ class V8_EXPORT ValueDeserializer {
public:
virtual ~Delegate() {}
/*
/**
* The embedder overrides this method to read some kind of host object, if
* possible. If not, a suitable exception should be thrown and
* MaybeLocal<Object>() returned.
*/
virtual MaybeLocal<Object> ReadHostObject(Isolate* isolate);
/*
/**
* Get a WasmCompiledModule given a transfer_id previously provided
* by ValueSerializer::GetWasmModuleTransferId
*/
@ -1835,25 +1868,25 @@ class V8_EXPORT ValueDeserializer {
Delegate* delegate);
~ValueDeserializer();
/*
/**
* Reads and validates a header (including the format version).
* May, for example, reject an invalid or unsupported wire format.
*/
V8_WARN_UNUSED_RESULT Maybe<bool> ReadHeader(Local<Context> context);
/*
/**
* Deserializes a JavaScript value from the buffer.
*/
V8_WARN_UNUSED_RESULT MaybeLocal<Value> ReadValue(Local<Context> context);
/*
/**
* Accepts the array buffer corresponding to the one passed previously to
* ValueSerializer::TransferArrayBuffer.
*/
void TransferArrayBuffer(uint32_t transfer_id,
Local<ArrayBuffer> array_buffer);
/*
/**
* Similar to TransferArrayBuffer, but for SharedArrayBuffer.
* The id is not necessarily in the same namespace as unshared ArrayBuffer
* objects.
@ -1861,7 +1894,7 @@ class V8_EXPORT ValueDeserializer {
void TransferSharedArrayBuffer(uint32_t id,
Local<SharedArrayBuffer> shared_array_buffer);
/*
/**
* Must be called before ReadHeader to enable support for reading the legacy
* wire format (i.e., which predates this being shipped).
*
@ -1870,19 +1903,19 @@ class V8_EXPORT ValueDeserializer {
*/
void SetSupportsLegacyWireFormat(bool supports_legacy_wire_format);
/*
/**
* Expect inline wasm in the data stream (rather than in-memory transfer)
*/
void SetExpectInlineWasm(bool allow_inline_wasm);
/*
/**
* Reads the underlying wire format version. Likely mostly to be useful to
* legacy code reading old wire format versions. Must be called after
* ReadHeader.
*/
uint32_t GetWireFormatVersion() const;
/*
/**
* Reads raw data in various common formats to the buffer.
* Note that integer types are read in base-128 varint format, not with a
* binary copy. For use during an override of Delegate::ReadHostObject.
@ -2307,9 +2340,25 @@ class V8_EXPORT Name : public Primitive {
static void CheckCast(Value* obj);
};
/**
* A flag describing different modes of string creation.
*
* Aside from performance implications there are no differences between the two
* creation modes.
*/
enum class NewStringType {
/**
* Create a new string, always allocating new storage memory.
*/
kNormal,
enum class NewStringType { kNormal, kInternalized };
/**
* Acts as a hint that the string should be created in the
* old generation heap space and be deduplicated if an identical string
* already exists.
*/
kInternalized
};
/**
* A JavaScript string value (ECMA-262, 4.3.17).
@ -2324,7 +2373,7 @@ class V8_EXPORT String : public Name {
ONE_BYTE_ENCODING = 0x8
};
/**
* Returns the number of characters in this string.
* Returns the number of characters (UTF-16 code units) in this string.
*/
int Length() const;
@ -2335,14 +2384,16 @@ class V8_EXPORT String : public Name {
int Utf8Length() const;
/**
* Returns whether this string is known to contain only one byte data.
* Returns whether this string is known to contain only one byte data,
* i.e. ISO-8859-1 code points.
* Does not read the string.
* False negatives are possible.
*/
bool IsOneByte() const;
/**
* Returns whether this string contain only one byte data.
* Returns whether this string contain only one byte data,
* i.e. ISO-8859-1 code points.
* Will read the entire string in some cases.
*/
bool ContainsOnlyOneByte() const;
@ -2649,7 +2700,7 @@ class V8_EXPORT String : public Name {
};
/**
* Converts an object to a two-byte string.
* Converts an object to a two-byte (UTF-16-encoded) string.
* If conversion to a string fails (eg. due to an exception in the toString()
* method of the object) then the length() method returns 0 and the * operator
* returns NULL.
@ -2684,22 +2735,30 @@ class V8_EXPORT String : public Name {
*/
class V8_EXPORT Symbol : public Name {
public:
// Returns the print name string of the symbol, or undefined if none.
/**
* Returns the print name string of the symbol, or undefined if none.
*/
Local<Value> Name() const;
// Create a symbol. If name is not empty, it will be used as the description.
/**
* Create a symbol. If name is not empty, it will be used as the description.
*/
static Local<Symbol> New(Isolate* isolate,
Local<String> name = Local<String>());
// Access global symbol registry.
// Note that symbols created this way are never collected, so
// they should only be used for statically fixed properties.
// Also, there is only one global name space for the names used as keys.
// To minimize the potential for clashes, use qualified names as keys.
/**
* Access global symbol registry.
* Note that symbols created this way are never collected, so
* they should only be used for statically fixed properties.
* Also, there is only one global name space for the names used as keys.
* To minimize the potential for clashes, use qualified names as keys.
*/
static Local<Symbol> For(Isolate *isolate, Local<String> name);
// Retrieve a global symbol. Similar to |For|, but using a separate
// registry that is not accessible by (and cannot clash with) JavaScript code.
/**
* Retrieve a global symbol. Similar to |For|, but using a separate
* registry that is not accessible by (and cannot clash with) JavaScript code.
*/
static Local<Symbol> ForApi(Isolate *isolate, Local<String> name);
// Well-known symbols
@ -2724,20 +2783,26 @@ class V8_EXPORT Symbol : public Name {
*/
class V8_EXPORT Private : public Data {
public:
// Returns the print name string of the private symbol, or undefined if none.
/**
* Returns the print name string of the private symbol, or undefined if none.
*/
Local<Value> Name() const;
// Create a private symbol. If name is not empty, it will be the description.
/**
* Create a private symbol. If name is not empty, it will be the description.
*/
static Local<Private> New(Isolate* isolate,
Local<String> name = Local<String>());
// Retrieve a global private symbol. If a symbol with this name has not
// been retrieved in the same isolate before, it is created.
// Note that private symbols created this way are never collected, so
// they should only be used for statically fixed properties.
// Also, there is only one global name space for the names used as keys.
// To minimize the potential for clashes, use qualified names as keys,
// e.g., "Class#property".
/**
* Retrieve a global private symbol. If a symbol with this name has not
* been retrieved in the same isolate before, it is created.
* Note that private symbols created this way are never collected, so
* they should only be used for statically fixed properties.
* Also, there is only one global name space for the names used as keys.
* To minimize the potential for clashes, use qualified names as keys,
* e.g., "Class#property".
*/
static Local<Private> ForApi(Isolate* isolate, Local<String> name);
private:
@ -4062,7 +4127,8 @@ class V8_EXPORT ArrayBuffer : public Object {
/**
* malloc/free based convenience allocator.
*
* Caller takes ownership.
* Caller takes ownership, i.e. the returned object needs to be freed using
* |delete allocator| once it is no longer in use.
*/
static Allocator* NewDefaultAllocator();
};
@ -4106,8 +4172,11 @@ class V8_EXPORT ArrayBuffer : public Object {
/**
* Create a new ArrayBuffer over an existing memory block.
* The created array buffer is by default immediately in externalized state.
* The memory block will not be reclaimed when a created ArrayBuffer
* is garbage-collected.
* In externalized state, the memory block will not be reclaimed when a
* created ArrayBuffer is garbage-collected.
* In internalized state, the memory block will be released using
* |Allocator::Free| once all ArrayBuffers referencing it are collected by
* the garbage collector.
*/
static Local<ArrayBuffer> New(
Isolate* isolate, void* data, size_t byte_length,
@ -6056,6 +6125,12 @@ class V8_EXPORT HeapStatistics {
size_t heap_size_limit() { return heap_size_limit_; }
size_t malloced_memory() { return malloced_memory_; }
size_t peak_malloced_memory() { return peak_malloced_memory_; }
/**
* Returns a 0/1 boolean, which signifies whether the |--zap_code_space|
* option is enabled or not, which makes V8 overwrite heap garbage with a bit
* pattern.
*/
size_t does_zap_garbage() { return does_zap_garbage_; }
private:
@ -7846,20 +7921,33 @@ class Maybe {
V8_INLINE bool IsNothing() const { return !has_value_; }
V8_INLINE bool IsJust() const { return has_value_; }
// Will crash if the Maybe<> is nothing.
/**
* An alias for |FromJust|. Will crash if the Maybe<> is nothing.
*/
V8_INLINE T ToChecked() const { return FromJust(); }
/**
* Converts this Maybe<> to a value of type T. If this Maybe<> is
* nothing (empty), |false| is returned and |out| is left untouched.
*/
V8_WARN_UNUSED_RESULT V8_INLINE bool To(T* out) const {
if (V8_LIKELY(IsJust())) *out = value_;
return IsJust();
}
// Will crash if the Maybe<> is nothing.
/**
* Converts this Maybe<> to a value of type T. If this Maybe<> is
* nothing (empty), V8 will crash the process.
*/
V8_INLINE T FromJust() const {
if (V8_UNLIKELY(!IsJust())) V8::FromJustIsNothing();
return value_;
}
/**
* Converts this Maybe<> to a value of type T, using a default value if this
* Maybe<> is nothing (empty).
*/
V8_INLINE T FromMaybe(const T& default_value) const {
return has_value_ ? value_ : default_value;
}