tor-browser

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

StreamConsumer.h (4655B)

      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 #ifndef js_StreamConsumer_h
      7 #define js_StreamConsumer_h
      8 
      9 #include "mozilla/Attributes.h"
     10 #include "mozilla/RefCountType.h"
     11 
     12 #include <stddef.h>
     13 #include <stdint.h>
     14 
     15 #include "jstypes.h"
     16 
     17 #include "js/AllocPolicy.h"
     18 #include "js/TypeDecls.h"
     19 #include "js/UniquePtr.h"
     20 #include "js/Vector.h"
     21 
     22 namespace JS {
     23 
     24 /**
     25 * The ConsumeStreamCallback is called from an active JSContext, passing a
     26 * StreamConsumer that wishes to consume the given host object as a stream of
     27 * bytes with the given MIME type. On failure, the embedding must report the
     28 * appropriate error on 'cx'. On success, the embedding must call
     29 * consumer->consumeChunk() repeatedly on any thread until exactly one of:
     30 *  - consumeChunk() returns false
     31 *  - the embedding calls consumer->streamEnd()
     32 *  - the embedding calls consumer->streamError()
     33 * before JS_DestroyContext(cx) or JS::ShutdownAsyncTasks(cx) is called.
     34 *
     35 * Note: consumeChunk(), streamEnd() and streamError() may be called
     36 * synchronously by ConsumeStreamCallback.
     37 *
     38 * When streamEnd() is called, the embedding may optionally pass an
     39 * OptimizedEncodingListener*, indicating that there is a cache entry associated
     40 * with this stream that can store an optimized encoding of the bytes that were
     41 * just streamed at some point in the future by having SpiderMonkey call
     42 * storeOptimizedEncoding(). Until the optimized encoding is ready, SpiderMonkey
     43 * will hold an outstanding refcount to keep the listener alive.
     44 *
     45 * After storeOptimizedEncoding() is called, on cache hit, the embedding
     46 * may call consumeOptimizedEncoding() instead of consumeChunk()/streamEnd().
     47 * The embedding must ensure that the GetOptimizedEncodingBuildId() (see
     48 * js/BuildId.h) at the time when an optimized encoding is created is the same
     49 * as when it is later consumed.
     50 */
     51 
     52 class OptimizedEncodingListener {
     53 protected:
     54  virtual ~OptimizedEncodingListener() = default;
     55 
     56 public:
     57  // SpiderMonkey will hold an outstanding reference count as long as it holds
     58  // a pointer to OptimizedEncodingListener.
     59  virtual MozExternalRefCountType MOZ_XPCOM_ABI AddRef() = 0;
     60  virtual MozExternalRefCountType MOZ_XPCOM_ABI Release() = 0;
     61 
     62  // SpiderMonkey may optionally call storeOptimizedEncoding() after it has
     63  // finished processing a streamed resource.
     64  virtual void storeOptimizedEncoding(const uint8_t* bytes, size_t length) = 0;
     65 };
     66 
     67 class JS_PUBLIC_API StreamConsumer {
     68 protected:
     69  // AsyncStreamConsumers are created and destroyed by SpiderMonkey.
     70  StreamConsumer() = default;
     71  virtual ~StreamConsumer() = default;
     72 
     73 public:
     74  // Called by the embedding as each chunk of bytes becomes available.
     75  // If this function returns 'false', the stream must drop all pointers to
     76  // this StreamConsumer.
     77  virtual bool consumeChunk(const uint8_t* begin, size_t length) = 0;
     78 
     79  // Called by the embedding when the stream reaches end-of-file, passing the
     80  // listener described above.
     81  virtual void streamEnd(OptimizedEncodingListener* listener = nullptr) = 0;
     82 
     83  // Called by the embedding when there is an error during streaming. The
     84  // given error code should be passed to the ReportStreamErrorCallback on the
     85  // main thread to produce the semantically-correct rejection value.
     86  virtual void streamError(size_t errorCode) = 0;
     87 
     88  // Called by the embedding *instead of* consumeChunk()/streamEnd() if an
     89  // optimized encoding is available from a previous streaming of the same
     90  // contents with the same optimized build id.
     91  virtual void consumeOptimizedEncoding(const uint8_t* begin,
     92                                        size_t length) = 0;
     93 
     94  // Provides optional stream attributes such as base or source mapping URLs.
     95  // Necessarily called before consumeChunk(), streamEnd(), streamError() or
     96  // consumeOptimizedEncoding(). The caller retains ownership of the strings.
     97  virtual void noteResponseURLs(const char* maybeUrl,
     98                                const char* maybeSourceMapUrl) = 0;
     99 };
    100 
    101 enum class MimeType { Wasm };
    102 
    103 using ConsumeStreamCallback = bool (*)(JSContext*, JS::HandleObject, MimeType,
    104                                       StreamConsumer*);
    105 
    106 using ReportStreamErrorCallback = void (*)(JSContext*, size_t);
    107 
    108 extern JS_PUBLIC_API void InitConsumeStreamCallback(
    109    JSContext* cx, ConsumeStreamCallback consume,
    110    ReportStreamErrorCallback report);
    111 
    112 }  // namespace JS
    113 
    114 #endif  // js_StreamConsumer_h