/work/obj-fuzz/dist/include/mozilla/media/MediaUtils.h

Source (jump to first uncovered line)
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set sw=2 ts=8 et ft=cpp : */
/* 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_MediaUtils_h
#define mozilla_MediaUtils_h

#include "mozilla/Assertions.h"
#include "mozilla/Monitor.h"
#include "mozilla/MozPromise.h"
#include "mozilla/RefPtr.h"
#include "mozilla/SharedThreadPool.h"
#include "mozilla/TaskQueue.h"
#include "mozilla/UniquePtr.h"
#include "nsCOMPtr.h"
#include "nsIAsyncShutdown.h"
#include "nsISupportsImpl.h"
#include "nsThreadUtils.h"

class nsIEventTarget;

namespace mozilla {
namespace media {

/*
 * media::Pledge - A promise-like pattern for c++ that takes lambda functions.
 *
 * Asynchronous APIs that proxy to another thread or to the chrome process and
 * back may find it useful to return a pledge to callers who then use
 * pledge.Then(func) to specify a lambda function to be invoked with the result
 * later back on this same thread.
 *
 * Callers will enjoy that lambdas allow "capturing" of local variables, much
 * like closures in JavaScript (safely by-copy by default).
 *
 * Callers will also enjoy that they do not need to be thread-safe (their code
 * runs on the same thread after all).
 *
 * Advantageously, pledges are non-threadsafe by design (because locking and
 * event queues are redundant). This means none of the lambdas you pass in,
 * or variables you lambda-capture into them, need be threasafe or support
 * threadsafe refcounting. After all, they'll run later on the same thread.
 *
 *   RefPtr<media::Pledge<Foo>> p = GetFooAsynchronously(); // returns a pledge
 *   p->Then([](const Foo& foo) {
 *     // use foo here (same thread. Need not be thread-safe!)
 *   });
 *
 * See media::CoatCheck below for an example of GetFooAsynchronously().
 */

class PledgeBase
{
public:
  NS_INLINE_DECL_REFCOUNTING(PledgeBase);
protected:
  virtual ~PledgeBase() {};
};

template<typename ValueType, typename ErrorType = nsresult>
class Pledge : public PledgeBase
{
  // TODO: Remove workaround once mozilla allows std::function from <functional>
  // wo/std::function support, do template + virtual trick to accept lambdas
  class FunctorsBase
  {
  public:
    FunctorsBase() {}
    virtual void Succeed(ValueType& result) = 0;
    virtual void Fail(ErrorType& error) = 0;
    virtual ~FunctorsBase() {};
  };

public:
  explicit Pledge() : mDone(false), mRejected(false) {}
  Pledge(const Pledge& aOther) = delete;
  Pledge& operator = (const Pledge&) = delete;

  template<typename OnSuccessType>
  void Then(OnSuccessType&& aOnSuccess)
  {
    Then(std::forward<OnSuccessType>(aOnSuccess), [](ErrorType&){});
  }

  template<typename OnSuccessType, typename OnFailureType>
  void Then(OnSuccessType&& aOnSuccess, OnFailureType&& aOnFailure)
  {
    class Functors : public FunctorsBase
    {
    public:
      Functors(OnSuccessType&& aOnSuccessRef, OnFailureType&& aOnFailureRef)
        : mOnSuccess(std::move(aOnSuccessRef)), mOnFailure(std::move(aOnFailureRef)) {}

      void Succeed(ValueType& result)
      {
        mOnSuccess(result);
      }
      void Fail(ErrorType& error)
      {
        mOnFailure(error);
      };

      OnSuccessType mOnSuccess;
      OnFailureType mOnFailure;
    };
    mFunctors = MakeUnique<Functors>(std::forward<OnSuccessType>(aOnSuccess),
                                     std::forward<OnFailureType>(aOnFailure));
    if (mDone) {
      if (!mRejected) {
        mFunctors->Succeed(mValue);
      } else {
        mFunctors->Fail(mError);
      }
    }
  }

