js/public/ArrayBufferMaybeShared.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 /**
   7  * Functions for working with either ArrayBuffer or SharedArrayBuffer objects
   8  * in agnostic fashion.
   9  */
  10
  11 #ifndef js_ArrayBufferMaybeShared_h
  12 #define js_ArrayBufferMaybeShared_h
  13
  14 #include <stdint.h>  // uint8_t, uint32_t
  15
  16 #include "jstypes.h"  // JS_PUBLIC_API
  17
  18 struct JS_PUBLIC_API JSContext;
  19 class JS_PUBLIC_API JSObject;
  20
  21 namespace JS {
  22
  23 class JS_PUBLIC_API AutoRequireNoGC;
  24
  25 // TYPE TESTING
  26
  27 /**
  28  * Check whether obj supports the JS::GetArrayBufferMaybeShared* APIs.  Note
  29  * that this may return false if a security wrapper is encountered that denies
  30  * the unwrapping. If this test succeeds, then it is safe to call the various
  31  * predicate and accessor JSAPI calls defined below.
  32  */
  33 extern JS_PUBLIC_API bool IsArrayBufferObjectMaybeShared(JSObject* obj);
  34
  35 // ACCESSORS
  36
  37 /*
  38  * Test for ArrayBufferMaybeShared subtypes and return the unwrapped object if
  39  * so, else nullptr. Never throws.
  40  */
  41 extern JS_PUBLIC_API JSObject* UnwrapArrayBufferMaybeShared(JSObject* obj);
  42
  43 /**
  44  * Get the length, sharedness, and data from an ArrayBufferMaybeShared subtypes.
  45  *
  46  * The computed length and data pointer may be invalidated by a GC or by an
  47  * unshared array buffer becoming detached. Callers must take care not to
  48  * perform any actions that could trigger a GC or result in an unshared array
  49  * buffer becoming detached. If such actions nonetheless must be performed,
  50  * callers should perform this call a second time (and sensibly handle results
  51  * that may be different from those returned the first time). (Sharedness is an
  52  * immutable characteristic of an array buffer or shared array buffer, so that
  53  * boolean remains valid across GC or detaching.)
  54  *
  55  * |obj| must be an ArrayBufferMaybeShared subtype: an ArrayBuffer or a
  56  * SharedArrayBuffer.
  57  *
  58  * |*length| will be set to bytes in the buffer.
  59  *
  60  * |*isSharedMemory| will be set to true if it is a SharedArrayBuffer, otherwise
  61  * to false.
  62  *
  63  * |*data| will be set to a pointer to the bytes in the buffer.
  64  */
  65 extern JS_PUBLIC_API void GetArrayBufferMaybeSharedLengthAndData(
  66     JSObject* obj, size_t* length, bool* isSharedMemory, uint8_t** data);
  67
  68 /**
  69  * Return a pointer to the start of the array buffer's data, and indicate
  70  * whether the data is from a shared array buffer through an outparam.
  71  *
  72  * The returned data pointer may be invalidated by a GC or by an unshared array
  73  * buffer becoming detached. Callers must take care not to perform any actions
  74  * that could trigger a GC or result in an unshared array buffer becoming
  75  * detached. If such actions nonetheless must be performed, callers should
  76  * perform this call a second time (and sensibly handle results that may be
  77  * different from those returned the first time). (Sharedness is an immutable
  78  * characteristic of an array buffer or shared array buffer, so that boolean
  79  * remains valid across GC or detaching.)
  80  *
  81  * |obj| must have passed a JS::IsArrayBufferObjectMaybeShared test, or somehow
  82  * be known that it would pass such a test: it is an ArrayBuffer or
  83  * SharedArrayBuffer or a wrapper of an ArrayBuffer/SharedArrayBuffer, and the
  84  * unwrapping will succeed.
  85  *
  86  * |*isSharedMemory| will be set to true if the typed array maps a
  87  * SharedArrayBuffer, otherwise to false.
  88  */
  89 extern JS_PUBLIC_API uint8_t* GetArrayBufferMaybeSharedData(
  90     JSObject* obj, bool* isSharedMemory, const AutoRequireNoGC&);
  91
  92 /**
  93  * Returns whether the passed array buffer is 'large': its byteLength >= 2 GB.
  94  *
  95  * |obj| must pass a JS::IsArrayBufferObjectMaybeShared test.
  96  */
  97 extern JS_PUBLIC_API bool IsLargeArrayBufferMaybeShared(JSObject* obj);
  98
  99 /**
 100  * Returns whether the passed array buffer is resizable or growable for shared
 101  * array buffers.
 102  *
 103  * |obj| must pass a JS::IsArrayBufferObjectMaybeShared test.
 104  */
 105 extern JS_PUBLIC_API bool IsResizableArrayBufferMaybeShared(JSObject* obj);
 106
 107 }  // namespace JS
 108
 109 #endif /* js_ArrayBufferMaybeShared_h */