//
-// Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+// Copyright (c) 2003-2018 Christopher M. Kohlhoff (chris at kohlhoff dot com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
\until asio.hpp
-Since this example uses timers, we need to include the appropriate
-Boost.Date_Time header file for manipulating times.
-
-\until posix_time.hpp
-
-All programs that use asio need to have at least one boost::asio::io_service object.
+All programs that use asio need to have at least one boost::asio::io_context object.
This class provides access to I/O functionality. We declare an object of this
type first thing in the main function.
-\until boost::asio::io_service
+\until boost::asio::io_context
-Next we declare an object of type boost::asio::deadline_timer. The core asio classes
+Next we declare an object of type boost::asio::steady_timer. The core asio classes
that provide I/O functionality (or as in this case timer functionality) always
-take a reference to an io_service as their first constructor argument. The
+take a reference to an io_context as their first constructor argument. The
second argument to the constructor sets the timer to expire 5 seconds from now.
-\until boost::asio::deadline_timer
+\until boost::asio::steady_timer
In this simple example we perform a blocking wait on the timer.
-That is, the call to boost::asio::deadline_timer::wait() will not return until the
+That is, the call to boost::asio::steady_timer::wait() will not return until the
timer has expired, 5 seconds after it was created (i.e. <b>not</b> from when the
wait starts).
-A deadline timer is always in one of two states: "expired" or "not expired". If
-the boost::asio::deadline_timer::wait() function is called on an expired timer, it
-will return immediately.
+A timer is always in one of two states: "expired" or "not expired". If the
+boost::asio::steady_timer::wait() function is called on an expired timer, it will
+return immediately.
\until wait
\dontinclude timer2/timer.cpp
\skip #include
-\until posix_time.hpp
+\until asio.hpp
Using asio's asynchronous functionality means having a callback
function that will be called when an asynchronous operation completes. In this
program we define a function called <tt>print</tt> to be called when the
asynchronous wait finishes.
-\until boost::asio::deadline_timer
+\until boost::asio::steady_timer
Next, instead of doing a blocking wait as in tutorial Timer.1,
-we call the boost::asio::deadline_timer::async_wait() function to perform an
+we call the boost::asio::steady_timer::async_wait() function to perform an
asynchronous wait. When calling this function we pass the <tt>print</tt>
callback handler that was defined above.
\skipline async_wait
-Finally, we must call the boost::asio::io_service::run() member function
-on the io_service object.
+Finally, we must call the boost::asio::io_context::run() member function
+on the io_context object.
The asio library provides a guarantee that callback handlers will <b>only</b>
-be called from threads that are currently calling boost::asio::io_service::run().
-Therefore unless the boost::asio::io_service::run() function is called the callback for
+be called from threads that are currently calling boost::asio::io_context::run().
+Therefore unless the boost::asio::io_context::run() function is called the callback for
the asynchronous wait completion will never be invoked.
-The boost::asio::io_service::run() function will also continue to run while there is
+The boost::asio::io_context::run() function will also continue to run while there is
still "work" to do. In this example, the work is the asynchronous wait on the
timer, so the call will not return until the timer has expired and the
callback has completed.
-It is important to remember to give the io_service some work to do before
-calling boost::asio::io_service::run(). For example, if we had omitted the above call
-to boost::asio::deadline_timer::async_wait(), the io_service would not have had any
-work to do, and consequently boost::asio::io_service::run() would have returned
+It is important to remember to give the io_context some work to do before
+calling boost::asio::io_context::run(). For example, if we had omitted the above call
+to boost::asio::steady_timer::async_wait(), the io_context would not have had any
+work to do, and consequently boost::asio::io_context::run() would have returned
immediately.
\skip run
\dontinclude timer3/timer.cpp
\skip #include
-\until posix_time.hpp
+\until bind.hpp
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
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 io_service to stop. Recall that in
-tutorial Timer.2 we learnt that the boost::asio::io_service::run() function completes
+that there is no explicit call to ask the io_context to stop. Recall that in
+tutorial Timer.2 we learnt that the boost::asio::io_context::run() function completes
when there is no more "work" to do. By not starting a new asynchronous wait on
-the timer when <tt>count</tt> reaches 5, the io_service will run out of work and
+the timer when <tt>count</tt> reaches 5, the io_context will run out of work and
stop running.
\until ++
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 boost::asio::deadline_timer::async_wait() function
+with your callback handler. The boost::asio::steady_timer::async_wait() function
expects a handler function (or function object) with the signature
<tt>void(const boost::system::error_code&)</tt>. Binding the additional parameters
converts your <tt>print</tt> function into a function object that matches the
will see that this placeholder may be elided if the parameter is not needed by
the callback handler.
-\until boost::asio::io_service
+\until boost::asio::io_context
A new <tt>count</tt> variable is added so that we can stop the
program when the timer fires for the sixth time.
-\until boost::asio::deadline_timer
+\until boost::asio::steady_timer
As in Step 4, when making the call to
-boost::asio::deadline_timer::async_wait() from <tt>main</tt> we bind the additional
+boost::asio::steady_timer::async_wait() from <tt>main</tt> we bind the additional
parameters needed for the <tt>print</tt> function.
\until run
\dontinclude timer4/timer.cpp
\skip #include
-\until posix_time.hpp
+\until bind.hpp
Instead of defining a free function <tt>print</tt> as the
callback handler, as we did in the earlier tutorial programs, we now define a
\until public
The constructor of this class will take a reference to the
-io_service object and use it when initialising the <tt>timer_</tt> member. The
+io_context object and use it when initialising the <tt>timer_</tt> member. The
counter used to shut down the program is now also a member of the class.
\until {
\until };
The <tt>main</tt> function is much simpler than before, as it
-now declares a local <tt>printer</tt> object before running the io_service as
+now declares a local <tt>printer</tt> object before running the io_context as
normal.
\until }
/**
\page tuttimer5 Timer.5 - Synchronising handlers in multithreaded programs
-This tutorial demonstrates the use of the boost::asio::io_service::strand class to
+This tutorial demonstrates the use of the boost::asio::io_context::strand class to
synchronise callback handlers in a multithreaded program.
The previous four tutorials avoided the issue of handler synchronisation by
-calling the boost::asio::io_service::run() function from one thread only. As you
+calling the boost::asio::io_context::run() function from one thread only. As you
already know, the asio library provides a guarantee that callback handlers will
<b>only</b> be called from threads that are currently calling
-boost::asio::io_service::run(). Consequently, calling boost::asio::io_service::run() from
+boost::asio::io_context::run(). Consequently, calling boost::asio::io_context::run() from
only one thread ensures that callback handlers cannot run concurrently.
The single threaded approach is usually the best place to start when
</ul>
If you find yourself running into these limitations, an alternative approach
-is to have a pool of threads calling boost::asio::io_service::run(). However, as this
+is to have a pool of threads calling boost::asio::io_context::run(). However, as this
allows handlers to execute concurrently, we need a method of synchronisation
when handlers might be accessing a shared, thread-unsafe resource.
\dontinclude timer5/timer.cpp
\skip #include
-\until posix_time.hpp
+\until bind.hpp
We start by defining a class called <tt>printer</tt>, similar
to the class in the previous tutorial. This class will extend the previous
\until public
-In addition to initialising a pair of boost::asio::deadline_timer members, the
+In addition to initialising a pair of boost::asio::steady_timer members, the
constructor initialises the <tt>strand_</tt> member, an object of type
-boost::asio::io_service::strand.
+boost::asio::io_context::strand.
-An boost::asio::io_service::strand is an executor that guarantees that, for those
+An boost::asio::io_context::strand is an executor that 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 boost::asio::io_service::run(). Of course, the
+the number of threads that are calling boost::asio::io_context::run(). Of course, the
handlers may still execute concurrently with other handlers that were
-<b>not</b> dispatched through an boost::asio::io_service::strand, or were dispatched
-through a different boost::asio::io_service::strand object.
+<b>not</b> dispatched through an boost::asio::io_context::strand, or were dispatched
+through a different boost::asio::io_context::strand object.
\until {
When initiating the asynchronous operations, each callback handler is "bound"
-to an boost::asio::io_service::strand object. The
-boost::asio::io_service::strand::bind_executor() function returns a new handler that
+to an boost::asio::io_context::strand object. The
+boost::asio::io_context::strand::bind_executor() function returns a new handler that
automatically dispatches its contained handler through the
-boost::asio::io_service::strand object. By binding the handlers to the same
-boost::asio::io_service::strand, we are ensuring that they cannot execute
+boost::asio::io_context::strand object. By binding the handlers to the same
+boost::asio::io_context::strand, we are ensuring that they cannot execute
concurrently.
\until }
\until };
-The <tt>main</tt> function now causes boost::asio::io_service::run() to
+The <tt>main</tt> function now causes boost::asio::io_context::run() to
be called from two threads: the main thread and one additional thread. This is
accomplished using an boost::thread object.
Just as it would with a call from a single thread, concurrent calls to
-boost::asio::io_service::run() will continue to execute while there is "work" left to
+boost::asio::io_context::run() will continue to execute while there is "work" left to
do. The background thread will not exit until all asynchronous operations have
completed.
projects / ceph.git / blobdiff