  void Resolve(const ValueType& aValue)
  {
    mValue = aValue;
    Resolve();
  }

  void Reject(ErrorType rv)
  {
    if (!mDone) {
      mDone = mRejected = true;
      mError = rv;
      if (mFunctors) {
        mFunctors->Fail(mError);
      }
    }
  }

protected:
  void Resolve()
  {
    if (!mDone) {
      mDone = true;
      MOZ_ASSERT(!mRejected);
      if (mFunctors) {
        mFunctors->Succeed(mValue);
      }
    }
  }

  ValueType mValue;
private:
  ~Pledge() {};
  bool mDone;
  bool mRejected;
  ErrorType mError;
  UniquePtr<FunctorsBase> mFunctors;
};

/* media::NewRunnableFrom() - Create a Runnable from a lambda.
 *
 * Passing variables (closures) to an async function is clunky with Runnable:
 *
 *   void Foo()
 *   {
 *     class FooRunnable : public Runnable
 *     {
 *     public:
 *       FooRunnable(const Bar &aBar) : mBar(aBar) {}
 *       NS_IMETHOD Run() override
 *       {
 *         // Use mBar
 *       }
 *     private:
 *       RefPtr<Bar> mBar;
 *     };
 *
 *     RefPtr<Bar> bar = new Bar();
 *     NS_DispatchToMainThread(new FooRunnable(bar);
 *   }
 *
 * It's worse with more variables. Lambdas have a leg up with variable capture:
 *
 *   void Foo()
 *   {
 *     RefPtr<Bar> bar = new Bar();
 *     NS_DispatchToMainThread(media::NewRunnableFrom([bar]() mutable {
 *       // use bar
 *     }));
 *   }
 *
 * Capture is by-copy by default, so the nsRefPtr 'bar' is safely copied for
 * access on the other thread (threadsafe refcounting in bar is assumed).
 *
 * The 'mutable' keyword is only needed for non-const access to bar.
 */

template<typename OnRunType>
class LambdaRunnable : public Runnable
{
public:
  explicit LambdaRunnable(OnRunType&& aOnRun)
    : Runnable("media::LambdaRunnable")
    , mOnRun(std::move(aOnRun))
  {
  }

private:
  NS_IMETHODIMP
  Run() override
  {
    return mOnRun();
  }
  OnRunType mOnRun;
};

template<typename OnRunType>
already_AddRefed<LambdaRunnable<OnRunType>>
NewRunnableFrom(OnRunType&& aOnRun)
{
  typedef LambdaRunnable<OnRunType> LambdaType;
  RefPtr<LambdaType> lambda = new LambdaType(std::forward<OnRunType>(aOnRun));
  return lambda.forget();
}

