added some more docs for callouts

[libasyncio] / asyncio / async_callout.hpp

diff --git a/asyncio/async_callout.hpp b/asyncio/async_callout.hpp
index 251821a..15d7233 100644 (file)
--- 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);