Implementation of AIFrameTimer.

indra/llcommon/aiframetimer.h

@@ -32,23 +32,108 @@
 #define AIFRAMETIMER_H
 
 #include "llframetimer.h"
+#include "llthread.h"
+#include <boost/signals2.hpp>
+#include <set>
 
 class LL_COMMON_API AIFrameTimer
 {
-  private:
-	F64 mExpire;								// Time at which the timer expires, in seconds since application start (compared to LLFrameTimer::sFrameTime).
-	static std::set<AIFrameTimer> sTimerList;	// List with all running timers.
+  protected:
+	typedef boost::signals2::signal<void (void)> signal_type;
 
-	friend class LLFrameTimer;
+  private:
+	// Use separate struct for this object because it is non-copyable.
+	struct Signal {
+		signal_type mSignal;
+	};
+
+	// Notes on Thread-Safety
+	//
+	// This is the type of the objects stored in AIFrameTimer::sTimerList, and as such leans
+	// for it's thread-safety on the same lock as is used for that std::multiset as follows.
+	// An arbitrary thread can create, insert and initialize this object. Other threads can
+	// not access it until that has completed.
+	//
+	// After creation two threads can access it: the thread that created it (owns the
+	// AIFrameTimer object, which has an mHandle that points to this object), or the main
+	// thread by finding it in sTimerList.
+	//
+	// See aiframetimer.cpp for more notes.
+	class AIRunningFrameTimer {
+	  private:
+		F64 mExpire;							// Time at which the timer expires, in seconds since application start (compared to LLFrameTimer::sFrameTime).
+		Signal* mCallback;
+		AIFrameTimer* mTimer;
+
+	  public:
+		AIRunningFrameTimer(F64 expiration, AIFrameTimer* timer) : mExpire(LLFrameTimer::getElapsedSeconds() + expiration), mCallback(new Signal), mTimer(timer) { }
+		~AIRunningFrameTimer() { delete mCallback; }
+		void init(signal_type::slot_type const& slot) const { mCallback->mSignal.connect(slot); }
+
+		friend bool operator<(AIRunningFrameTimer const& ft1, AIRunningFrameTimer const& ft2) { return ft1.mExpire < ft2.mExpire; }
+
+		void do_callback(void) const { mCallback->mSignal(); }
+		F64 expiration(void) const { return mExpire; }
+		AIFrameTimer* getTimer(void) const { return mTimer; }
+	};
+
+	typedef std::multiset<AIRunningFrameTimer> timer_list_type;
+
+	static LLMutex sMutex;						// Mutex for the two global variables below.
+	static timer_list_type sTimerList;			// List with all running timers.
 	static F64 sNextExpiration;					// Cache of smallest value in sTimerList.
+	friend class LLFrameTimer;					// Access to sNextExpiration.
+
+	class Handle {
+	  public:
+		timer_list_type::iterator mRunningTimer;	// Points to the running timer, or to sTimerList.end() when not running.
+													// Access to this iterator is protected by the AIFrameTimer::sMutex!
+		LLMutex mMutex;								// A mutex used to protect us from deletion of the callback object while
+													// calling the callback function in the case of simultaneous expiration
+													// and cancellation by the thread owning the AIFrameTimer (by calling
+													// AIFrameTimer::cancel).
+
+		// Construction for a not-running timer.
+		Handle(void) : mRunningTimer(sTimerList.end()) { }
+
+		// Actual initialization used by AIFrameTimer::create.
+		void init(timer_list_type::iterator const& running_timer, signal_type::slot_type const& slot)
+		{
+		  // Locking AIFrameTimer::sMutex is not neccessary here, because we're creating
+		  // the object and no other thread knows of mRunningTimer at this point.
+		  mRunningTimer = running_timer;
+		  mRunningTimer->init(slot);
+		}
+
+	  private:
+		// LLMutex has no assignment operator.
+	  	Handle& operator=(Handle const&) { return *this; }
+	};
+
+	Handle mHandle;
 
   public:
-	AIFrameTimer(F64 expiration) : mExpire(LLFrameTimer::getElapsedSeconds() + expiration) { }
+	// Construct an AIFrameTimer that is not initialized.
+	//
+	// The call to end() is deliberately not put inside a critical area because it's a read-only
+	// operation on something that is never written to while there are threads.
+	AIFrameTimer(void) { }
 
+	// Construction of a running AIFrameTimer with expiration time expiration in seconds, and callback slot.
+	AIFrameTimer(F64 expiration, signal_type::slot_type const& slot) { create(expiration, slot); }
+
+	// Destructing the AIFrameTimer object terminates the running timer (if still running).
+	// Note that cancel() must have returned BEFORE anything is destructed that would disallow the callback function to be called.
+	// So, if the AIFrameTimer is a member of an object whose callback function is called then cancel() has
+	// be called manually (or from the destructor of THAT object), before that object is destructed.
+	// Cancel may be called multiple times.
+	~AIFrameTimer() { cancel(); }
+
+	void create(F64 expiration, signal_type::slot_type const& slot);
+	void cancel(void);
+
+  protected:
 	static void handleExpiration(F64 current_frame_time);
-
-	friend bool operator<(AIFrameTimer const& ft1, AIFrameTimer const& ft2) { return ft1.mExpire < ft2.mExpire; }
 };
 
-
 #endif