tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

ArrayBufferMaybeShared.h (4381B)

      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 /**
    108 * Returns whether the passed array buffer is immutable.
    109 *
    110 * |obj| must pass a JS::IsArrayBufferObjectMaybeShared test.
    111 */
    112 extern JS_PUBLIC_API bool IsImmutableArrayBufferMaybeShared(JSObject* obj);
    113 
    114 }  // namespace JS
    115 
    116 #endif /* js_ArrayBufferMaybeShared_h */