Source code
Revision control
Copy as Markdown
Other Tools
/* 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
#ifndef mozilla_media_mediaelementeventrunners_h
#define mozilla_media_mediaelementeventrunners_h
#include "mozilla/dom/PlayPromise.h"
#include "nsCycleCollectionParticipant.h"
#include "nsIContent.h"
#include "nsINamed.h"
#include "nsIRunnable.h"
#include "nsString.h"
#include "nsISupportsImpl.h"
#include "nsTString.h"
namespace mozilla::dom {
class HTMLMediaElement;
// Under certain conditions there may be no-one holding references to
// a media element from script, DOM parent, etc, but the element may still
// fire meaningful events in the future so we can't destroy it yet:
// 1) If the element is delaying the load event (or would be, if it were
// in a document), then events up to loadeddata or error could be fired,
// so we need to stay alive.
// 2) If the element is not paused and playback has not ended, then
// we will (or might) play, sending timeupdate and ended events and possibly
// audio output, so we need to stay alive.
// 3) if the element is seeking then we will fire seeking events and possibly
// start playing afterward, so we need to stay alive.
// 4) If autoplay could start playback in this element (if we got enough data),
// then we need to stay alive.
// 5) if the element is currently loading, not suspended, and its source is
// not a MediaSource, then script might be waiting for progress events or a
// 'stalled' or 'suspend' event, so we need to stay alive.
// If we're already suspended then (all other conditions being met),
// it's OK to just disappear without firing any more events,
// since we have the freedom to remain suspended indefinitely. Note
// that we could use this 'suspended' loophole to garbage-collect a suspended
// element in case 4 even if it had 'autoplay' set, but we choose not to.
// If someone throws away all references to a loading 'autoplay' element
// sound should still eventually play.
// 6) If the source is a MediaSource, most loading events will not fire unless
// appendBuffer() is called on a SourceBuffer, in which case something is
// already referencing the SourceBuffer, which keeps the associated media
// element alive. Further, a MediaSource will never time out the resource
// fetch, and so should not keep the media element alive if it is
// unreferenced. A pending 'stalled' event keeps the media element alive.
//
// Media elements owned by inactive documents (i.e. documents not contained in
// any document viewer) should never hold a self-reference because none of the
// above conditions are allowed: the element will stop loading and playing
// and never resume loading or playing unless its owner document changes to
// an active document (which can only happen if there is an external reference
// to the element).
// Media elements with no owner doc should be able to hold a self-reference.
// Something native must have created the element and may expect it to
// stay alive to play.
// It's very important that any change in state which could change the value of
// needSelfReference in AddRemoveSelfReference be followed by a call to
// AddRemoveSelfReference before this element could die!
// It's especially important if needSelfReference would change to 'true',
// since if we neglect to add a self-reference, this element might be
// garbage collected while there are still event listeners that should
// receive events. If we neglect to remove the self-reference then the element
// just lives longer than it needs to.
class nsMediaEventRunner : public nsIRunnable, public nsINamed {
public:
NS_DECL_CYCLE_COLLECTING_ISUPPORTS
NS_DECL_CYCLE_COLLECTION_CLASS_AMBIGUOUS(nsMediaEventRunner, nsIRunnable)
explicit nsMediaEventRunner(const nsAString& aName,
HTMLMediaElement* aElement,
const nsAString& aEventName = u"unknown"_ns);
void Cancel() { mElement = nullptr; }
NS_IMETHODIMP GetName(nsACString& aName) override {
aName = NS_ConvertUTF16toUTF8(mName).get();
return NS_OK;
}
nsString Name() const { return mName; }
nsString EventName() const { return mEventName; }
protected:
virtual ~nsMediaEventRunner() = default;
bool IsCancelled();
nsresult DispatchEvent(const nsAString& aName);
RefPtr<HTMLMediaElement> mElement;
nsString mName;
nsString mEventName;
uint32_t mLoadID;
};
/**
* This runner is used to dispatch async event on media element.
*/
class nsAsyncEventRunner : public nsMediaEventRunner {
public:
nsAsyncEventRunner(const nsAString& aEventName, HTMLMediaElement* aElement)
: nsMediaEventRunner(u"nsAsyncEventRunner"_ns, aElement, aEventName) {}
NS_IMETHOD Run() override;
};
/**
* These runners are used to handle `playing` event and address play promise.
*
* If no error is passed while constructing an instance, the instance will
* resolve the passed promises with undefined; otherwise, the instance will
* reject the passed promises with the passed error.
*
* The constructor appends the constructed instance into the passed media
* element's mPendingPlayPromisesRunners member and once the the runner is run
* (whether fulfilled or canceled), it removes itself from
* mPendingPlayPromisesRunners.
*/
class nsResolveOrRejectPendingPlayPromisesRunner : public nsMediaEventRunner {
public:
NS_DECL_ISUPPORTS_INHERITED
NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(
nsResolveOrRejectPendingPlayPromisesRunner, nsMediaEventRunner)
nsResolveOrRejectPendingPlayPromisesRunner(
HTMLMediaElement* aElement, nsTArray<RefPtr<PlayPromise>>&& aPromises,
nsresult aError = NS_OK);
void ResolveOrReject();
NS_IMETHOD Run() override;
protected:
virtual ~nsResolveOrRejectPendingPlayPromisesRunner() = default;
private:
nsTArray<RefPtr<PlayPromise>> mPromises;
nsresult mError;
};
class nsNotifyAboutPlayingRunner
: public nsResolveOrRejectPendingPlayPromisesRunner {
public:
nsNotifyAboutPlayingRunner(
HTMLMediaElement* aElement,
nsTArray<RefPtr<PlayPromise>>&& aPendingPlayPromises)
: nsResolveOrRejectPendingPlayPromisesRunner(
aElement, std::move(aPendingPlayPromises)) {}
NS_IMETHOD Run() override;
};
/**
* This runner is used to dispatch a source error event, which would happen when
* loading resource failed.
*/
class nsSourceErrorEventRunner : public nsMediaEventRunner {
public:
NS_DECL_ISUPPORTS_INHERITED
NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(nsSourceErrorEventRunner,
nsMediaEventRunner)
nsSourceErrorEventRunner(HTMLMediaElement* aElement, nsIContent* aSource)
: nsMediaEventRunner(u"nsSourceErrorEventRunner"_ns, aElement),
mSource(aSource) {}
NS_IMETHOD Run() override;
private:
virtual ~nsSourceErrorEventRunner() = default;
nsCOMPtr<nsIContent> mSource;
};
/**
* This runner is used to dispatch `timeupdate` event and ensure we don't
* dispatch `timeupdate` more often than once per `TIMEUPDATE_MS` if that is not
* a mandatory event.
*/
class nsTimeupdateRunner : public nsMediaEventRunner {
public:
nsTimeupdateRunner(HTMLMediaElement* aElement, bool aIsMandatory)
: nsMediaEventRunner(u"nsTimeupdateRunner"_ns, aElement,
u"timeupdate"_ns),
mIsMandatory(aIsMandatory) {}
NS_IMETHOD Run() override;
private:
bool ShouldDispatchTimeupdate() const;
bool mIsMandatory;
};
} // namespace mozilla::dom
#endif // mozilla_media_mediaelementeventrunners_h