From 97fed1de7fada14161c5ced50cf65bfef24ce075 Mon Sep 17 00:00:00 2001 From: Christopher Kohlhoff Date: Fri, 3 Oct 2014 11:35:55 +1000 Subject: [PATCH] Documentation fixes. --- asio/include/asio/basic_waitable_timer.hpp | 3 -- asio/include/asio/execution_context.hpp | 2 +- .../asio/impl/buffered_read_stream.hpp | 8 ++++++ .../asio/impl/buffered_write_stream.hpp | 8 ++++++ asio/include/asio/impl/connect.hpp | 4 +++ asio/include/asio/impl/read.hpp | 8 ++++++ asio/include/asio/impl/read_at.hpp | 8 ++++++ asio/include/asio/impl/read_until.hpp | 16 +++++++++++ asio/include/asio/impl/spawn.hpp | 4 +++ asio/include/asio/impl/write.hpp | 8 ++++++ asio/include/asio/impl/write_at.hpp | 8 ++++++ asio/include/asio/wrap.hpp | 10 ++++--- asio/src/doc/reference.xsl | 3 ++ .../src/examples/cpp03/tutorial/timer_dox.txt | 28 ++++++++++--------- 14 files changed, 97 insertions(+), 21 deletions(-) diff --git a/asio/include/asio/basic_waitable_timer.hpp b/asio/include/asio/basic_waitable_timer.hpp index 0fbe49ba..81819c26 100644 --- a/asio/include/asio/basic_waitable_timer.hpp +++ b/asio/include/asio/basic_waitable_timer.hpp @@ -127,9 +127,6 @@ class basic_waitable_timer : public basic_io_object { public: - /// The executor type. - typedef asio::io_service::executor_type executor_type; - /// The clock type. typedef Clock clock_type; diff --git a/asio/include/asio/execution_context.hpp b/asio/include/asio/execution_context.hpp index ddff5628..4aad2499 100644 --- a/asio/include/asio/execution_context.hpp +++ b/asio/include/asio/execution_context.hpp @@ -209,7 +209,7 @@ public: * given service type. If there is no existing implementation of the service, * then the io_service will create a new instance of the service. * - * @param e The io_service object that owns the service. + * @param i The io_service object that owns the service. * * @return The service interface implementing the specified service type. * Ownership of the service interface is not transferred to the caller. diff --git a/asio/include/asio/impl/buffered_read_stream.hpp b/asio/include/asio/impl/buffered_read_stream.hpp index 444d4552..785c59b0 100644 --- a/asio/include/asio/impl/buffered_read_stream.hpp +++ b/asio/include/asio/impl/buffered_read_stream.hpp @@ -139,6 +139,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< detail::buffered_fill_handler, Allocator> @@ -165,6 +167,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template template ASIO_INITFN_RESULT_TYPE(ReadHandler, @@ -322,6 +326,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -356,6 +362,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template template ASIO_INITFN_RESULT_TYPE(ReadHandler, diff --git a/asio/include/asio/impl/buffered_write_stream.hpp b/asio/include/asio/impl/buffered_write_stream.hpp index ff36d01e..e894fb29 100644 --- a/asio/include/asio/impl/buffered_write_stream.hpp +++ b/asio/include/asio/impl/buffered_write_stream.hpp @@ -125,6 +125,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< detail::buffered_flush_handler, Allocator> @@ -151,6 +153,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template template ASIO_INITFN_RESULT_TYPE(WriteHandler, @@ -308,6 +312,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -342,6 +348,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template template ASIO_INITFN_RESULT_TYPE(WriteHandler, diff --git a/asio/include/asio/impl/connect.hpp b/asio/include/asio/impl/connect.hpp index 4251f2b2..aa1c72d5 100644 --- a/asio/include/asio/impl/connect.hpp +++ b/asio/include/asio/impl/connect.hpp @@ -322,6 +322,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template @@ -364,6 +366,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(ComposedConnectHandler, diff --git a/asio/include/asio/impl/read.hpp b/asio/include/asio/impl/read.hpp index f1855a14..2eaba114 100644 --- a/asio/include/asio/impl/read.hpp +++ b/asio/include/asio/impl/read.hpp @@ -516,6 +516,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -552,6 +554,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(ReadHandler, @@ -730,6 +734,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -766,6 +772,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(ReadHandler, diff --git a/asio/include/asio/impl/read_at.hpp b/asio/include/asio/impl/read_at.hpp index 30d900ad..764f6cb9 100644 --- a/asio/include/asio/impl/read_at.hpp +++ b/asio/include/asio/impl/read_at.hpp @@ -565,6 +565,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -601,6 +603,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(ReadHandler, @@ -786,6 +790,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -822,6 +828,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(ReadHandler, diff --git a/asio/include/asio/impl/read_until.hpp b/asio/include/asio/impl/read_until.hpp index 3c5594ad..a27353ee 100644 --- a/asio/include/asio/impl/read_until.hpp +++ b/asio/include/asio/impl/read_until.hpp @@ -493,6 +493,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -527,6 +529,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template ASIO_INITFN_RESULT_TYPE(ReadHandler, void (asio::error_code, std::size_t)) @@ -729,6 +733,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -765,6 +771,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template ASIO_INITFN_RESULT_TYPE(ReadHandler, void (asio::error_code, std::size_t)) @@ -976,6 +984,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -1010,6 +1020,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template ASIO_INITFN_RESULT_TYPE(ReadHandler, void (asio::error_code, std::size_t)) @@ -1217,6 +1229,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -1253,6 +1267,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template ASIO_INITFN_RESULT_TYPE(ReadHandler, diff --git a/asio/include/asio/impl/spawn.hpp b/asio/include/asio/impl/spawn.hpp index 461699b7..8ffc8cff 100644 --- a/asio/include/asio/impl/spawn.hpp +++ b/asio/include/asio/impl/spawn.hpp @@ -224,6 +224,8 @@ private: asio::error_code ec_; }; +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator, Allocator> { @@ -248,6 +250,8 @@ struct associated_executor, Executor> } }; +#endif // !defined(GENERATING_DOCUMENTATION) + namespace detail { template diff --git a/asio/include/asio/impl/write.hpp b/asio/include/asio/impl/write.hpp index eafd82c2..d1ce4497 100644 --- a/asio/include/asio/impl/write.hpp +++ b/asio/include/asio/impl/write.hpp @@ -579,6 +579,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -615,6 +617,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(WriteHandler, @@ -744,6 +748,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< detail::write_streambuf_handler, @@ -774,6 +780,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(WriteHandler, diff --git a/asio/include/asio/impl/write_at.hpp b/asio/include/asio/impl/write_at.hpp index 2768c297..63b58693 100644 --- a/asio/include/asio/impl/write_at.hpp +++ b/asio/include/asio/impl/write_at.hpp @@ -627,6 +627,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< @@ -663,6 +665,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(WriteHandler, @@ -803,6 +807,8 @@ namespace detail } } // namespace detail +#if !defined(GENERATING_DOCUMENTATION) + template struct associated_allocator< detail::write_at_streambuf_op, @@ -833,6 +839,8 @@ struct associated_executor< } }; +#endif // !defined(GENERATING_DOCUMENTATION) + template inline ASIO_INITFN_RESULT_TYPE(WriteHandler, diff --git a/asio/include/asio/wrap.hpp b/asio/include/asio/wrap.hpp index 7d95c7e8..59c5de51 100644 --- a/asio/include/asio/wrap.hpp +++ b/asio/include/asio/wrap.hpp @@ -378,8 +378,12 @@ public: return static_cast(*this); } -#if defined(ASIO_HAS_VARIADIC_TEMPLATES) \ - || defined(GENERATING_DOCUMENTATION) +#if defined(GENERATING_DOCUMENTATION) + + template auto operator()(Args&& ...); + template auto operator()(Args&& ...) const; + +#elif defined(ASIO_HAS_VARIADIC_TEMPLATES) /// Forwarding function call operator. template @@ -398,7 +402,6 @@ public: } #else // defined(ASIO_HAS_VARIADIC_TEMPLATES) - // || defined(GENERATING_DOCUMENTATION) typename detail::executor_wrapper_result_of0::type operator()() { @@ -429,7 +432,6 @@ public: #undef ASIO_PRIVATE_WRAP_CALL_DEF #endif // defined(ASIO_HAS_VARIADIC_TEMPLATES) - // || defined(GENERATING_DOCUMENTATION) private: typedef detail::executor_wrapper_base + + + diff --git a/asio/src/examples/cpp03/tutorial/timer_dox.txt b/asio/src/examples/cpp03/tutorial/timer_dox.txt index 658fbc18..c28867c9 100644 --- a/asio/src/examples/cpp03/tutorial/timer_dox.txt +++ b/asio/src/examples/cpp03/tutorial/timer_dox.txt @@ -292,8 +292,8 @@ Return to \ref tuttimer4 /** \page tuttimer5 Timer.5 - Synchronising handlers in multithreaded programs -This tutorial demonstrates the use of the asio::strand class to synchronise -callback handlers in a multithreaded program. +This tutorial demonstrates the use of the asio::io_service::strand class to +synchronise callback handlers in a multithreaded program. The previous four tutorials avoided the issue of handler synchronisation by calling the asio::io_service::run() function from one thread only. As you @@ -329,22 +329,24 @@ tutorial by running two timers in parallel. In addition to initialising a pair of asio::deadline_timer members, the constructor initialises the strand_ member, an object of type -asio::strand. +asio::io_service::strand. -An asio::strand guarantees that, for those handlers that are dispatched through -it, an executing handler will be allowed to complete before the next one is -started. This is guaranteed irrespective of the number of threads that are -calling asio::io_service::run(). Of course, the handlers may still execute -concurrently with other handlers that were not dispatched through an -asio::strand, or were dispatched through a different asio::strand object. +An asio::io_service::strand guarantees that, for those handlers that are +dispatched through it, an executing handler will be allowed to complete before +the next one is started. This is guaranteed irrespective of the number of +threads that are calling asio::io_service::run(). Of course, the handlers may +still execute concurrently with other handlers that were not dispatched +through an asio::io_service::strand, or were dispatched through a different +asio::io_service::strand object. \until { When initiating the asynchronous operations, each callback handler is "wrapped" -using the asio::strand object. The asio::strand::wrap() function returns a new -handler that automatically dispatches its contained handler through the -asio::strand object. By wrapping the handlers using the same asio::strand, we -are ensuring that they cannot execute concurrently. +using the asio::io_service::strand object. The asio::io_service::strand::wrap() +function returns a new handler that automatically dispatches its contained +handler through the asio::io_service::strand object. By wrapping the handlers +using the same asio::io_service::strand, we are ensuring that they cannot +execute concurrently. \until } \until }