From 33bfc490efd9e9882da500a5b2d23c266269143c Mon Sep 17 00:00:00 2001
From: Denis Blank <denis.blank@outlook.com>
Date: Sun, 5 Apr 2020 00:22:30 +0200
Subject: [PATCH] Rename cancel() to stop() and make cancel() return a
 cancellation result instead

---
 doc/changelog.dox                             |  2 +-
 include/continuable/continuable-base.hpp      | 16 +++++++++++---
 .../multi/test-continuable-base-destruct.cpp  |  6 +++++
 .../multi/test-continuable-base-errors.cpp    |  4 ++--
 .../multi/test-continuable-base-multipath.cpp | 22 ++++++++++++++-----
 5 files changed, 39 insertions(+), 11 deletions(-)

diff --git a/doc/changelog.dox b/doc/changelog.dox
index a11d369..c0298ce 100644
--- a/doc/changelog.dox
+++ b/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
diff --git a/include/continuable/continuable-base.hpp b/include/continuable/continuable-base.hpp
index 53dd91b..4ecafe1 100644
--- a/include/continuable/continuable-base.hpp
+++ b/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 {};
 }
 
diff --git a/test/unit-test/multi/test-continuable-base-destruct.cpp b/test/unit-test/multi/test-continuable-base-destruct.cpp
index 49ae9fa..cbb9ebc 100644
--- a/test/unit-test/multi/test-continuable-base-destruct.cpp
+++ b/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) {
diff --git a/test/unit-test/multi/test-continuable-base-errors.cpp b/test/unit-test/multi/test-continuable-base-errors.cpp
index d03df52..fba0126 100644
--- a/test/unit-test/multi/test-continuable-base-errors.cpp
+++ b/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);
diff --git a/test/unit-test/multi/test-continuable-base-multipath.cpp b/test/unit-test/multi/test-continuable-base-multipath.cpp
index 609f43b..f9d5ae1 100644
--- a/test/unit-test/multi/test-continuable-base-multipath.cpp
+++ b/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();
           }));
 }