gecko/dom/base/StructuredCloneHolder.h

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_dom_StructuredCloneHolder_h
#define mozilla_dom_StructuredCloneHolder_h

#include "js/StructuredClone.h"
#include "mozilla/Move.h"
#include "nsAutoPtr.h"
#include "nsISupports.h"
#include "nsTArray.h"

#ifdef DEBUG
#include "nsIThread.h"
#endif

namespace mozilla {
class ErrorResult;
namespace layers {
class Image;
}

namespace gfx {
class DataSourceSurface;
}

namespace dom {

class StructuredCloneHolderBase
{
public:
  StructuredCloneHolderBase();
  virtual ~StructuredCloneHolderBase();

  // These methods should be implemented in order to clone data.
  // Read more documentation in js/public/StructuredClone.h.

  virtual JSObject* CustomReadHandler(JSContext* aCx,
                                      JSStructuredCloneReader* aReader,
                                      uint32_t aTag,
                                      uint32_t aIndex) = 0;

  virtual bool CustomWriteHandler(JSContext* aCx,
                                  JSStructuredCloneWriter* aWriter,
                                  JS::Handle<JSObject*> aObj) = 0;

  // This method has to be called when this object is not needed anymore.
  // It will free memory and the buffer. This has to be called because
  // otherwise the buffer will be freed in the DTOR of this class and at that
  // point we cannot use the overridden methods.
  void Clear();

  // If these 3 methods are not implement, transfering objects will not be
  // allowed. Otherwise only arrayBuffers will be transferred.

  virtual bool
  CustomReadTransferHandler(JSContext* aCx,
                            JSStructuredCloneReader* aReader,
                            uint32_t aTag,
                            void* aContent,
                            uint64_t aExtraData,
                            JS::MutableHandleObject aReturnObject);

  virtual bool
  CustomWriteTransferHandler(JSContext* aCx,
                             JS::Handle<JSObject*> aObj,
                             // Output:
                             uint32_t* aTag,
                             JS::TransferableOwnership* aOwnership,
                             void** aContent,
                             uint64_t* aExtraData);

  virtual void
  CustomFreeTransferHandler(uint32_t aTag,
                            JS::TransferableOwnership aOwnership,
                            void* aContent,
                            uint64_t aExtraData);

  // These methods are what you should use to read/write data.

  // Execute the serialization of aValue using the Structured Clone Algorithm.
  // The data can read back using Read().
  bool Write(JSContext* aCx,
             JS::Handle<JS::Value> aValue);

  // Like Write() but it supports the transferring of objects.
  bool Write(JSContext* aCx,
             JS::Handle<JS::Value> aValue,
             JS::Handle<JS::Value> aTransfer);

  // If Write() has been called, this method retrieves data and stores it into
  // aValue.
  bool Read(JSContext* aCx,
            JS::MutableHandle<JS::Value> aValue);

  bool HasData() const
  {
    return !!mBuffer;
  }

  uint64_t* BufferData() const
  {
    MOZ_ASSERT(mBuffer, "Write() has never been called.");
    return mBuffer->data();
  }

  size_t BufferSize() const
  {
    MOZ_ASSERT(mBuffer, "Write() has never been called.");
    return mBuffer->nbytes();
  }

protected:
  nsAutoPtr<JSAutoStructuredCloneBuffer> mBuffer;

#ifdef DEBUG
  bool mClearCalled;
#endif
};

class BlobImpl;
class MessagePort;
class MessagePortIdentifier;

class StructuredCloneHolder : public StructuredCloneHolderBase
{
public:
  enum CloningSupport
  {
    CloningSupported,
    CloningNotSupported
  };

  enum TransferringSupport
  {
    TransferringSupported,
    TransferringNotSupported
  };

  enum ContextSupport
  {
    SameProcessSameThread,
    SameProcessDifferentThread,
    DifferentProcess
  };

  // If cloning is supported, this object will clone objects such as Blobs,
  // FileList, ImageData, etc.
  // If transferring is supported, we will transfer MessagePorts and in the
  // future other transferrable objects.
  // The ContextSupport is useful to know where the cloned/transferred data can
  // be read and written. Additional checks about the nature of the objects
  // will be done based on this context value because not all the objects can
  // be sent between threads or processes.
  explicit StructuredCloneHolder(CloningSupport aSupportsCloning,
                                 TransferringSupport aSupportsTransferring,
                                 ContextSupport aContextSupport);
  virtual ~StructuredCloneHolder();

  // Normally you should just use Write() and Read().

  void Write(JSContext* aCx,
             JS::Handle<JS::Value> aValue,
             ErrorResult &aRv);

  void Write(JSContext* aCx,
             JS::Handle<JS::Value> aValue,
             JS::Handle<JS::Value> aTransfer,
             ErrorResult &aRv);

  void Read(nsISupports* aParent,
            JSContext* aCx,
            JS::MutableHandle<JS::Value> aValue,
            ErrorResult &aRv);

  // Sometimes, when IPC is involved, you must send a buffer after a Write().
  // This method 'steals' the internal data from this class.
  // You should free this buffer with StructuredCloneHolder::FreeBuffer().
  void MoveBufferDataToArray(FallibleTArray<uint8_t>& aArray,
                             ErrorResult& aRv);

