From 624b49ce9cd2c0931e5828a81e90ff08b2b05c31 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Fri, 18 Sep 2015 12:45:47 +0200 Subject: [PATCH] [4047] Fixed documentation of the TimerMgr. --- src/lib/dhcpsrv/timer_mgr.cc | 10 ++++----- src/lib/dhcpsrv/timer_mgr.h | 39 +++++++++--------------------------- 2 files changed, 14 insertions(+), 35 deletions(-) diff --git a/src/lib/dhcpsrv/timer_mgr.cc b/src/lib/dhcpsrv/timer_mgr.cc index 91c74724c9..e4135e58f3 100644 --- a/src/lib/dhcpsrv/timer_mgr.cc +++ b/src/lib/dhcpsrv/timer_mgr.cc @@ -184,9 +184,6 @@ public: /// @brief Cancels the execution of the interval timer. /// - /// This method has no effect if the timer hasn't been scheduled with - /// the @c TimerMgr::setup method. - /// /// @param timer_name Unique timer name. /// /// @throw BadValue if the timer hasn't been registered. @@ -220,8 +217,8 @@ private: /// /// This method marks the @c util::Watch socket associated with the /// timer as ready (writes data to a pipe). This method will block until - /// @c TimerMgr::ifaceMgrCallback is executed from the main thread by the - /// @c IfaceMgr. + /// @c TimerMgrImpl::if§aceMgrCallback is executed from the main thread by + /// the @c IfaceMgr. /// /// @param timer_name Unique timer name to be passed to the callback. void timerCallback(const std::string& timer_name); @@ -267,7 +264,8 @@ private: /// @tparam Iterator Iterator pointing to the timer configuration /// structure. template - void handleReadySocket(Iterator timer_info_iterator, const bool run_callback); + void handleReadySocket(Iterator timer_info_iterator, + const bool run_callback); //@} diff --git a/src/lib/dhcpsrv/timer_mgr.h b/src/lib/dhcpsrv/timer_mgr.h index 781bc0cee1..d4a29f4388 100644 --- a/src/lib/dhcpsrv/timer_mgr.h +++ b/src/lib/dhcpsrv/timer_mgr.h @@ -74,7 +74,7 @@ class TimerMgrImpl; /// the external socket it will invoke a callback function /// associated with this socket. This is the /// @c TimerMgr::ifaceMgrCallback associated with the socket when the -/// timer is registered. This callback function is executed/ in the +/// timer is registered. This callback function is executed in the /// main thread. It clears the socket, which unblocks the worker /// thread. It also invokes the user callback function specified /// for a given timer. @@ -86,19 +86,13 @@ class TimerMgrImpl; /// timers. Therefore, the @c TimerMgr does not allow for /// registering or unregistering the timers when the worker thread /// is running. The worker thread must be stopped first. -/// -/// @warning The application (DHCP server) is responsible for -/// unregistering the timers before it terminates: -/// @code -/// TimerMgr::instance().unregisterTimers(); -/// @endcode -/// -/// to avoid the static deinitialization fiasco between the @c TimerMgr -/// and @c IfaceMgr. Note that the @c TimerMgr destructor doesn't -/// unregister the timers to avoid referencing the @c IfaceMgr -/// instance which may not exist at this point. If the timers are -/// not unregistered before the application terminates this will -/// likely result in segmentation fault on some systems. +/// It is possible to call @c TimerMgr::setup and @c TimerMgr::cancel +/// while the worker thread is running but this is considered +/// unreliable (may cause race conditions) except the case when the +/// @c TimerMgr::setup is called from the installed callback +/// function to reschedule the ONE_SHOT timer. This is thread safe +/// because the worker thread is blocked while the callback function +/// is executed. /// class TimerMgr : public boost::noncopyable { public: @@ -117,11 +111,6 @@ public: /// callback. Inserting new element to this data structure and /// reading it at the same time would yield undefined behavior. /// - /// In order to prevent race conditions between the worker thread and - /// this method a mutex could be introduced. However, locking the mutex - /// would be required for all callback invocations, which could have - /// negative impact on the performance. - /// /// @param timer_name Unique name for the timer. /// @param callback Pointer to the callback function to be invoked /// when the timer elapses, e.g. function processing expired leases @@ -149,20 +138,12 @@ public: /// callback. Removing element from this data structure and /// reading it at the same time would yield undefined behavior. /// - /// In order to prevent race conditions between the worker thread and - /// this method a mutex could be introduced. However, locking the mutex - /// would be required for all callback invocations which could have - /// negative impact on the performance. - /// /// @param timer_name Name of the timer to be unregistered. /// /// @throw BadValue if the specified timer hasn't been registered. void unregisterTimer(const std::string& timer_name); /// @brief Unregisters all timers. - /// - /// This method must be explicitly called prior to termination of the - /// process. void unregisterTimers(); /// @brief Schedules the execution of the interval timer. @@ -249,8 +230,8 @@ private: /// @brief Private destructor. /// - /// Stops the worker thread if it is running. It doesn't unregister any - /// timers to avoid static deinitialization fiasco with the @c IfaceMgr. + /// Stops the worker thread if it is running and unregisteres any + /// registered timers. ~TimerMgr(); //@} -- 2.47.3