/* media::CoatCheck - There and back again. Park an object in exchange for an id.
 *
 * A common problem with calling asynchronous functions that do work on other
 * threads or processes is how to pass in a heap object for use once the
 * function completes, without requiring that object to have threadsafe
 * refcounting, contain mutexes, be marshaled, or leak if things fail
 * (or worse, intermittent use-after-free because of lifetime issues).
 *
 * One solution is to set up a coat-check on the caller side, park your object
 * in exchange for an id, and send the id. Common in IPC, but equally useful
 * for same-process thread-hops, because by never leaving the thread there's
 * no need for objects to be threadsafe or use threadsafe refcounting. E.g.
 *
 *   class FooDoer
 *   {
 *     CoatCheck<Foo> mOutstandingFoos;
 *
 *   public:
 *     void DoFoo()
 *     {
 *       RefPtr<Foo> foo = new Foo();
 *       uint32_t requestId = mOutstandingFoos.Append(*foo);
 *       sChild->SendFoo(requestId);
 *     }
 *
 *     void RecvFooResponse(uint32_t requestId)
 *     {
 *       RefPtr<Foo> foo = mOutstandingFoos.Remove(requestId);
 *       if (foo) {
 *         // use foo
 *       }
 *     }
 *   };
 *
 * If you read media::Pledge earlier, here's how this is useful for pledges:
 *
 *   class FooGetter
 *   {
 *     CoatCheck<Pledge<Foo>> mOutstandingPledges;
 *
 *   public:
 *     already_addRefed<Pledge<Foo>> GetFooAsynchronously()
 *     {
 *       RefPtr<Pledge<Foo>> p = new Pledge<Foo>();
 *       uint32_t requestId = mOutstandingPledges.Append(*p);
 *       sChild->SendFoo(requestId);
 *       return p.forget();
 *     }
 *
 *     void RecvFooResponse(uint32_t requestId, const Foo& fooResult)
 *     {
 *       RefPtr<Foo> p = mOutstandingPledges.Remove(requestId);
 *       if (p) {
 *         p->Resolve(fooResult);
 *       }
 *     }
 *   };
 *
 * This helper is currently optimized for very small sets (i.e. not optimized).
 * It is also not thread-safe as the whole point is to stay on the same thread.
 */

template<class T>
class CoatCheck
{
public:
  typedef std::pair<uint32_t, RefPtr<T>> Element;

  uint32_t Append(T& t)
  {
    uint32_t id = GetNextId();
    mElements.AppendElement(Element(id, RefPtr<T>(&t)));
    return id;
  }

  already_AddRefed<T> Remove(uint32_t aId)
  {
    for (auto& element : mElements) {
      if (element.first == aId) {
        RefPtr<T> ref;
        ref.swap(element.second);
        mElements.RemoveElement(element);
        return ref.forget();
      }
    }
    MOZ_ASSERT_UNREACHABLE("Received id with no matching parked object!");
    return nullptr;
  }

private:
  static uint32_t GetNextId()
  {
    static uint32_t counter = 0;
    return ++counter;
  };
  AutoTArray<Element, 3> mElements;
};

/* media::Refcountable - Add threadsafe ref-counting to something that isn't.
 *
 * Often, reference counting is the most practical way to share an object with
 * another thread without imposing lifetime restrictions, even if there's
 * otherwise no concurrent access happening on the object.  For instance, an
 * algorithm on another thread may find it more expedient to modify a passed-in
 * object, rather than pass expensive copies back and forth.
 *
 * Lists in particular often aren't ref-countable, yet are expensive to copy,
 * e.g. nsTArray<RefPtr<Foo>>. Refcountable can be used to make such objects
 * (or owning smart-pointers to such objects) refcountable.
 *
 * Technical limitation: A template specialization is needed for types that take
 * a constructor. Please add below (UniquePtr covers a lot of ground though).
 */

class RefcountableBase
{
public:
  NS_INLINE_DECL_THREADSAFE_REFCOUNTING(RefcountableBase)
protected:
  virtual ~RefcountableBase() {}
};

template<typename T>
class Refcountable : public T, public RefcountableBase
{
public:
  NS_METHOD_(MozExternalRefCountType) AddRef()
  {
    return RefcountableBase::AddRef();
  }

  NS_METHOD_(MozExternalRefCountType) Release()
  {
    return RefcountableBase::Release();
  }

private:
  ~Refcountable<T>() {}
};

template<typename T>
class Refcountable<UniquePtr<T>> : public UniquePtr<T>
{
public:
  explicit Refcountable<UniquePtr<T>>(T* aPtr) : UniquePtr<T>(aPtr) {}
  NS_INLINE_DECL_THREADSAFE_REFCOUNTING(Refcountable<T>)
private:
  ~Refcountable<UniquePtr<T>>() {}
};

/* Async shutdown helpers
 */

already_AddRefed<nsIAsyncShutdownClient>
GetShutdownBarrier();

