Documented the class. Do() now gets a pointer to the event queue as parameter.

git-svn-id: file:///srv/svn/repos/haiku/trunk/current@1514 a95241bf-73f2-0310-859d-f6bbb57e9c96

src/servers/registrar/Event.cpp

@@ -27,7 +27,34 @@
 
 #include "Event.h"
 
+/*!	\class Event
+	\brief Base class for events as handled by EventQueue.
+
+	Event features methods to set and get the event time and the "auto delete"
+	flag, and a Do() method invoked, when the event is executed.
+
+	If the "auto delete" flag is set to \c true, the event is deleted by the
+	event queue after it has been executed. The same happens, if Do() returns
+	\c true.
+*/
+
+/*!	\var bigtime_t Event::fTime
+	\brief The event time.
+*/
+
+/*!	\var bool Event::fAutoDelete
+	\brief The "auto delete" flag.
+*/
+
 // constructor
+/*!	\brief Creates a new event.
+
+	The event time is initialized to 0. That is, it should be set before
+	pushing the event into an event queue.
+
+	\param autoDelete Specifies whether the object shall automatically be
+		   deleted by the event queue after being executed.
+*/
 Event::Event(bool autoDelete)
 	: fTime(0),
 	  fAutoDelete(autoDelete)
@@ -35,6 +62,11 @@ Event::Event(bool autoDelete)
 }
 
 // constructor
+/*!	\brief Creates a new event.
+	\param time Time when the event shall be executed.
+	\param autoDelete Specifies whether the object shall automatically be
+		   deleted by the event queue after being executed.
+*/
 Event::Event(bigtime_t time, bool autoDelete)
 	: fTime(time),
 	  fAutoDelete(autoDelete)
@@ -42,11 +74,22 @@ Event::Event(bigtime_t time, bool autoDelete)
 }
 
 // destructor
+/*!	\brief Frees all resources associated with the object.
+
+	Does nothing.
+*/
 Event::~Event()
 {
 }
 
 // SetTime
+/*!	\brief Sets a new event time.
+
+	\note You must not call this method, when the event is in an event queue.
+		  Use EventQueue::ModifyEvent() instead.
+
+	\param time The new event time.
+*/
 void
 Event::SetTime(bigtime_t time)
 {
@@ -54,6 +97,9 @@ Event::SetTime(bigtime_t time)
 }
 
 // Time
+/*!	\brief Returns the time of the event.
+	\return Returns the time of the event.
+*/
 bigtime_t
 Event::Time() const
 {
@@ -61,6 +107,10 @@ Event::Time() const
 }
 
 // SetAutoDelete
+/*!	\brief Sets whether the event shall be deleted after execution.
+	\param autoDelete Specifies whether the object shall automatically be
+		   deleted by the event queue after being executed.
+*/
 void
 Event::SetAutoDelete(bool autoDelete)
 {
@@ -68,6 +118,10 @@ Event::SetAutoDelete(bool autoDelete)
 }
 
 // IsAutoDelete
+/*!	\brief Returns whether the event shall be deleted after execution.
+	\return Returns whether the object shall automatically be
+			deleted by the event queue after being executed.
+*/
 bool
 Event::IsAutoDelete() const
 {
@@ -75,8 +129,43 @@ Event::IsAutoDelete() const
 }
 
 // Do
+/*!	\brief Hook method invoked when the event time has arrived.
+
+	To be overridden by derived classes. As the method is executed in the
+	event queue's timer thread, the execution of the method should take
+	as little time as possible to keep the event queue precise.
+
+	The return value of this method indicates whether the event queue shall
+	delete the object. This does not override the IsAutoDelete() value. If
+	IsAutoDelete() is \c true, then the object is deleted regardless of this
+	method's return value, but if IsAutoDelete() is \c false, this method's
+	return value is taken into consideration. To be precise the logical OR
+	of IsAutoDelete() and the return value of Do() specifies whether the
+	object shall be deleted. The reason for this handling is that there are
+	usally two kind of events: "one-shot" events and those that are reused
+	periodically or from time to time. The first kind can simply be
+	constructed with "auto delete" set to \c true and doesn't need to care
+	about Do()'s return value. The second kind shall usually not be deleted,
+	but during the execution of Do() it might turn out, that it the would be
+	a good idea to let it be deleted by the event queue.
+	BTW, the event may as well delete itself in Do(); that is not a very
+	nice practice though.
+
+	\note IsAutoDelete() is checked by the event queue before Do() is invoked.
+		  Thus changing it in Do() won't have any effect.
+
+	If it is not deleted, the event can re-push itself into the queue
+	within Do().
+
+	\note The event queue is not locked when this method is invoked and it
+		  doesn't contain the event anymore.
+
+	\param queue The event queue executing the event.
+	\return \c true, if the event shall be deleted by the event queue,
+			\c false, if IsAutoDelete() shall be checked for this decision.
+*/
 bool
-Event::Do()
+Event::Do(EventQueue *queue)
 {
 	return fAutoDelete;
 }

src/servers/registrar/Event.h

@@ -30,6 +30,8 @@
 
 #include <OS.h>
 
+class EventQueue;
+
 class Event {
 public:
 	Event(bool autoDelete = true);
@@ -42,7 +44,7 @@ public:
 	void SetAutoDelete(bool autoDelete);
 	bool IsAutoDelete() const;
 
-	virtual	bool Do();
+	virtual	bool Do(EventQueue *queue);
 
  private:
 	bigtime_t		fTime;