From d02bf9269ab3234339fbaebd1a47e68dfed4007b Mon Sep 17 00:00:00 2001 From: Reinhard Pfau Date: Wed, 29 Apr 2009 22:34:20 +0200 Subject: [PATCH] added some more docs for callouts --- asyncio/async_callout.cpp | 52 +++++++++++++++++++++++++++++++++++++++++++- asyncio/async_callout.hpp | 26 ++++++++++++++++++++- 2 files changed, 74 insertions(+), 4 deletions(-) diff --git a/asyncio/async_callout.cpp b/asyncio/async_callout.cpp index 16c1347..10089e3 100644 --- a/asyncio/async_callout.cpp +++ b/asyncio/async_callout.cpp @@ -20,7 +20,9 @@ on this file might be covered by the GNU General Public License. /** * @file * - * @copyright © Copyright 2008 by Intra2net AG + * @copyright © Copyright 2008-2009 by Intra2net AG + * @contact opensource@intra2net.com + * */ #include "async_callout.hpp" #include @@ -38,6 +40,7 @@ on this file might be covered by the GNU General Public License. namespace AsyncIo { +// anonymous namespace for our secret details :-) namespace { @@ -65,6 +68,10 @@ unsigned long create_call_out_id_value() } // eo create_call_out_id_value +/** + * @brief add a caller instance to the local call map. + * @param caller the caller instance. + */ void add_call( CallerPtr caller ) { if (caller->joinId()) @@ -74,6 +81,12 @@ void add_call( CallerPtr caller ) } // eo add_call +/** + * @brief removes an entry from the local call map + * @param id_value id to remove from the map. + * @return @a true if an entry was found and removed + * @a false if entry was not found in the map. + */ bool remove_call( unsigned long id_value ) { CallMap::iterator it= l_call_map.find(id_value); @@ -86,6 +99,11 @@ bool remove_call( unsigned long id_value ) } // eo remove_call(unsigned long) +/** + * @brief return the caller for an id. + * @param id_value the id to search the caller for. + * @return caller; empty pointer if not found. + */ CallerPtr get_call(unsigned long id_value) { CallMap::iterator it= l_call_map.find(id_value); @@ -97,6 +115,11 @@ CallerPtr get_call(unsigned long id_value) } // eo get_call(unsigned long) +/** + * @brief tests if an id can be found in the call map. + * @param id_value the id to search for. + * @return @a true if the id is found in the call map. + */ bool has_call( unsigned long id_value ) { CallMap::iterator it= l_call_map.find(id_value); @@ -125,6 +148,16 @@ CallOutId::CallOutId(unsigned long value) } // eo CallOutId::CallOutId(unsigned long) +/** + * @brief thaws (activate) the referenced (and frozen) call. + * @return @a true if the call was successfully thawed; @a false else. + * + * A call (referenced the id instance) can be successfully thawed if: + * - the call was a frozen call + * - the call is still existing; i.e. we are within the given time period + * for that call. + * . + */ bool CallOutId::thaw() const { if (m_caller_weak_ptr.expired()) @@ -140,6 +173,13 @@ bool CallOutId::thaw() const } // eo CallOutId::thaw() const +/** + * @brief removes the referenced call. + * @return @a true if the call was removed; @a false else. + * + * @note after calling this method, the refernced call is not existing. + * Either it was removed or it was already removed earlier (explicit or implicit). + */ bool CallOutId::remove() { if (m_caller_weak_ptr.expired()) @@ -152,6 +192,12 @@ bool CallOutId::remove() } // eo CallOutId::remove() +/** + * @brief returns if the referenced call is still active. + * @return @a true if the referenced call is active. + * + * The referenced call is active if it is still waiting to be executed. + */ bool CallOutId::active() const { return m_value!=0 and not m_caller_weak_ptr.expired() and has_call(m_value); @@ -159,7 +205,7 @@ bool CallOutId::active() const /** - * @brief retruns if the call is frozen. + * @brief returns if the call is frozen. * @return @a true iff the call is frozen. */ bool CallOutId::frozen() const @@ -178,6 +224,8 @@ bool CallOutId::frozen() const * @return the remaining time. * * The result only makes sense if the call is still active. + * + * If the references call is not active then the returned time is 0. */ MilliTime CallOutId::remaining_time() { diff --git a/asyncio/async_callout.hpp b/asyncio/async_callout.hpp index 251821a..15d7233 100644 --- a/asyncio/async_callout.hpp +++ b/asyncio/async_callout.hpp @@ -21,7 +21,7 @@ on this file might be covered by the GNU General Public License. * @file * @brief provides a method for delayed execution of functions. * - * @copyright © Copyright 2008 by Intra2net AG + * @copyright © Copyright 2008-2009 by Intra2net AG */ #ifndef ___ASYNC_CALLOUT_HPP__ #define ___ASYNC_CALLOUT_HPP__ @@ -134,6 +134,19 @@ class Caller * @param f the function which should be called. * @param delta_sec the delta time (in seconds) when the function should be called. * @return an id to identify the call (may be used for preliminary removal of the call) + * + * A deferred call is done by passing a function object and a delay when it should + * be called. + * The backend loop will call the function after the delay is passed and the backend loop is active. + * + * Thus the call might not not be exactly after the desired delay, but at least this time has + * to pass until the function is called. + * + * The result id can be used to remove the call if it becomes obsolete. + * This is useful when You call timeout handlers and can remove them if an event happens and + * obsoletes the timeout call. + * + * @see CallOutId */ template< typename F > CallOutId callOut( boost::function< void() > f, F delta_sec ); @@ -149,7 +162,16 @@ template<> CallOutId callOut( boost::function< void() > f, int delta_sec ); * * @param f the function which should be called. * @param delta_sec the delta time (in seconds) when the call will be (silently) removed. - * @return an id to identify the call; neccessary for thaw the call. + * @return an id to identify the call; necessary for thaw the call. + * + * A frozen call is a function call which will be prepared for a given period of time + * but not executed. Within that time period that call might be activated ("thawed") + * which means the call will be executed the next time when the backend loop is running. + * If the prepared call is not activated, then it vanishes. + * + * The returned call id provides a method to thaw a frozen call. + * + * @see CallOutId */ template< typename F > CallOutId frozenCall( boost::function< void() > f, F delta_sec); -- 1.7.1