class ShutdownBlocker : public nsIAsyncShutdownBlocker
{
public:
  ShutdownBlocker(const nsString& aName) : mName(aName) {}

  NS_IMETHOD
  BlockShutdown(nsIAsyncShutdownClient* aProfileBeforeChange) override = 0;

  NS_IMETHOD GetName(nsAString& aName) override
  {
    aName = mName;
    return NS_OK;
  }

  NS_IMETHOD GetState(nsIPropertyBag**) override
  {
    return NS_OK;
  }

  NS_DECL_ISUPPORTS
protected:
  virtual ~ShutdownBlocker() {}
private:
  const nsString mName;
};

class ShutdownTicket final
{
public:
  explicit ShutdownTicket(nsIAsyncShutdownBlocker* aBlocker) : mBlocker(aBlocker) {}
  NS_INLINE_DECL_REFCOUNTING(ShutdownTicket)
private:
  ~ShutdownTicket()
  {
    nsCOMPtr<nsIAsyncShutdownClient> barrier = GetShutdownBarrier();
    barrier->RemoveBlocker(mBlocker);
  }

  nsCOMPtr<nsIAsyncShutdownBlocker> mBlocker;
};

/**
 * Await convenience methods to block until the promise has been resolved or
 * rejected. The Resolve/Reject functions, while called on a different thread,
 * would be running just as on the current thread thanks to the memory barrier
 * provided by the monitor.
 * For now Await can only be used with an exclusive MozPromise if passed a
 * Resolve/Reject function.
 * Await() can *NOT* be called from a task queue/nsISerialEventTarget used for
 * resolving/rejecting aPromise, otherwise things will deadlock.
 */
template<typename ResolveValueType,
         typename RejectValueType,
         typename ResolveFunction,
         typename RejectFunction>
void
Await(
  already_AddRefed<nsIEventTarget> aPool,
  RefPtr<MozPromise<ResolveValueType, RejectValueType, true>> aPromise,
  ResolveFunction&& aResolveFunction,
  RejectFunction&& aRejectFunction)
{
  RefPtr<TaskQueue> taskQueue =
    new TaskQueue(std::move(aPool), "MozPromiseAwait");
  Monitor mon(__func__);
  bool done = false;

  aPromise->Then(taskQueue,
                 __func__,
                 [&](ResolveValueType&& aResolveValue) {
                   MonitorAutoLock lock(mon);
                   aResolveFunction(std::forward<ResolveValueType>(aResolveValue));
                   done = true;
                   mon.Notify();
                 },
                 [&](RejectValueType&& aRejectValue) {
                   MonitorAutoLock lock(mon);
                   aRejectFunction(std::forward<RejectValueType>(aRejectValue));
                   done = true;
                   mon.Notify();
                 });

  MonitorAutoLock lock(mon);
  while (!done) {
    mon.Wait();
  }
}

template<typename ResolveValueType, typename RejectValueType, bool Excl>
typename MozPromise<ResolveValueType, RejectValueType, Excl>::
  ResolveOrRejectValue
Await(already_AddRefed<nsIEventTarget> aPool,
      RefPtr<MozPromise<ResolveValueType, RejectValueType, Excl>> aPromise)
{
  RefPtr<TaskQueue> taskQueue =
    new TaskQueue(std::move(aPool), "MozPromiseAwait");
  Monitor mon(__func__);
  bool done = false;

  typename MozPromise<ResolveValueType, RejectValueType, Excl>::ResolveOrRejectValue val;
  aPromise->Then(taskQueue,
                 __func__,
                 [&](ResolveValueType aResolveValue) {
                   val.SetResolve(std::move(aResolveValue));
                   MonitorAutoLock lock(mon);
                   done = true;
                   mon.Notify();
                 },
                 [&](RejectValueType aRejectValue) {
                   val.SetReject(std::move(aRejectValue));
                   MonitorAutoLock lock(mon);
                   done = true;
                   mon.Notify();
                 });

  MonitorAutoLock lock(mon);
  while (!done) {
    mon.Wait();
  }

  return val;
}

