From f04ddb645a790a50e343385aca32d2761b7a0d4d Mon Sep 17 00:00:00 2001
From: chris_kohlhoff <chris_kohlhoff>
Date: Fri, 9 Dec 2005 01:27:33 +0000
Subject: [PATCH] Add documentation on interaction between exceptions and
 demuxer::run().

---
 asio/include/asio/basic_demuxer.hpp | 36 +++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/asio/include/asio/basic_demuxer.hpp b/asio/include/asio/basic_demuxer.hpp
index 1dee8e9d..17fabfed 100644
--- a/asio/include/asio/basic_demuxer.hpp
+++ b/asio/include/asio/basic_demuxer.hpp
@@ -49,6 +49,8 @@ namespace asio {
  *
  * @par Concepts:
  * Dispatcher.
+ *
+ * @sa \ref demuxer_handler_exception
  */
 template <typename Demuxer_Service>
 class basic_demuxer
@@ -296,6 +298,40 @@ private:
   Demuxer_Service& service_;
 };
 
+/**
+ * @page demuxer_handler_exception Effect of exceptions thrown from handlers
+ *
+ * If an exception is thrown from a handler, the exception is allowed to
+ * propagate through the throwing thread's invocation of
+ * asio::demuxer::run(). No other threads that are calling
+ * asio::demuxer::run() are affected. It is then the responsibility of
+ * the application to catch the exception.
+ *
+ * After the exception has been caught, the asio::demuxer::run() call
+ * may be restarted @em without the need for an intervening call to
+ * asio::demuxer::reset(). This allows the thread to rejoin the
+ * demuxer's thread pool without impacting any other threads in the
+ * pool.
+ *
+ * @par Example:
+ * @code
+ * asio::demuxer demuxer;
+ * ...
+ * for (;;)
+ * {
+ *   try
+ *   {
+ *     demuxer.run();
+ *     break; // run() exited normally
+ *   }
+ *   catch (my_exception& e)
+ *   {
+ *     // Deal with exception as appropriate.
+ *   }
+ * }
+ * @endcode
+ */
+
 } // namespace asio
 
 #include "asio/detail/pop_options.hpp"