js/public/StreamConsumer.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 #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