src/servers/registrar/Event.cpp

   1 //------------------------------------------------------------------------------
   2 //      Copyright (c) 2001-2002, OpenBeOS
   3 //
   4 //      Permission is hereby granted, free of charge, to any person obtaining a
   5 //      copy of this software and associated documentation files (the "Software"),
   6 //      to deal in the Software without restriction, including without limitation
   7 //      the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8 //      and/or sell copies of the Software, and to permit persons to whom the
   9 //      Software is furnished to do so, subject to the following conditions:
  10 //
  11 //      The above copyright notice and this permission notice shall be included in
  12 //      all copies or substantial portions of the Software.
  13 //
  14 //      THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 //      IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 //      FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  17 //      AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18 //      LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19 //      FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  20 //      DEALINGS IN THE SOFTWARE.
  21 //
  22 //      File Name:              Event.cpp
  23 //      Author:                 Ingo Weinhold (bonefish@users.sf.net)
  24 //                                      YellowBites (http://www.yellowbites.com)
  25 //      Description:    Base class for events as handled by EventQueue.
  26 //------------------------------------------------------------------------------
  27
  28 #include "Event.h"
  29
  30 /*!     \class Event
  31         \brief Base class for events as handled by EventQueue.
  32
  33         Event features methods to set and get the event time and the "auto delete"
  34         flag, and a Do() method invoked, when the event is executed.
  35
  36         If the "auto delete" flag is set to \c true, the event is deleted by the
  37         event queue after it has been executed. The same happens, if Do() returns
  38         \c true.
  39 */
  40
  41 /*!     \var bigtime_t Event::fTime
  42         \brief The event time.
  43 */
  44
  45 /*!     \var bool Event::fAutoDelete
  46         \brief The "auto delete" flag.
  47 */
  48
  49 // constructor
  50 /*!     \brief Creates a new event.
  51
  52         The event time is initialized to 0. That is, it should be set before
  53         pushing the event into an event queue.
  54
  55         \param autoDelete Specifies whether the object shall automatically be
  56                    deleted by the event queue after being executed.
  57 */
  58 Event::Event(bool autoDelete)
  59         : fTime(0),
  60           fAutoDelete(autoDelete)
  61 {
  62 }
  63
  64 // constructor
  65 /*!     \brief Creates a new event.
  66         \param time Time when the event shall be executed.
  67         \param autoDelete Specifies whether the object shall automatically be
  68                    deleted by the event queue after being executed.
  69 */
  70 Event::Event(bigtime_t time, bool autoDelete)
  71         : fTime(time),
  72           fAutoDelete(autoDelete)
  73 {
  74 }
  75
  76 // destructor
  77 /*!     \brief Frees all resources associated with the object.
  78
  79         Does nothing.
  80 */
  81 Event::~Event()
  82 {
  83 }
  84
  85 // SetTime
  86 /*!     \brief Sets a new event time.
  87
  88         \note You must not call this method, when the event is in an event queue.
  89                   Use EventQueue::ModifyEvent() instead.
  90
  91         \param time The new event time.
  92 */
  93 void
  94 Event::SetTime(bigtime_t time)
  95 {
  96         fTime = time;
  97 }
  98
  99 // Time
 100 /*!     \brief Returns the time of the event.
 101         \return Returns the time of the event.
 102 */
 103 bigtime_t
 104 Event::Time() const
 105 {
 106         return fTime;
 107 }
 108
 109 // SetAutoDelete
 110 /*!     \brief Sets whether the event shall be deleted after execution.
 111         \param autoDelete Specifies whether the object shall automatically be
 112                    deleted by the event queue after being executed.
 113 */
 114 void
 115 Event::SetAutoDelete(bool autoDelete)
 116 {
 117         fAutoDelete = autoDelete;
 118 }
 119
 120 // IsAutoDelete
 121 /*!     \brief Returns whether the event shall be deleted after execution.
 122         \return Returns whether the object shall automatically be
 123                         deleted by the event queue after being executed.
 124 */
 125 bool
 126 Event::IsAutoDelete() const
 127 {
 128         return fAutoDelete;
 129 }
 130
 131 // Do
 132 /*!     \brief Hook method invoked when the event time has arrived.
 133
 134         To be overridden by derived classes. As the method is executed in the
 135         event queue's timer thread, the execution of the method should take
 136         as little time as possible to keep the event queue precise.
 137
 138         The return value of this method indicates whether the event queue shall
 139         delete the object. This does not override the IsAutoDelete() value. If
 140         IsAutoDelete() is \c true, then the object is deleted regardless of this
 141         method's return value, but if IsAutoDelete() is \c false, this method's
 142         return value is taken into consideration. To be precise the logical OR
 143         of IsAutoDelete() and the return value of Do() specifies whether the
 144         object shall be deleted. The reason for this handling is that there are
 145         usally two kind of events: "one-shot" events and those that are reused
 146         periodically or from time to time. The first kind can simply be
 147         constructed with "auto delete" set to \c true and doesn't need to care
 148         about Do()'s return value. The second kind shall usually not be deleted,
 149         but during the execution of Do() it might turn out, that it the would be
 150         a good idea to let it be deleted by the event queue.
 151         BTW, the event may as well delete itself in Do(); that is not a very
 152         nice practice though.
 153
 154         \note IsAutoDelete() is checked by the event queue before Do() is invoked.
 155                   Thus changing it in Do() won't have any effect.
 156
 157         If it is not deleted, the event can re-push itself into the queue
 158         within Do().
 159
 160         \note The event queue is not locked when this method is invoked and it
 161                   doesn't contain the event anymore.
 162
 163         \param queue The event queue executing the event.
 164         \return \c true, if the event shall be deleted by the event queue,
 165                         \c false, if IsAutoDelete() shall be checked for this decision.
 166 */
 167 bool
 168 Event::Do(EventQueue *queue)
 169 {
 170         return fAutoDelete;
 171 }
 172