dlib C++ Library - timer_abstract.h

    // Copyright (C) 2005  Davis E. King (davis@dlib.net)
    // License: Boost Software License   See LICENSE.txt for the full license.
    #undef DLIB_TIMER_KERNEl_ABSTRACT_
    #ifdef DLIB_TIMER_KERNEl_ABSTRACT_

    #include "../threads.h"

    namespace dlib
    {

        template <
            typename T
            >
        class timer
        {
            /*!
                INITIAL VALUE
                    is_running()      == false
                    delay_time()      == 1000
                    action_object()   == The object that is passed into the constructor
                    action_function() == The member function pointer that is passed to
                                         the constructor.

                WHAT THIS OBJECT REPRESENTS
                    This object represents a timer that will call a given member function
                    (the action function) repeatedly at regular intervals and in its own
                    thread.

                    Note that the delay_time() is measured in milliseconds but you are not
                    guaranteed to have that level of resolution.  The actual resolution
                    is implementation dependent.

                THREAD SAFETY
                    All methods of this class are thread safe.
            !*/

        public:

            typedef void (T::*af_type)();

            timer (
                T& ao,
                af_type af
            );
            /*!
                requires
                    - af does not throw
                ensures
                    - does not block.
                    - #*this is properly initialized
                    - #action_object() == ao
                    - #action_function() == af
                      (af is a member function pointer to a member in the class T)
                throws
                    - std::bad_alloc
                    - dlib::thread_error
            !*/

            virtual ~timer (
            );
            /*!
                requires
                    - is not called from inside the action_function()
                ensures
                    - any resources associated with *this have been released
                    - will not call the action_function() anymore.
                    - if (the action function is currently executing) then
                        - blocks until it finishes
            !*/

            void clear(
            );
            /*!
                ensures
                    - #*this has its initial value
                    - does not block
                throws
                    - std::bad_alloc or dlib::thread_error
                        If either of these exceptions are thrown then #*this is unusable
                        until clear() is called and succeeds.
            !*/

            af_type action_function (
            ) const;
            /*!
                ensures
                    - does not block.
                    - returns a pointer to the member function of action_object() that is
                      called by *this.
            !*/

            const T& action_object (
            ) const;
            /*!
                ensures
                    - does not block.
                    - returns a const reference to the object used to call the member
                      function pointer action_function()
            !*/

            T& action_object (
            );
            /*!
                ensures
                    - does not block.
                    - returns a non-const reference to the object used to call the member
                      function pointer action_function()
            !*/

            bool is_running (
            ) const;
            /*!
                ensures
                    - does not block.
                    - if (*this is currently scheduled to call the action_function()) then
                        - returns true
                    - else
                        - returns false
            !*/

            unsigned long delay_time (
            ) const;
            /*!
                ensures
                    - does not block.
                    - returns the amount of time, in milliseconds, that *this will wait between
                      the return of one call to the action_function() and the beginning of the
                      next call to the action_function().
            !*/

            void set_delay_time (
                unsigned long milliseconds
            );
            /*!
                ensures
                    - does not block.
                    - #delay_time() == milliseconds
                throws
                    - std::bad_alloc or dlib::thread_error
                        If either of these exceptions are thrown then #is_running() == false
                        but otherwise this function succeeds
            !*/

            void start (
            );
            /*!
                ensures
                    - does not block.
                    - if (is_running() == false) then
                        - #is_running() == true
                        - The action_function() will run in another thread.
                        - The first call to the action_function() will occur in roughly
                          delay_time() milliseconds.
                    - else
                        - this call to start() has no effect
                throws
                    - dlib::thread_error or std::bad_alloc
                        If this exception is thrown then #is_running() == false but
                        otherwise this call to start() has no effect.
            !*/

            void stop (
            );
            /*!
                ensures
                    - #is_running() == false
                    - does not block.
            !*/

            void stop_and_wait (
            );
            /*!
                ensures
                    - #is_running() == false
                    - if (the action function is currently executing) then
                        - blocks until it finishes
            !*/

        private:

            // restricted functions
            timer(const timer<T>&);        // copy constructor
            timer<T>& operator=(const timer<T>&);    // assignment operator

        };

    }

    #endif // DLIB_TIMER_KERNEl_ABSTRACT_