michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: #ifndef BASE_OBSERVER_LIST_THREADSAFE_H_
michael@0: #define BASE_OBSERVER_LIST_THREADSAFE_H_
michael@0: 
michael@0: #include <vector>
michael@0: #include <algorithm>
michael@0: 
michael@0: #include "base/basictypes.h"
michael@0: #include "base/logging.h"
michael@0: #include "base/message_loop.h"
michael@0: #include "base/observer_list.h"
michael@0: #include "base/ref_counted.h"
michael@0: #include "base/task.h"
michael@0: 
michael@0: namespace base {
michael@0: 
michael@0: ///////////////////////////////////////////////////////////////////////////////
michael@0: //
michael@0: // OVERVIEW:
michael@0: //
michael@0: //   A thread-safe container for a list of observers.
michael@0: //   This is similar to the observer_list (see observer_list.h), but it
michael@0: //   is more robust for multi-threaded situations.
michael@0: //
michael@0: //   The following use cases are supported:
michael@0: //    * Observers can register for notifications from any thread.
michael@0: //      Callbacks to the observer will occur on the same thread where
michael@0: //      the observer initially called AddObserver() from.
michael@0: //    * Any thread may trigger a notification via NOTIFY_OBSERVERS.
michael@0: //    * Observers can remove themselves from the observer list inside
michael@0: //      of a callback.
michael@0: //    * If one thread is notifying observers concurrently with an observer
michael@0: //      removing itself from the observer list, the notifications will
michael@0: //      be silently dropped.
michael@0: //
michael@0: //   The drawback of the threadsafe observer list is that notifications
michael@0: //   are not as real-time as the non-threadsafe version of this class.
michael@0: //   Notifications will always be done via PostTask() to another thread,
michael@0: //   whereas with the non-thread-safe observer_list, notifications happen
michael@0: //   synchronously and immediately.
michael@0: //
michael@0: //   IMPLEMENTATION NOTES
michael@0: //   The ObserverListThreadSafe maintains an ObserverList for each thread
michael@0: //   which uses the ThreadSafeObserver.  When Notifying the observers,
michael@0: //   we simply call PostTask to each registered thread, and then each thread
michael@0: //   will notify its regular ObserverList.
michael@0: //
michael@0: ///////////////////////////////////////////////////////////////////////////////
michael@0: template <class ObserverType>
michael@0: class ObserverListThreadSafe
michael@0:     : public base::RefCountedThreadSafe<ObserverListThreadSafe<ObserverType> > {
michael@0:  public:
michael@0:   ObserverListThreadSafe() {}
michael@0: 
michael@0:   ~ObserverListThreadSafe() {
michael@0:     typename ObserversListMap::const_iterator it;
michael@0:     for (it = observer_lists_.begin(); it != observer_lists_.end(); ++it)
michael@0:       delete (*it).second;
michael@0:     observer_lists_.clear();
michael@0:   }
michael@0: 
michael@0:   // Add an observer to the list.
michael@0:   void AddObserver(ObserverType* obs) {
michael@0:     ObserverList<ObserverType>* list = NULL;
michael@0:     MessageLoop* loop = MessageLoop::current();
michael@0:     // TODO(mbelshe): Get rid of this check.  Its needed right now because
michael@0:     //                Time currently triggers usage of the ObserverList.
michael@0:     //                And unittests use time without a MessageLoop.
michael@0:     if (!loop)
michael@0:       return;  // Some unittests may access this without a message loop.
michael@0:     {
michael@0:       AutoLock lock(list_lock_);
michael@0:       if (observer_lists_.find(loop) == observer_lists_.end())
michael@0:         observer_lists_[loop] = new ObserverList<ObserverType>();
michael@0:       list = observer_lists_[loop];
michael@0:     }
michael@0:     list->AddObserver(obs);
michael@0:   }
michael@0: 
michael@0:   // Remove an observer from the list.
michael@0:   // If there are pending notifications in-transit to the observer, they will
michael@0:   // be aborted.
michael@0:   // RemoveObserver MUST be called from the same thread which called
michael@0:   // AddObserver.
michael@0:   void RemoveObserver(ObserverType* obs) {
michael@0:     ObserverList<ObserverType>* list = NULL;
michael@0:     MessageLoop* loop = MessageLoop::current();
michael@0:     if (!loop)
michael@0:       return;  // On shutdown, it is possible that current() is already null.
michael@0:     {
michael@0:       AutoLock lock(list_lock_);
michael@0:       list = observer_lists_[loop];
michael@0:       if (!list) {
michael@0:         NOTREACHED() << "RemoveObserver called on for unknown thread";
michael@0:         return;
michael@0:       }
michael@0: 
michael@0:       // If we're about to remove the last observer from the list,
michael@0:       // then we can remove this observer_list entirely.
michael@0:       if (list->size() == 1)
michael@0:         observer_lists_.erase(loop);
michael@0:     }
michael@0:     list->RemoveObserver(obs);
michael@0: 
michael@0:     // If RemoveObserver is called from a notification, the size will be
michael@0:     // nonzero.  Instead of deleting here, the NotifyWrapper will delete
michael@0:     // when it finishes iterating.
michael@0:     if (list->size() == 0)
michael@0:       delete list;
michael@0:   }
michael@0: 
michael@0:   // Notify methods.
michael@0:   // Make a thread-safe callback to each Observer in the list.
michael@0:   // Note, these calls are effectively asynchronous.  You cannot assume
michael@0:   // that at the completion of the Notify call that all Observers have
michael@0:   // been Notified.  The notification may still be pending delivery.
michael@0:   template <class Method>
michael@0:   void Notify(Method m) {
michael@0:     UnboundMethod<ObserverType, Method, Tuple0> method(m, MakeTuple());
michael@0:     Notify<Method, Tuple0>(method);
michael@0:   }
michael@0: 
michael@0:   template <class Method, class A>
michael@0:   void Notify(Method m, const A &a) {
michael@0:     UnboundMethod<ObserverType, Method, Tuple1<A> > method(m, MakeTuple(a));
michael@0:     Notify<Method, Tuple1<A> >(method);
michael@0:   }
michael@0: 
michael@0:   // TODO(mbelshe):  Add more wrappers for Notify() with more arguments.
michael@0: 
michael@0:  private:
michael@0:   template <class Method, class Params>
michael@0:   void Notify(const UnboundMethod<ObserverType, Method, Params>& method) {
michael@0:     AutoLock lock(list_lock_);
michael@0:     typename ObserversListMap::iterator it;
michael@0:     for (it = observer_lists_.begin(); it != observer_lists_.end(); ++it) {
michael@0:       MessageLoop* loop = (*it).first;
michael@0:       ObserverList<ObserverType>* list = (*it).second;
michael@0:       loop->PostTask(FROM_HERE,
michael@0:           NewRunnableMethod(this,
michael@0:               &ObserverListThreadSafe<ObserverType>::
michael@0:                  template NotifyWrapper<Method, Params>, list, method));
michael@0:     }
michael@0:   }
michael@0: 
michael@0:   // Wrapper which is called to fire the notifications for each thread's
michael@0:   // ObserverList.  This function MUST be called on the thread which owns
michael@0:   // the unsafe ObserverList.
michael@0:   template <class Method, class Params>
michael@0:   void NotifyWrapper(ObserverList<ObserverType>* list,
michael@0:       const UnboundMethod<ObserverType, Method, Params>& method) {
michael@0: 
michael@0:     // Check that this list still needs notifications.
michael@0:     {
michael@0:       AutoLock lock(list_lock_);
michael@0:       typename ObserversListMap::iterator it =
michael@0:           observer_lists_.find(MessageLoop::current());
michael@0: 
michael@0:       // The ObserverList could have been removed already.  In fact, it could
michael@0:       // have been removed and then re-added!  If the master list's loop
michael@0:       // does not match this one, then we do not need to finish this
michael@0:       // notification.
michael@0:       if (it == observer_lists_.end() || it->second != list)
michael@0:         return;
michael@0:     }
michael@0: 
michael@0:     {
michael@0:       typename ObserverList<ObserverType>::Iterator it(*list);
michael@0:       ObserverType* obs;
michael@0:       while ((obs = it.GetNext()) != NULL)
michael@0:         method.Run(obs);
michael@0:     }
michael@0: 
michael@0:     // If there are no more observers on the list, we can now delete it.
michael@0:     if (list->size() == 0) {
michael@0: #ifndef NDEBUG
michael@0:       {
michael@0:         AutoLock lock(list_lock_);
michael@0:         // Verify this list is no longer registered.
michael@0:         typename ObserversListMap::iterator it =
michael@0:             observer_lists_.find(MessageLoop::current());
michael@0:         DCHECK(it == observer_lists_.end() || it->second != list);
michael@0:       }
michael@0: #endif
michael@0:       delete list;
michael@0:     }
michael@0:   }
michael@0: 
michael@0:   typedef std::map<MessageLoop*, ObserverList<ObserverType>*> ObserversListMap;
michael@0: 
michael@0:   // These are marked mutable to facilitate having NotifyAll be const.
michael@0:   Lock list_lock_;  // Protects the observer_lists_.
michael@0:   ObserversListMap observer_lists_;
michael@0: 
michael@0:   DISALLOW_EVIL_CONSTRUCTORS(ObserverListThreadSafe);
michael@0: };
michael@0: 
michael@0: } // namespace base
michael@0: 
michael@0: #endif  // BASE_OBSERVER_LIST_THREADSAFE_H_