  // Call this method to know if this object is keeping some DOM object alive.
  bool HasClonedDOMObjects() const
  {
    return !mBlobImplArray.IsEmpty() ||
           !mClonedSurfaces.IsEmpty();
  }

  nsTArray<RefPtr<BlobImpl>>& BlobImpls()
  {
    MOZ_ASSERT(mSupportsCloning, "Blobs cannot be taken/set if cloning is not supported.");
    return mBlobImplArray;
  }

  // The parent object is set internally just during the Read(). This method
  // can be used by read functions to retrieve it.
  nsISupports* ParentDuringRead() const
  {
    return mParent;
  }

  // This must be called if the transferring has ports generated by Read().
  // MessagePorts are not thread-safe and they must be retrieved in the thread
  // where they are created.
  nsTArray<RefPtr<MessagePort>>&& TakeTransferredPorts()
  {
    MOZ_ASSERT(mSupportsTransferring);
    return Move(mTransferredPorts);
  }

  nsTArray<MessagePortIdentifier>& PortIdentifiers()
  {
    MOZ_ASSERT(mSupportsTransferring);
    return mPortIdentifiers;
  }

  nsTArray<RefPtr<gfx::DataSourceSurface>>& GetSurfaces()
  {
    return mClonedSurfaces;
  }

  // Implementations of the virtual methods to allow cloning of objects which
  // JS engine itself doesn't clone.

  virtual JSObject* CustomReadHandler(JSContext* aCx,
                                      JSStructuredCloneReader* aReader,
                                      uint32_t aTag,
                                      uint32_t aIndex) override;

  virtual bool CustomWriteHandler(JSContext* aCx,
                                  JSStructuredCloneWriter* aWriter,
                                  JS::Handle<JSObject*> aObj) override;

  virtual bool CustomReadTransferHandler(JSContext* aCx,
                                         JSStructuredCloneReader* aReader,
                                         uint32_t aTag,
                                         void* aContent,
                                         uint64_t aExtraData,
                                         JS::MutableHandleObject aReturnObject) override;

  virtual bool CustomWriteTransferHandler(JSContext* aCx,
                                          JS::Handle<JSObject*> aObj,
                                          uint32_t* aTag,
                                          JS::TransferableOwnership* aOwnership,
                                          void** aContent,
                                          uint64_t* aExtraData) override;

  virtual void CustomFreeTransferHandler(uint32_t aTag,
                                         JS::TransferableOwnership aOwnership,
                                         void* aContent,
                                         uint64_t aExtraData) override;

  // These 2 static methods are useful to read/write fully serializable objects.
  // They can be used by custom StructuredCloneHolderBase classes to
  // serialize objects such as ImageData, CryptoKey, RTCCertificate, etc.

  static JSObject* ReadFullySerializableObjects(JSContext* aCx,
                                                JSStructuredCloneReader* aReader,
                                                uint32_t aTag);

  static bool  WriteFullySerializableObjects(JSContext* aCx,
                                             JSStructuredCloneWriter* aWriter,
                                             JS::Handle<JSObject*> aObj);

protected:
  // If you receive a buffer from IPC, you can use this method to retrieve a
  // JS::Value. It can happen that you want to pre-populate the array of Blobs
  // and/or the PortIdentifiers.
  void ReadFromBuffer(nsISupports* aParent,
                      JSContext* aCx,
                      uint64_t* aBuffer,
                      size_t aBufferLength,
                      JS::MutableHandle<JS::Value> aValue,
                      ErrorResult &aRv);

  void ReadFromBuffer(nsISupports* aParent,
                      JSContext* aCx,
                      uint64_t* aBuffer,
                      size_t aBufferLength,
                      uint32_t aAlgorithmVersion,
                      JS::MutableHandle<JS::Value> aValue,
                      ErrorResult &aRv);

  // Use this method to free a buffer generated by MoveToBuffer().
  void FreeBuffer(uint64_t* aBuffer,
                  size_t aBufferLength);

  bool mSupportsCloning;
  bool mSupportsTransferring;
  ContextSupport mSupportedContext;

  // Used for cloning blobs in the structured cloning algorithm.
  nsTArray<RefPtr<BlobImpl>> mBlobImplArray;

  // This is used for sharing the backend of ImageBitmaps.
  // The DataSourceSurface object must be thread-safely reference-counted.
  // The DataSourceSurface object will not be written ever via any ImageBitmap
  // instance, so no race condition will occur.
  nsTArray<RefPtr<gfx::DataSourceSurface>> mClonedSurfaces;

  // This raw pointer is only set within ::Read() and is unset by the end.
  nsISupports* MOZ_NON_OWNING_REF mParent;

  // This array contains the ports once we've finished the reading. It's
  // generated from the mPortIdentifiers array.
  nsTArray<RefPtr<MessagePort>> mTransferredPorts;

  // This array contains the identifiers of the MessagePorts. Based on these we
  // are able to reconnect the new transferred ports with the other
  // MessageChannel ports.
  nsTArray<MessagePortIdentifier> mPortIdentifiers;

#ifdef DEBUG
  nsCOMPtr<nsIThread> mCreationThread;
#endif
};

} // dom namespace
} // mozilla namespace

#endif // mozilla_dom_StructuredCloneHolder_h