diff --git a/asio/src/examples/tutorial/tutorial_dox.txt b/asio/src/examples/tutorial/tutorial_dox.txt index 8092d344..4b9c78cb 100644 --- a/asio/src/examples/tutorial/tutorial_dox.txt +++ b/asio/src/examples/tutorial/tutorial_dox.txt @@ -68,7 +68,7 @@ Return to \ref tuttimer1 /** \page tuttimer2 Tutorial Part 2 - Using a timer asynchronously -This tutorial program illustrates how to use asio's asynchronous callback +This tutorial program demonstrates how to use asio's asynchronous callback functionality by modifying the program from Part 1 to perform an asynchronous wait on the timer. @@ -122,8 +122,72 @@ Return to \ref tuttimer2 /** \page tuttimer3 Tutorial Part 3 - Binding arguments to a handler -\include timer3/timer.cpp +In this part of the tutorial we will modify the program from Part 2 so that +the timer fires once a second. This will show how to pass additional +parameters to a your handler function. + +\dontinclude timer3/timer.cpp + +\until include "asio.hpp" + +Step 1. To implement a repeating timer using asio you need to change +the timer's expiry time in your callback function, and to then start a new +asynchronous wait. Obviously this means that the callback function will need +to be able to access the timer object. To this end we add two new parameters +to the print function: + +\li A pointer to a timer object. + +\li A counter so that we can stop the program when the timer fires for the +sixth time. + +\until { + +Step 2. As mentioned above, this tutorial program uses a counter to +stop running when the timer fires for the sixth time. However you will observe +that there is no explicit call to ask the demuxer to stop. Recall that in Part +2 we learnt that the asio::demuxer::run() function completes when there is no +more "work" to do. By not starting a new asynchronous wait on the timer when +count reaches 5, the demuxer will run out of work and stop running. + +\until ++ + +Step 3. Next we move the expiry time for the timer along by one second +from the previous expiry time. Using the asio::timer::from_existing flag +instead of asio::timer::from_now ensures that the timer does drift away from +the whole-second mark due to any delays in processing the handler. + +\until set + +Step 4. Then we start a new asynchronous wait on the timer. As you can +see, the boost::bind function is used to associate the extra +parameters with your callback handler. The asio::timer::async_wait() function +expects a handler function (or function object) with the signature +void(). Binding the additional parameters converts your +print function into a function object that matches the signature +correctly. + +\until asio::demuxer + +Step 5. A new count variable is added so that we can stop the +program when the timer fires for the sixth time. + +\until asio::timer + +Step 6. As in Step 4, when making the call to asio::timer::async_wait() +from main we bind the additional parameters needed for the +print function. + +\until run + +Step 7. Finally, just to prove that the count variable was +being used in the print handler function, we will print out its new +value. + +\until } + +See the \ref tuttimer3src \n Return to the \ref tutindex \n Go back to \ref tuttimer2 \n Go on to \ref tuttimer4 @@ -131,10 +195,69 @@ Go on to \ref tuttimer4 */ /** -\page tuttimer4 Tutorial Part 4 - Using a member function as a handler -\include timer4/timer.cpp +\page tuttimer3src Source listing for Tutorial Part 3 +\include timer3/timer.cpp +Return to \ref tuttimer3 +*/ +/** +\page tuttimer4 Tutorial Part 4 - Using a member function as a handler + +In this part of the tutorial we will see how to use a class member function as +a callback handler. The program should execute identically to the tutorial +program from Part 3. + +\dontinclude timer4/timer.cpp + +\until include "asio.hpp" + +Step 1. Instead of defining a free function print as the +callback handler, as we did in the earlier tutorial programs, we now define a +class called printer. + +\until public + +Step 2. The constructor of this class will take a reference to the +demuxer object and use it when initialising the timer_ member. The +counter used to shut down the program is now also a member of the class. + +\until { + +Step 3. The boost::bind function works just as well with class +member functions as with free functions. Since all non-static class member +functions have an implicit this parameter, we need to bind +this to the function. As in Part 3, boost::bind converts our +callback handler (now a member function) into a function object that matches +the signature void(). + +\until } + +Step 4. In the class destructor we will print out the final value of +the counter. + +\until } + +Step 5. The print member function is very similar to the +print function from Part 3, except that it now operates on the class +data members instead of having the timer and counter passed in as parameters. + +\until }; + +Step 6. The main function is much simpler than before, as it +now declares a local printer object before running the demuxer as +normal. + +\until } + +See the \ref tuttimer4src \n Return to the \ref tutindex \n Go back to \ref tuttimer3 \n */ + +/** +\page tuttimer4src Source listing for Tutorial Part 4 +\include timer4/timer.cpp +Return to \ref tuttimer4 +*/ +