Viewing file:  v8-array-buffer.h (21.49 KB) -rw-r--r--
Select action/file-type:
 (+) |  (+) |  (+) | Code (+) | Session (+) |  (+) | SDB (+) |  (+) |  (+) |  (+) |  (+) |  (+) |
// 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_ARRAY_BUFFER_H_
#define INCLUDE_V8_ARRAY_BUFFER_H_
#include <stddef.h>
#include <memory>
#include "v8-local-handle.h" // NOLINT(build/include_directory)
#include "v8-memory-span.h" // NOLINT(build/include_directory)
#include "v8-object.h" // NOLINT(build/include_directory)
#include "v8-platform.h" // NOLINT(build/include_directory)
#include "v8config.h" // NOLINT(build/include_directory)
namespace v8 {
class SharedArrayBuffer;
#if defined(V8_COMPRESS_POINTERS) && \
!defined(V8_COMPRESS_POINTERS_IN_SHARED_CAGE)
class IsolateGroup;
#endif
#ifndef V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT
// Defined using gn arg `v8_array_buffer_internal_field_count`.
#define V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT 2
#endif
enum class ArrayBufferCreationMode { kInternalized, kExternalized };
enum class BackingStoreInitializationMode { kZeroInitialized, kUninitialized };
enum class BackingStoreOnFailureMode { kReturnNull, kOutOfMemory };
/**
* A wrapper around the backing store (i.e. the raw memory) of an array buffer.
* See a document linked in http://crbug.com/v8/9908 for more information.
*
* The allocation and destruction of backing stores is generally managed by
* V8. Clients should always use standard C++ memory ownership types (i.e.
* std::unique_ptr and std::shared_ptr) to manage lifetimes of backing stores
* properly, since V8 internal objects may alias backing stores.
*
* This object does not keep the underlying |ArrayBuffer::Allocator| alive by
* default. Use Isolate::CreateParams::array_buffer_allocator_shared when
* creating the Isolate to make it hold a reference to the allocator itself.
*/
class V8_EXPORT BackingStore : public v8::internal::BackingStoreBase {
public:
~BackingStore();
/**
* Return a pointer to the beginning of the memory block for this backing
* store. The pointer is only valid as long as this backing store object
* lives.
*/
void* Data() const;
/**
* The length (in bytes) of this backing store.
*/
size_t ByteLength() const;
/**
* The maximum length (in bytes) that this backing store may grow to.
*
* If this backing store was created for a resizable ArrayBuffer or a growable
* SharedArrayBuffer, it is >= ByteLength(). Otherwise it is ==
* ByteLength().
*/
size_t MaxByteLength() const;
/**
* Indicates whether the backing store was created for an ArrayBuffer or
* a SharedArrayBuffer.
*/
bool IsShared() const;
/**
* Indicates whether the backing store was created for a resizable ArrayBuffer
* or a growable SharedArrayBuffer, and thus may be resized by user JavaScript
* code.
*/
bool IsResizableByUserJavaScript() const;
/**
* Prevent implicit instantiation of operator delete with size_t argument.
* The size_t argument would be incorrect because ptr points to the
* internal BackingStore object.
*/
void operator delete(void* ptr) { ::operator delete(ptr); }
/**
* This callback is used only if the memory block for a BackingStore cannot be
* allocated with an ArrayBuffer::Allocator. In such cases the destructor of
* the BackingStore invokes the callback to free the memory block.
*/
using DeleterCallback = void (*)(void* data, size_t length,
void* deleter_data);
/**
* If the memory block of a BackingStore is static or is managed manually,
* then this empty deleter along with nullptr deleter_data can be passed to
* ArrayBuffer::NewBackingStore to indicate that.
*
* The manually managed case should be used with caution and only when it
* is guaranteed that the memory block freeing happens after detaching its
* ArrayBuffer.
*/
static void EmptyDeleter(void* data, size_t length, void* deleter_data);
private:
/**
* See [Shared]ArrayBuffer::GetBackingStore and
* [Shared]ArrayBuffer::NewBackingStore.
*/
BackingStore();
};
#if !defined(V8_IMMINENT_DEPRECATION_WARNINGS)
// Use v8::BackingStore::DeleterCallback instead.
using BackingStoreDeleterCallback = void (*)(void* data, size_t length,
void* deleter_data);
#endif
/**
* An instance of the built-in ArrayBuffer constructor (ES6 draft 15.13.5).
*/
class V8_EXPORT ArrayBuffer : public Object {
public:
/**
* A thread-safe allocator that V8 uses to allocate |ArrayBuffer|'s memory.
* The allocator is a global V8 setting. It has to be set via
* Isolate::CreateParams.
*
* Memory allocated through this allocator by V8 is accounted for as external
* memory by V8. Note that V8 keeps track of the memory for all internalized
* |ArrayBuffer|s. Responsibility for tracking external memory (using
* Isolate::AdjustAmountOfExternalAllocatedMemory) is handed over to the
* embedder upon externalization and taken over upon internalization (creating
* an internalized buffer from an existing buffer).
*
* Note that it is unsafe to call back into V8 from any of the allocator
* functions.
*/
class V8_EXPORT Allocator {
public:
virtual ~Allocator() = default;
/**
* Allocate |length| bytes. Return nullptr if allocation is not successful.
* Memory should be initialized to zeroes.
*/
virtual void* Allocate(size_t length) = 0;
/**
* Allocate |length| bytes. Return nullptr if allocation is not successful.
* Memory does not have to be initialized.
*/
virtual void* AllocateUninitialized(size_t length) = 0;
/**
* Free the memory block of size |length|, pointed to by |data|.
* That memory is guaranteed to be previously allocated by |Allocate|.
*/
virtual void Free(void* data, size_t length) = 0;
/**
* Returns a size_t that determines the largest ArrayBuffer that can be
* allocated. Override if your Allocator is more restrictive than the
* default. Will only be called once, and the value returned will be
* cached.
* Should not return a value that is larger than kMaxByteLength.
*/
virtual size_t MaxAllocationSize() const { return kMaxByteLength; }
/**
* ArrayBuffer allocation mode. kNormal is a malloc/free style allocation,
* while kReservation is for larger allocations with the ability to set
* access permissions.
*/
enum class AllocationMode { kNormal, kReservation };
/**
* Returns page allocator used by this Allocator instance.
*
* When the sandbox used by Allocator it is expected that this returns
* sandbox's page allocator.
* Otherwise, it should return system page allocator.
*/
virtual PageAllocator* GetPageAllocator() { return nullptr; }
#if defined(V8_COMPRESS_POINTERS) && \
!defined(V8_COMPRESS_POINTERS_IN_SHARED_CAGE)
/**
* Convenience allocator.
*
* When the sandbox is enabled, this allocator will allocate its backing
* memory inside the sandbox that belongs to passed isolate group.
* Otherwise, it will rely on malloc/free.
*
* 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(const IsolateGroup& group);
#endif // defined(V8_COMPRESS_POINTERS) &&
// !defined(V8_COMPRESS_POINTERS_IN_SHARED_CAGE)
/**
* Convenience allocator.
*
* When the sandbox is enabled, this allocator will allocate its backing
* memory inside the default global sandbox. Otherwise, it will rely on
* malloc/free.
*
* 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();
};
/**
* Data length in bytes.
*/
size_t ByteLength() const;
/**
* Maximum length in bytes.
*/
size_t MaxByteLength() const;
/**
* Attempt to create a new ArrayBuffer. Allocate |byte_length| bytes.
* Allocated memory will be owned by a created ArrayBuffer and
* will be deallocated when it is garbage-collected,
* unless the object is externalized. If allocation fails, the Maybe
* returned will be empty.
*/
static MaybeLocal<ArrayBuffer> MaybeNew(
Isolate* isolate, size_t byte_length,
BackingStoreInitializationMode initialization_mode =
BackingStoreInitializationMode::kZeroInitialized);
/**
* Create a new ArrayBuffer. Allocate |byte_length| bytes, which are either
* zero-initialized or uninitialized. Allocated memory will be owned by a
* created ArrayBuffer and will be deallocated when it is garbage-collected,
* unless the object is externalized.
*/
static Local<ArrayBuffer> New(
Isolate* isolate, size_t byte_length,
BackingStoreInitializationMode initialization_mode =
BackingStoreInitializationMode::kZeroInitialized);
/**
* Create a new ArrayBuffer with an existing backing store.
* The created array keeps a reference to the backing store until the array
* is garbage collected. Note that the IsExternal bit does not affect this
* reference from the array to the backing store.
*
* In future IsExternal bit will be removed. Until then the bit is set as
* follows. If the backing store does not own the underlying buffer, then
* the array is created in externalized state. Otherwise, the array is created
* in internalized state. In the latter case the array can be transitioned
* to the externalized state using Externalize(backing_store).
*/
static Local<ArrayBuffer> New(Isolate* isolate,
std::shared_ptr<BackingStore> backing_store);
/**
* Returns a new standalone BackingStore that is allocated using the array
* buffer allocator of the isolate. The allocation can either be zero
* initialized, or uninitialized. The result can be later passed to
* ArrayBuffer::New.
*
* If the allocator returns nullptr, then the function may cause GCs in the
* given isolate and re-try the allocation.
*
* If GCs do not help and on_failure is kOutOfMemory, then the
* function will crash with an out-of-memory error.
*
* Otherwise if GCs do not help (or the allocation is too large for GCs to
* help) and on_failure is kReturnNull, then a null result is returned.
*/
static std::unique_ptr<BackingStore> NewBackingStore(
Isolate* isolate, size_t byte_length,
BackingStoreInitializationMode initialization_mode =
BackingStoreInitializationMode::kZeroInitialized,
BackingStoreOnFailureMode on_failure =
BackingStoreOnFailureMode::kOutOfMemory);
/**
* Returns a new standalone BackingStore that takes over the ownership of
* the given buffer. The destructor of the BackingStore invokes the given
* deleter callback.
*
* The result can be later passed to ArrayBuffer::New. The raw pointer
* to the buffer must not be passed again to any V8 API function.
*/
static std::unique_ptr<BackingStore> NewBackingStore(
void* data, size_t byte_length, v8::BackingStore::DeleterCallback deleter,
void* deleter_data);
/**
* Returns a new resizable standalone BackingStore that is allocated using the
* array buffer allocator of the isolate. The result can be later passed to
* ArrayBuffer::New.
*
* |byte_length| must be <= |max_byte_length|.
*
* This function is usable without an isolate. Unlike |NewBackingStore| calls
* with an isolate, GCs cannot be triggered, and there are no
* retries. Allocation failure will cause the function to crash with an
* out-of-memory error.
*/
static std::unique_ptr<BackingStore> NewResizableBackingStore(
size_t byte_length, size_t max_byte_length);
/**
* Returns true if this ArrayBuffer may be detached.
*/
bool IsDetachable() const;
/**
* Returns true if this ArrayBuffer has been detached.
*/
bool WasDetached() const;
/**
* Detaches this ArrayBuffer and all its views (typed arrays).
* Detaching sets the byte length of the buffer and all typed arrays to zero,
* preventing JavaScript from ever accessing underlying backing store.
* ArrayBuffer should have been externalized and must be detachable.
*/
V8_DEPRECATED(
"Use the version which takes a key parameter (passing a null handle is "
"ok).")
void Detach();
/**
* Detaches this ArrayBuffer and all its views (typed arrays).
* Detaching sets the byte length of the buffer and all typed arrays to zero,
* preventing JavaScript from ever accessing underlying backing store.
* ArrayBuffer should have been externalized and must be detachable. Returns
* Nothing if the key didn't pass the [[ArrayBufferDetachKey]] check,
* Just(true) otherwise.
*/
V8_WARN_UNUSED_RESULT Maybe<bool> Detach(v8::Local<v8::Value> key);
/**
* Sets the ArrayBufferDetachKey.
*/
void SetDetachKey(v8::Local<v8::Value> key);
/**
* Get a shared pointer to the backing store of this array buffer. This
* pointer coordinates the lifetime management of the internal storage
* with any live ArrayBuffers on the heap, even across isolates. The embedder
* should not attempt to manage lifetime of the storage through other means.
*
* The returned shared pointer will not be empty, even if the ArrayBuffer has
* been detached. Use |WasDetached| to tell if it has been detached instead.
*/
std::shared_ptr<BackingStore> GetBackingStore();
/**
* More efficient shortcut for
* GetBackingStore()->IsResizableByUserJavaScript().
*/
bool IsResizableByUserJavaScript() const;
/**
* More efficient shortcut for GetBackingStore()->Data(). The returned pointer
* is valid as long as the ArrayBuffer is alive.
*/
void* Data() const;
V8_INLINE static ArrayBuffer* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
CheckCast(value);
#endif
return static_cast<ArrayBuffer*>(value);
}
static constexpr int kInternalFieldCount =
V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
static constexpr int kEmbedderFieldCount = kInternalFieldCount;
#if V8_ENABLE_SANDBOX
static constexpr size_t kMaxByteLength =
internal::kMaxSafeBufferSizeForSandbox;
#elif V8_HOST_ARCH_32_BIT
static constexpr size_t kMaxByteLength = std::numeric_limits<int>::max();
#else
// The maximum safe integer (2^53 - 1).
static constexpr size_t kMaxByteLength =
static_cast<size_t>((uint64_t{1} << 53) - 1);
#endif
private:
ArrayBuffer();
static void CheckCast(Value* obj);
friend class TypedArray;
};
#ifndef V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT
// Defined using gn arg `v8_array_buffer_view_internal_field_count`.
#define V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT 2
#endif
/**
* A base class for an instance of one of "views" over ArrayBuffer,
* including TypedArrays and DataView (ES6 draft 15.13).
*/
class V8_EXPORT ArrayBufferView : public Object {
public:
/**
* Returns underlying ArrayBuffer.
*/
Local<ArrayBuffer> Buffer();
/**
* Byte offset in |Buffer|.
*/
size_t ByteOffset();
/**
* Size of a view in bytes.
*/
size_t ByteLength();
/**
* Copy the contents of the ArrayBufferView's buffer to an embedder defined
* memory without additional overhead that calling ArrayBufferView::Buffer
* might incur.
*
* Will write at most min(|byte_length|, ByteLength) bytes starting at
* ByteOffset of the underlying buffer to the memory starting at |dest|.
* Returns the number of bytes actually written.
*/
size_t CopyContents(void* dest, size_t byte_length);
/**
* Returns the contents of the ArrayBufferView's buffer as a MemorySpan. If
* the contents are on the V8 heap, they get copied into `storage`. Otherwise
* a view into the off-heap backing store is returned. The provided storage
* should be at least as large as the maximum on-heap size of a TypedArray,
* was defined in gn with `typed_array_max_size_in_heap`. The default value is
* 64 bytes.
*/
v8::MemorySpan<uint8_t> GetContents(v8::MemorySpan<uint8_t> storage);
/**
* Returns true if ArrayBufferView's backing ArrayBuffer has already been
* allocated.
*/
bool HasBuffer() const;
V8_INLINE static ArrayBufferView* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
CheckCast(value);
#endif
return static_cast<ArrayBufferView*>(value);
}
static constexpr int kInternalFieldCount =
V8_ARRAY_BUFFER_VIEW_INTERNAL_FIELD_COUNT;
static const int kEmbedderFieldCount = kInternalFieldCount;
private:
ArrayBufferView();
static void CheckCast(Value* obj);
};
/**
* An instance of DataView constructor (ES6 draft 15.13.7).
*/
class V8_EXPORT DataView : public ArrayBufferView {
public:
static Local<DataView> New(Local<ArrayBuffer> array_buffer,
size_t byte_offset, size_t length);
static Local<DataView> New(Local<SharedArrayBuffer> shared_array_buffer,
size_t byte_offset, size_t length);
V8_INLINE static DataView* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
CheckCast(value);
#endif
return static_cast<DataView*>(value);
}
private:
DataView();
static void CheckCast(Value* obj);
};
/**
* An instance of the built-in SharedArrayBuffer constructor.
*/
class V8_EXPORT SharedArrayBuffer : public Object {
public:
/**
* Data length in bytes.
*/
size_t ByteLength() const;
/**
* Maximum length in bytes.
*/
size_t MaxByteLength() const;
/**
* Create a new SharedArrayBuffer. Allocate |byte_length| bytes, which are
* either zero-initialized or uninitialized. Allocated memory will be owned by
* a created SharedArrayBuffer and will be deallocated when it is
* garbage-collected, unless the object is externalized.
*/
static Local<SharedArrayBuffer> New(
Isolate* isolate, size_t byte_length,
BackingStoreInitializationMode initialization_mode =
BackingStoreInitializationMode::kZeroInitialized);
/**
* Create a new SharedArrayBuffer. Allocate |byte_length| bytes, which are
* either zero-initialized or uninitialized. Allocated memory will be owned by
* a created SharedArrayBuffer and will be deallocated when it is
* garbage-collected, unless the object is externalized. If allocation
* fails, the Maybe returned will be empty.
*/
static MaybeLocal<SharedArrayBuffer> MaybeNew(
Isolate* isolate, size_t byte_length,
BackingStoreInitializationMode initialization_mode =
BackingStoreInitializationMode::kZeroInitialized);
/**
* Create a new SharedArrayBuffer with an existing backing store.
* The created array keeps a reference to the backing store until the array
* is garbage collected. Note that the IsExternal bit does not affect this
* reference from the array to the backing store.
*
* In future IsExternal bit will be removed. Until then the bit is set as
* follows. If the backing store does not own the underlying buffer, then
* the array is created in externalized state. Otherwise, the array is created
* in internalized state. In the latter case the array can be transitioned
* to the externalized state using Externalize(backing_store).
*/
static Local<SharedArrayBuffer> New(
Isolate* isolate, std::shared_ptr<BackingStore> backing_store);
/**
* Returns a new standalone BackingStore that is allocated using the array
* buffer allocator of the isolate. The allocation can either be zero
* initialized, or uninitialized. The result can be later passed to
* SharedArrayBuffer::New.
*
* If the allocator returns nullptr, then the function may cause GCs in the
* given isolate and re-try the allocation.
*
* If on_failure is kOutOfMemory and GCs do not help, then the function will
* crash with an out-of-memory error.
*
* Otherwise, if on_failure is kReturnNull and GCs do not help (or the
* byte_length is so large that the allocation cannot succeed), then a null
* result is returned.
*/
static std::unique_ptr<BackingStore> NewBackingStore(
Isolate* isolate, size_t byte_length,
BackingStoreInitializationMode initialization_mode =
BackingStoreInitializationMode::kZeroInitialized,
BackingStoreOnFailureMode on_failure =
BackingStoreOnFailureMode::kOutOfMemory);
/**
* Returns a new standalone BackingStore that takes over the ownership of
* the given buffer. The destructor of the BackingStore invokes the given
* deleter callback.
*
* The result can be later passed to SharedArrayBuffer::New. The raw pointer
* to the buffer must not be passed again to any V8 functions.
*/
static std::unique_ptr<BackingStore> NewBackingStore(
void* data, size_t byte_length, v8::BackingStore::DeleterCallback deleter,
void* deleter_data);
/**
* Get a shared pointer to the backing store of this array buffer. This
* pointer coordinates the lifetime management of the internal storage
* with any live ArrayBuffers on the heap, even across isolates. The embedder
* should not attempt to manage lifetime of the storage through other means.
*/
std::shared_ptr<BackingStore> GetBackingStore();
/**
* More efficient shortcut for GetBackingStore()->Data(). The returned pointer
* is valid as long as the ArrayBuffer is alive.
*/
void* Data() const;
V8_INLINE static SharedArrayBuffer* Cast(Value* value) {
#ifdef V8_ENABLE_CHECKS
CheckCast(value);
#endif
return static_cast<SharedArrayBuffer*>(value);
}
static constexpr int kInternalFieldCount =
V8_ARRAY_BUFFER_INTERNAL_FIELD_COUNT;
private:
SharedArrayBuffer();
static void CheckCast(Value* obj);
};
} // namespace v8
#endif // INCLUDE_V8_ARRAY_BUFFER_H_
|