Rename cancel() to stop() and make cancel() return a cancellation result instead

doc/changelog.dox

@@ -64,7 +64,7 @@ Result handling and
 - \ref result
 - \ref rethrow
 - \ref cancel
-- \ref terminate
+- \ref stop
 - \ref make_result
 
 Special result types

include/continuable/continuable-base.hpp

@@ -1058,9 +1058,10 @@ inline exceptional_result rethrow(exception_t exception) {
 }
 
 /// Can be used to cancel an asynchronous continuation chain,
-/// no handler which comes after cancel was received won't be called.
+/// the next failure handler which comes after cancel will be called
+/// with a default constructed exception_t object.
 ///
-/// The \ref empty_result returned by this function can be returned from
+/// The \ref cancellation_result returned by this function can be returned from
 /// any result or failure handler in order to cancel the chain.
 /// ```cpp
 /// http_request("example.com")
@@ -1091,7 +1092,16 @@ inline exceptional_result rethrow(exception_t exception) {
 ///
 /// \since 4.0.0
 ///
-inline empty_result cancel() {
+inline cancellation_result cancel() {
+  return {};
+}
+
+/// Can be used to stop an asynchronous continuation chain,
+/// no handler which comes after stop was received won't be called.
+///
+/// \since 4.0.0
+///
+inline empty_result stop() {
   return {};
 }
 

test/unit-test/multi/test-continuable-base-destruct.cpp

@@ -110,6 +110,12 @@ TYPED_TEST(single_dimension_tests, are_not_finished_when_not_continued) {
       return empty_result();
     }));
   }
+
+  {
+    ASSERT_ASYNC_INCOMPLETION(this->supply().then([] {
+      return stop();
+    }));
+  }
 }
 
 TYPED_TEST(single_dimension_tests, are_not_finished_when_cancelling) {

test/unit-test/multi/test-continuable-base-errors.cpp

@@ -127,7 +127,7 @@ TYPED_TEST(single_dimension_tests, are_exceptions_partial_applyable) {
                                 .fail([&]() -> empty_result {
                                   EXPECT_FALSE(handled);
                                   handled = true;
-                                  return cancel();
+                                  return stop();
                                 }));
   ASSERT_TRUE(handled);
 
@@ -138,7 +138,7 @@ TYPED_TEST(single_dimension_tests, are_exceptions_partial_applyable) {
           .fail([&]() -> result<int, int> {
             EXPECT_FALSE(handled);
             handled = true;
-            return cancel();
+            return stop();
           }));
 
   ASSERT_TRUE(handled);

test/unit-test/multi/test-continuable-base-multipath.cpp

@@ -63,17 +63,29 @@ TYPED_TEST(single_dimension_tests, multipath_result_is_throwable) {
 }
 
 TYPED_TEST(single_dimension_tests, multipath_result_is_cancelable) {
-  ASSERT_ASYNC_INCOMPLETION(this->supply().then([]() -> empty_result {
+  ASSERT_ASYNC_CANCELLATION(this->supply().then([]() -> cancellation_result {
     //
     return cancel();
   }));
 
-  ASSERT_ASYNC_INCOMPLETION(this->supply().then([]() -> result<> {
+  ASSERT_ASYNC_CANCELLATION(this->supply().then([]() -> result<> {
     //
     return cancel();
   }));
 }
 
+TYPED_TEST(single_dimension_tests, multipath_result_is_stoppable) {
+  ASSERT_ASYNC_INCOMPLETION(this->supply().then([]() -> empty_result {
+    //
+    return stop();
+  }));
+
+  ASSERT_ASYNC_INCOMPLETION(this->supply().then([]() -> result<> {
+    //
+    return stop();
+  }));
+}
+
 TYPED_TEST(single_dimension_tests, multipath_exception_is_recoverable) {
   EXPECT_ASYNC_RESULT(
       this->supply_exception(supply_test_exception(), identity<>{})
@@ -115,19 +127,19 @@ TYPED_TEST(single_dimension_tests, multipath_exception_is_forwardable) {
           }));
 }
 
-TYPED_TEST(single_dimension_tests, multipath_exception_is_cancelable) {
+TYPED_TEST(single_dimension_tests, multipath_exception_is_stoppable) {
   ASSERT_ASYNC_INCOMPLETION(
       this->supply_exception(supply_test_exception(), identity<int>{})
           .fail([](exception_t) -> empty_result {
             //
-            return cancel();
+            return stop();
           }));
 
   ASSERT_ASYNC_INCOMPLETION(
       this->supply_exception(supply_test_exception(), identity<int>{})
           .fail([](exception_t) -> result<int> {
             //
-            return cancel();
+            return stop();
           }));
 }