michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* vim:set ts=2 sw=2 sts=2 et cindent: */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #if !defined(MediaShutdownManager_h_)
michael@0: #define MediaShutdownManager_h_
michael@0: 
michael@0: #include "nsIObserver.h"
michael@0: #include "mozilla/Monitor.h"
michael@0: #include "mozilla/RefPtr.h"
michael@0: #include "mozilla/StaticPtr.h"
michael@0: #include "nsIThread.h"
michael@0: #include "nsCOMPtr.h"
michael@0: #include "nsTHashtable.h"
michael@0: #include "nsHashKeys.h"
michael@0: 
michael@0: namespace mozilla {
michael@0: 
michael@0: class MediaDecoder;
michael@0: class StateMachineThread;
michael@0: 
michael@0: // The MediaShutdownManager manages shutting down the MediaDecoder
michael@0: // infrastructure in response to an xpcom-shutdown notification. This happens
michael@0: // when Gecko is shutting down in the middle of operation. This is tricky, as
michael@0: // there are a number of moving parts that must be shutdown in a particular
michael@0: // order. Additionally the xpcom-shutdown observer *must* block until all
michael@0: // threads are shutdown, which is tricky since we have a number of threads
michael@0: // here and their shutdown is asynchronous. We can't have each element of
michael@0: // our pipeline listening for xpcom-shutdown, as if each observer blocks
michael@0: // waiting for its threads to shutdown it will block other xpcom-shutdown
michael@0: // notifications from firing, and shutdown of one part of the media pipeline
michael@0: // (say the State Machine thread) may depend another part to be shutdown
michael@0: // first (the MediaDecoder threads). The MediaShutdownManager encapsulates
michael@0: // all these dependencies, and provides a single xpcom-shutdown listener
michael@0: // for the MediaDecoder infrastructure, to ensure that no shutdown order
michael@0: // dependencies leak out of the MediaDecoder stack. The MediaShutdownManager
michael@0: // is a singleton.
michael@0: //
michael@0: // The MediaShutdownManager ensures that the MediaDecoder stack is shutdown
michael@0: // before returning from its xpcom-shutdown observer by keeping track of all
michael@0: // the active MediaDecoders, and upon xpcom-shutdown calling Shutdown() on
michael@0: // every MediaDecoder and then spinning the main thread event loop until all
michael@0: // SharedThreadPools have shutdown. Once the SharedThreadPools are shutdown,
michael@0: // all the state machines and their threads have been shutdown, the
michael@0: // xpcom-shutdown observer returns.
michael@0: //
michael@0: // Note that calling the Unregister() functions may result in the singleton
michael@0: // being deleted, so don't store references to the singleton, always use the
michael@0: // singleton by derefing the referenced returned by
michael@0: // MediaShutdownManager::Instance(), which ensures that the singleton is
michael@0: // created when needed.
michael@0: // i.e. like this:
michael@0: //    MediaShutdownManager::Instance()::Unregister(someDecoder);
michael@0: //    MediaShutdownManager::Instance()::Register(someOtherDecoder);
michael@0: // Not like this:
michael@0: //  MediaShutdownManager& instance = MediaShutdownManager::Instance();
michael@0: //  instance.Unregister(someDecoder); // Warning! May delete instance!
michael@0: //  instance.Register(someOtherDecoder); // BAD! instance may be dangling!
michael@0: class MediaShutdownManager : public nsIObserver {
michael@0: public:
michael@0:   NS_DECL_ISUPPORTS
michael@0:   NS_DECL_NSIOBSERVER
michael@0: 
michael@0:   // The MediaShutdownManager is a singleton, access its instance with
michael@0:   // this accessor.
michael@0:   static MediaShutdownManager& Instance();
michael@0: 
michael@0:   // Notifies the MediaShutdownManager that it needs to track the shutdown
michael@0:   // of this MediaDecoder.
michael@0:   void Register(MediaDecoder* aDecoder);
michael@0: 
michael@0:   // Notifies the MediaShutdownManager that a MediaDecoder that it was
michael@0:   // tracking has shutdown, and it no longer needs to be shutdown in the
michael@0:   // xpcom-shutdown listener.
michael@0:   void Unregister(MediaDecoder* aDecoder);
michael@0: 
michael@0: private:
michael@0: 
michael@0:   MediaShutdownManager();
michael@0:   virtual ~MediaShutdownManager();
michael@0: 
michael@0:   void Shutdown();
michael@0: 
michael@0:   // Ensures we have a shutdown listener if we need one, and removes the
michael@0:   // listener and destroys the singleton if we don't.
michael@0:   void EnsureCorrectShutdownObserverState();
michael@0: 
michael@0:   static StaticRefPtr<MediaShutdownManager> sInstance;
michael@0: 
michael@0:   // References to the MediaDecoder. The decoders unregister themselves
michael@0:   // in their Shutdown() method, so we'll drop the reference naturally when
michael@0:   // we're shutting down (in the non xpcom-shutdown case).
michael@0:   nsTHashtable<nsRefPtrHashKey<MediaDecoder>> mDecoders;
michael@0: 
michael@0:   // True if we have an XPCOM shutdown observer.
michael@0:   bool mIsObservingShutdown;
michael@0: 
michael@0:   bool mIsDoingXPCOMShutDown;
michael@0: };
michael@0: 
michael@0: } // namespace mozilla
michael@0: 
michael@0: #endif