Add consign completion token adapter.

The consign completion token adapter can be used to attach additional
values to a completion handler. This is typically used to keep at least
one copy of an object, such as a smart pointer, alive until the
completion handler is called.

For example:

  auto timer1 = std::make_shared<boost::asio::steady_timer>(my_io_context);
  timer1->expires_after(std::chrono::seconds(1));
  timer1->async_wait(
      boost::asio::consign(
        [](boost::system::error_code ec)
        {
          // ...
        },
        timer1
      )
    );

  auto timer2 = std::make_shared<boost::asio::steady_timer>(my_io_context);
  timer2->expires_after(std::chrono::seconds(30));
  std::future<void> f =
    timer2->async_wait(
      boost::asio::consign(
        boost::asio::use_future,
        timer2
      )
    );

test/Jamfile.v2

@@ -124,6 +124,8 @@ test-suite "asio" :
   [ link connect.cpp : $(USE_SELECT) : connect_select ]
   [ run connect_pipe.cpp ]
   [ run connect_pipe.cpp : : : $(USE_SELECT) : connect_pipe_select ]
+  [ run consign.cpp ]
+  [ run consign.cpp : : : $(USE_SELECT) : consign_select ]
   [ link coroutine.cpp ]
   [ link coroutine.cpp : $(USE_SELECT) : coroutine_select ]
   [ run deadline_timer.cpp ]

test/consign.cpp

@@ -0,0 +1,60 @@
+//
+// consign.cpp
+// ~~~~~~~~~~
+//
+// Copyright (c) 2003-2022 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)
+//
+
+// Disable autolinking for unit tests.
+#if !defined(BOOST_ALL_NO_LIB)
+#define BOOST_ALL_NO_LIB 1
+#endif // !defined(BOOST_ALL_NO_LIB)
+
+// Test that header file is self-contained.
+#include <boost/asio/consign.hpp>
+
+#include <boost/asio/bind_executor.hpp>
+#include <boost/asio/io_context.hpp>
+#include <boost/asio/post.hpp>
+#include <boost/asio/system_timer.hpp>
+#include "unit_test.hpp"
+
+void consign_test()
+{
+#if defined(BOOST_ASIO_HAS_STD_TUPLE) \
+  && defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES)
+  boost::asio::io_context io1;
+  boost::asio::io_context io2;
+  boost::asio::system_timer timer1(io1);
+  int count = 0;
+
+  timer1.expires_after(boost::asio::chrono::seconds(0));
+  timer1.async_wait(
+      boost::asio::consign(
+        boost::asio::bind_executor(io2.get_executor(),
+          [&count](boost::system::error_code)
+          {
+            ++count;
+          }), 123, 321));
+
+  BOOST_ASIO_CHECK(count == 0);
+
+  io1.run();
+
+  BOOST_ASIO_CHECK(count == 0);
+
+  io2.run();
+
+  BOOST_ASIO_CHECK(count == 1);
+#endif // defined(BOOST_ASIO_HAS_STD_TUPLE)
+       //   && defined(BOOST_ASIO_HAS_VARIADIC_TEMPLATES)
+}
+
+BOOST_ASIO_TEST_SUITE
+(
+  "consign",
+  BOOST_ASIO_TEST_CASE(consign_test)
+)