/**
 * Similar to Await, takes an array of promises of the same type.
 * MozPromise::All is used to handle the resolution/rejection of the promises.
 */
template<typename ResolveValueType,
         typename RejectValueType,
         typename ResolveFunction,
         typename RejectFunction>
void
AwaitAll(already_AddRefed<nsIEventTarget> aPool,
         nsTArray<RefPtr<MozPromise<ResolveValueType, RejectValueType, true>>>&
           aPromises,
         ResolveFunction&& aResolveFunction,
         RejectFunction&& aRejectFunction)
{
  typedef MozPromise<ResolveValueType, RejectValueType, true> Promise;
  RefPtr<nsIEventTarget> pool = aPool;
  RefPtr<TaskQueue> taskQueue =
    new TaskQueue(do_AddRef(pool), "MozPromiseAwaitAll");
  RefPtr<typename Promise::AllPromiseType> p =
    Promise::All(taskQueue, aPromises);
  Await(
    pool.forget(), p, std::move(aResolveFunction), std::move(aRejectFunction));
}

// Note: only works with exclusive MozPromise, as Promise::All would attempt
// to perform copy of nsTArrays which are disallowed.
template<typename ResolveValueType, typename RejectValueType>
typename MozPromise<ResolveValueType,
                    RejectValueType,
                    true>::AllPromiseType::ResolveOrRejectValue
AwaitAll(already_AddRefed<nsIEventTarget> aPool,
         nsTArray<RefPtr<MozPromise<ResolveValueType, RejectValueType, true>>>&
           aPromises)
{
  typedef MozPromise<ResolveValueType, RejectValueType, true> Promise;
  RefPtr<nsIEventTarget> pool = aPool;
  RefPtr<TaskQueue> taskQueue =
    new TaskQueue(do_AddRef(pool), "MozPromiseAwaitAll");
  RefPtr<typename Promise::AllPromiseType> p =
    Promise::All(taskQueue, aPromises);
  return Await(pool.forget(), p);
}

} // namespace media
} // namespace mozilla

#endif // mozilla_MediaUtils_h

Coverage Report

Created: 2018-09-25 14:53

Line	Count	Source (jump to first uncovered line)
1		/* -- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -- */
2		/* vim: set sw=2 ts=8 et ft=cpp : */
3		/* This Source Code Form is subject to the terms of the Mozilla Public
4		* License, v. 2.0. If a copy of the MPL was not distributed with this file,
5		* You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7		#ifndef mozilla_MediaUtils_h
8		#define mozilla_MediaUtils_h
9
10		#include "mozilla/Assertions.h"
11		#include "mozilla/Monitor.h"
12		#include "mozilla/MozPromise.h"
13		#include "mozilla/RefPtr.h"
14		#include "mozilla/SharedThreadPool.h"
15		#include "mozilla/TaskQueue.h"
16		#include "mozilla/UniquePtr.h"
17		#include "nsCOMPtr.h"
18		#include "nsIAsyncShutdown.h"
19		#include "nsISupportsImpl.h"
20		#include "nsThreadUtils.h"
21
22		class nsIEventTarget;
23
24		namespace mozilla {
25		namespace media {
26
27		/*
28		* media::Pledge - A promise-like pattern for c++ that takes lambda functions.
29		*
30		* Asynchronous APIs that proxy to another thread or to the chrome process and
31		* back may find it useful to return a pledge to callers who then use
32		* pledge.Then(func) to specify a lambda function to be invoked with the result
33		* later back on this same thread.
34		*
35		* Callers will enjoy that lambdas allow "capturing" of local variables, much
36		* like closures in JavaScript (safely by-copy by default).
37		*
38		* Callers will also enjoy that they do not need to be thread-safe (their code
39		* runs on the same thread after all).