added some more docs for callouts

diff --git a/asyncio/async_callout.cpp b/asyncio/async_callout.cpp
index 16c1347..10089e3 100644 (file)
--- 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 <asyncio_config.hpp>
@@ -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 (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);