From 57b90abf1994f110c627758de63872421321fb73 Mon Sep 17 00:00:00 2001
From: jerel <jerel.unruh@toyotaconnected.com>
Date: Wed, 5 Jul 2023 18:52:16 -0500
Subject: [PATCH] Rename JoinHandle to AbortHandle to more closely match its
 behavior

(and to align with tokio's conventions)
---
 README.md                           | 10 +++++-----
 example/src/application/advanced.rs |  4 ++--
 example/src/lib.rs                  | 18 +++++++-----------
 membrane/src/runtime.rs             | 25 ++++++++++++++++++-------
 membrane/tests/mock.rs              | 14 +++++---------
 membrane/tests/ui/single.rs         | 14 +++++---------
 membrane/tests/ui/stream.rs         | 14 +++++---------
 7 files changed, 47 insertions(+), 52 deletions(-)

diff --git a/README.md b/README.md
index 5772ca2..667e3ab 100644
--- a/README.md
+++ b/README.md
@@ -48,29 +48,29 @@ _View the [example](https://github.com/jerel/membrane/tree/main/example) directo
 
 In your crate's `lib.rs` add a `RUNTIME` static that will survive for the lifetime of the program. `RUNTIME` must hold an instance of `membrane::App<Runtime>` where `Runtime` has the `membrane::Interface` trait implemented for whichever async framework you wish to use. In our examples we use `tokio` to provide the runtime behavior, you are welcome to copy it:
 ``` rust
-use membrane::runtime::{App, Interface, JoinHandle};
+use membrane::runtime::{App, Interface, AbortHandle};
 
 pub struct Runtime(tokio::runtime::Runtime);
 
 impl Interface for Runtime {
-  fn spawn<F>(&self, future: F) -> JoinHandle
+  fn spawn<F>(&self, future: F) -> AbortHandle
   where
     F: std::future::Future + Send + 'static,
     F::Output: Send + 'static,
   {
     let handle = self.0.spawn(future);
-    JoinHandle {
+    AbortHandle {
       abort: Box::new(move || handle.abort()),
     }
   }
 
-  fn spawn_blocking<F, R>(&self, future: F) -> JoinHandle
+  fn spawn_blocking<F, R>(&self, future: F) -> AbortHandle
   where
     F: FnOnce() -> R + Send + 'static,
     R: Send + 'static,
   {
     let handle = self.0.spawn_blocking(future);
-    JoinHandle {
+    AbortHandle {
       abort: Box::new(move || handle.abort()),
     }
   }
diff --git a/example/src/application/advanced.rs b/example/src/application/advanced.rs
index ef0e0e8..09a68d8 100644
--- a/example/src/application/advanced.rs
+++ b/example/src/application/advanced.rs
@@ -57,7 +57,7 @@ pub fn contact_async_emitter(user_id: String) -> impl Emitter<Result<data::Conta
   });
 
   let e = emitter.clone();
-  // drop the JoinHandle to detach the thread
+  // drop the AbortHandle to detach the thread
   let _ = thread::spawn(move || {
     e.on_done(|| {
       println!("\n[contact_async_emitter] the finalizer has been called for the Emitter");
@@ -119,7 +119,7 @@ pub fn contact_async_stream_emitter(
     .for_each(|contact| {
       let stream = stream.clone();
 
-      // drop the JoinHandle to detach the thread
+      // drop the AbortHandle to detach the thread
       let _ = thread::spawn(move || {
         let id = thread::current().id();
 
diff --git a/example/src/lib.rs b/example/src/lib.rs
index d3c7f8a..a9d5219 100644
--- a/example/src/lib.rs
+++ b/example/src/lib.rs
@@ -1,31 +1,27 @@
 mod application;
 mod data;
 
-use membrane::runtime::{App, Interface, JoinHandle};
+use membrane::runtime::{App, Interface, AbortHandle};
 
 pub struct Runtime(tokio::runtime::Runtime);
 
 impl Interface for Runtime {
-  fn spawn<F>(&self, future: F) -> JoinHandle
+  fn spawn<F>(&self, future: F) -> AbortHandle
   where
     F: std::future::Future + Send + 'static,
     F::Output: Send + 'static,
   {
-    let handle = self.0.spawn(future);
-    JoinHandle {
-      abort: Box::new(move || handle.abort()),
-    }
+    let join_handle = self.0.spawn(future);
+    AbortHandle::new(move || join_handle.abort())
   }
 
-  fn spawn_blocking<F, R>(&self, future: F) -> JoinHandle
+  fn spawn_blocking<F, R>(&self, future: F) -> AbortHandle
   where
     F: FnOnce() -> R + Send + 'static,
     R: Send + 'static,
   {
-    let handle = self.0.spawn_blocking(future);
-    JoinHandle {
-      abort: Box::new(move || handle.abort()),
-    }
+    let join_handle = self.0.spawn_blocking(future);
+    AbortHandle::new(move || join_handle.abort())
   }
 }
 
diff --git a/membrane/src/runtime.rs b/membrane/src/runtime.rs
index f4bd7d9..de079b0 100644
--- a/membrane/src/runtime.rs
+++ b/membrane/src/runtime.rs
@@ -2,12 +2,12 @@ use once_cell::sync::OnceCell;
 use std::future::Future;
 
 pub trait Interface {
-  fn spawn<F>(&self, future: F) -> JoinHandle
+  fn spawn<F>(&self, future: F) -> AbortHandle
   where
     F: Future + Send + 'static,
     F::Output: Send + 'static;
 
-  fn info_spawn<F>(&self, future: F, _info: Info) -> JoinHandle
+  fn info_spawn<F>(&self, future: F, _info: Info) -> AbortHandle
   where
     F: Future + Send + 'static,
     F::Output: Send + 'static,
@@ -15,12 +15,12 @@ pub trait Interface {
     self.spawn(future)
   }
 
-  fn spawn_blocking<F, R>(&self, future: F) -> JoinHandle
+  fn spawn_blocking<F, R>(&self, future: F) -> AbortHandle
   where
     F: FnOnce() -> R + Send + 'static,
     R: Send + 'static;
 
-  fn info_spawn_blocking<F, R>(&self, future: F, _info: Info) -> JoinHandle
+  fn info_spawn_blocking<F, R>(&self, future: F, _info: Info) -> AbortHandle
   where
     F: FnOnce() -> R + Send + 'static,
     R: Send + 'static,
@@ -29,13 +29,24 @@ pub trait Interface {
   }
 }
 
-pub struct JoinHandle {
-  pub abort: Box<dyn Fn()>,
+#[deprecated(since="0.9.5", note="please use `AbortHandle` instead, renamed to better match common tokio naming convention")]
+pub type JoinHandle = AbortHandle;
+
+pub struct AbortHandle {
+  #[deprecated(since="0.9.5", note="please use `AbortHandle::new()` instead")]
   pub abort: Box<dyn Fn() + Send + 'static>,
 }
 
-impl JoinHandle {
+impl AbortHandle {
+  pub fn new(abort: impl Fn() + Send + 'static) -> Self {
+    #[allow(deprecated)]
+    Self {
+      abort: Box::new(abort)
+    }
+  }
+
   pub fn abort(&self) {
+    #[allow(deprecated)]
     (self.abort)();
   }
 }
diff --git a/membrane/tests/mock.rs b/membrane/tests/mock.rs
index 3798466..677979a 100644
--- a/membrane/tests/mock.rs
+++ b/membrane/tests/mock.rs
@@ -1,27 +1,23 @@
-use membrane::runtime::{App, Interface, JoinHandle};
+use membrane::runtime::{App, Interface, AbortHandle};
 use std::future::Future;
 
 pub struct TestRuntime();
 
 impl Interface for TestRuntime {
-  fn spawn<T>(&self, _future: T) -> JoinHandle
+  fn spawn<T>(&self, _future: T) -> AbortHandle
   where
     T: Future + Send + 'static,
     T::Output: Send + 'static,
   {
-    JoinHandle {
-      abort: Box::new(|| {}),
-    }
+    AbortHandle::new(|| {})
   }
 
-  fn spawn_blocking<F, R>(&self, _future: F) -> JoinHandle
+  fn spawn_blocking<F, R>(&self, _future: F) -> AbortHandle
   where
     F: FnOnce() -> R + Send + 'static,
     R: Send + 'static,
   {
-    JoinHandle {
-      abort: Box::new(|| {}),
-    }
+    AbortHandle::new(|| {})
   }
 }
 
diff --git a/membrane/tests/ui/single.rs b/membrane/tests/ui/single.rs
index 108197e..62c7a00 100644
--- a/membrane/tests/ui/single.rs
+++ b/membrane/tests/ui/single.rs
@@ -56,30 +56,26 @@ pub async fn one_success() -> Result<Vec<i32>, String> {
   Ok(vec![10])
 }
 
-use membrane::runtime::{App, Interface, JoinHandle};
+use membrane::runtime::{App, Interface, AbortHandle};
 use membrane::{async_dart, sync_dart};
 use std::future::Future;
 
 struct TestRuntime();
 impl Interface for TestRuntime {
-  fn spawn<T>(&self, future: T) -> JoinHandle
+  fn spawn<T>(&self, future: T) -> AbortHandle
   where
     T: Future + Send + 'static,
     T::Output: Send + 'static,
   {
-    JoinHandle {
-      abort: Box::new(|| {}),
-    }
+    AbortHandle::new(|| {})
   }
 
-  fn spawn_blocking<F, R>(&self, future: F) -> JoinHandle
+  fn spawn_blocking<F, R>(&self, future: F) -> AbortHandle
   where
     F: FnOnce() -> R + Send + 'static,
     R: Send + 'static,
   {
-    JoinHandle {
-      abort: Box::new(|| {}),
-    }
+    AbortHandle::new(|| {})
   }
 }
 
diff --git a/membrane/tests/ui/stream.rs b/membrane/tests/ui/stream.rs
index a6f5871..d084edb 100644
--- a/membrane/tests/ui/stream.rs
+++ b/membrane/tests/ui/stream.rs
@@ -11,29 +11,25 @@ pub fn one_success() -> impl Stream<Item = Result<i32, String>> {
 
 use futures::Stream;
 use membrane::async_dart;
-use membrane::runtime::{App, Interface, JoinHandle};
+use membrane::runtime::{App, Interface, AbortHandle};
 use std::future::Future;
 
 struct TestRuntime();
 impl Interface for TestRuntime {
-  fn spawn<T>(&self, future: T) -> JoinHandle
+  fn spawn<T>(&self, future: T) -> AbortHandle
   where
     T: Future + Send + 'static,
     T::Output: Send + 'static,
   {
-    JoinHandle {
-      abort: Box::new(|| {}),
-    }
+    AbortHandle::new(|| {})
   }
 
-  fn spawn_blocking<F, R>(&self, future: F) -> JoinHandle
+  fn spawn_blocking<F, R>(&self, future: F) -> AbortHandle
   where
     F: FnOnce() -> R + Send + 'static,
     R: Send + 'static,
   {
-    JoinHandle {
-      abort: Box::new(|| {}),
-    }
+    AbortHandle::new(|| {})
   }
 }