• Immutable Page
  • Info
  • Attachments

CompTimer

The CompTimer class represents something that can be done on a specific constant timeout, or in a certain amount of time. It calls a function which returns either true or false, if false then the cycle of constantly calling that function on timeout no longer happens.

Class Definition

/**
 * A simple timer for use with invoking a CallBack during a timed duration.
 */
class CompTimer {

    public:

        typedef boost::function<bool ()> CallBack;
        
        /**
         * Empty constructor setting everything to zero and NULL.
         */
        CompTimer ();
        
        /**
         * Frees the private data for this timer and any information about it's
         * context.
         */
        ~CompTimer ();
        
        /**
         * Checks if this timer is active and will have it's CallBack invoked.
         */
        bool active ();
        unsigned int minTime ();
        unsigned int maxTime ();
        unsigned int minLeft ();
        unsigned int maxLeft ();
        
        /**
         * Sets the timing durations of this timer.
         */
        void setTimes (unsigned int min, unsigned int max = 0);
        
        /**
         * Sets the callback function to invoke for this timer. This defaults
         * to NULL.
         */
        void setCallback (CallBack callback);
        
        /**
         * Starts this timer without modifying any of it's parameters. The timer is
         * stop()'d before this occurs.
         */
        void start ();
        
        /**
         * Starts this timer setting the paramters with setTimes(). The timer is stop()'d
         * before this occurs.
         */
        void start (unsigned int min, unsigned int max = 0);
        
        /**
         * Starts this timer setting the parameters with setTimes() and setCallback(). The timer is
         * stop()'d before this occurs.
         */
        void start (CallBack callback,
                    unsigned int min, unsigned int max = 0);
        
        /**
         * Stops this timer. After this the timer should not be active() and it's CallBack shouldn't
         * be invoked.
         */
        void stop ();

        friend class CompScreen;
        friend class PrivateScreen;

    private:
        bool         mActive;
        unsigned int mMinTime;
        unsigned int mMaxTime;
        int          mMinLeft;
        int          mMaxLeft;
        CallBack     mCallBack;
};

Setting the timeout time

Both the ::setTimes (unsigned int, unsigned int); and the ::start (Callback cb, unsigned int, unsigned int); take a minimum and maximum preferred value for when the timeout should be called. The reason for this is so that core can group timeouts into common fire-times to reduce the number of wakeups compiz will cause on the CPU. Usually a minimum of the preferred value and a maximum of 1.4 times the preferred amount is safe. If you require your timeout to be exactly precise, then you can set both the minimum and maximum value to be the same, however this will be more taxing on system resources.

Setting the callback

You can set the callback either with the ::setCallback (CallBack); or ::start (CallBack, unsigned int, unsigned int) methods.

Callback is typedef'd to be a boost::function<bool ()>. This means that the default prototype which can be automatically bound to this type is a static member function which returns bool. If you wish to have the object (this) or increase the number of arguments, then you can use boost::bind in order to do this. For example:

bool
PluginScreen::callback (int, int, int)
{
    return false;
}

CompTimer timer;
timer.start (boost::bind (&PluginScreen::callback, this, 1, 2, 3));

Controlling the timer

/!\ You must have times and a callback set before starting the timer

If at any time you wish to stop your function being called on a regular basis, you can use the ::stop () method. If you need to check if the timer is active, ::active () can do that, and if the callbacks and timer are set, you can use ::start () to re-start the timer.

Returning false in the callback function will automatically stop the timer.

Development/zero-nine/CoreClasses/CompTimer (last edited 2010-07-27 05:15:48 by 124-169-107-122)