Write about user interfaces and the use/non-use of async

Byron · Byron · commit 91ba0457745f · 2020-08-06T17:28:37.000+08:00
diff --git a/Cargo.toml b/Cargo.toml
@@ -37,15 +37,15 @@ small = ["lean-cli"]
 fast = ["git-features/parallel", "git-features/fast-sha1"]
 pretty-cli = ["structopt",
     "git-features/progress-prodash",
-    "git-features/interuptible",
+    "git-features/interruptible",
     "gitoxide-core/serde1",
     "prodash/log-renderer",
     "prodash-tui-renderer",
     "prodash-line-renderer",
     "prodash/localtime",
     "env_logger",
     "futures-lite"]
-lean-cli = ["argh", "git-features/progress-log", "env_logger", "git-features/interuptible"]
+lean-cli = ["argh", "git-features/progress-log", "env_logger", "git-features/interruptible"]
 
 prodash-line-renderer-crossterm = ["prodash-line-renderer", "prodash/line-renderer-crossterm", "git-features/progress-prodash", "atty", "crosstermion"]
 prodash-line-renderer-termion = ["prodash-line-renderer", "prodash/line-renderer-termion", "git-features/progress-prodash", "atty", "crosstermion"]
diff --git a/Makefile b/Makefile
@@ -74,7 +74,7 @@ check: ## Build all code in suitable configurations
 	cd git-features && cargo check --all-features \
 			   && cargo check --features parallel \
 			   && cargo check --features fast-sha1 \
-			   && cargo check --features interuptible
+			   && cargo check --features interruptible
 
 unit-tests: ## run all unit tests
 	cargo test --all --no-fail-fast
diff --git a/README.md b/README.md
@@ -235,11 +235,6 @@ Provide a CLI to for the most basic user journey:
   * [ ] create (thin) pack
 * [ ] transform _all_ `unwrap()` calls into `expect(…)` or `?` for quality. `parking_lot` will help for unwraps of poisoned locks.
   
-### Roadmap to 1.1
-
- * [ ] clone a repository via
-   * [ ] ssh
-
 ## Cargo features guide
 
 Cargo uses feature toggles to control which dependencies are pulled in, allowing users to specialize crates to fit their usage.
@@ -280,7 +275,7 @@ There are **convenience features**, which combine common choices of the above in
 * **light** = *lean-cli* + *fast*
   * crossplatform by nature as this comes with simplified log based progress
 * **small** = *lean-cli*
-  * As small as it can possibly be, no threading, no fast sha1, log based progress only
+  * As small as it can possibly be, no threading, no fast sha1, log based progress only, no cleanup of temporary files on interrupt
     
 ### git-features
 
@@ -301,7 +296,7 @@ All feature toggles are additive.
 * **progress-prodash**
   * Implement the `Progress` trait for the tree data structures provided by `prodash`, which enables using a terminal user
     interface for progress.
-* **interuptible**
+* **interruptible**
   * Listen to interrupts and termination requests and provide long-running operations tooling to allow aborting the input stream.
   * If unset, these utilities will be a no-op which may lead to leaking temporary files when interrupted.
   * If the application already sets a handler, this handler will have no effect.
@@ -342,6 +337,32 @@ All feature toggles are additive.
   
 ### Guidelines
 
+* **async**
+  * **library client-side**
+    * Don't use it client side, as operations there are usually bound by the CPU and ultra-fast access to memory mapped files.
+      It's no problem to saturate either CPU or the IO system.
+  * **User Interfaces**
+    * User interfaces can greatly benefit from using async as it's much easier to maintain a responsive UI thread that way thanks
+      to the wonderful future combinators.
+    * `blocking` can be used to make `Read` and `Iterator` async, or move any operation onto a thread which blends it into the 
+      async world. 
+       * Most operations are fast and 'interrupting' them is as easy as ignoring their result by cancelling their task.
+       * Long-running operations can be roughly interacted with using `git_features::interruptible::interrupt()` function, and after a moment
+         of waiting the flag can be unset with the `…::uninterrupt()` function to allow new long-running operations to work. 
+         Every long running operation supports this.
+  * **server-side**
+    * Building a pack is CPU and at some point, IO bound, and it makes no sense to use async to handle more connections - git
+      needs a lot of resources and threads will do just fine.
+      
+* **interruption of long-running operations**
+  * Use `git-features::interruptible::*` for building support for interruptions of long-running operations only.
+    * It's up to the author to decide how to best integrate it, generally we use a poll-based mechanism to check whether
+      an interrupt flag is set.
+    * **this is a must if…**
+      * …temporary resources like files might otherwise be leaked
+    * **this is optional but desirable if…**
+      * …there is no leakage otherwise to support user interfaces. They background long-running operations and need them to be cancellable.
+      
 * **prepare for SHA256 support by using `owned::Id` and `borrowed::Id`**
   * eventually there will be the need to support both Sha1 and Sha256. We anticipate it by using the `Id` type instead 
     of slices or arrays of 20 bytes. This way, eventually we can support multiple hash digest sizes.
@@ -381,6 +402,7 @@ From there, we can derive a few rules to try adhere to:
 
 * does not show any progress or logging output by default
 * if supported and logging is enabled, it will show timestamps in UTC
+* it does not need a git repository, but instead takes all variables via the command-line 
 
 ### Porcelain
 
diff --git a/git-features/Cargo.toml b/git-features/Cargo.toml
@@ -16,7 +16,7 @@ parallel = ["crossbeam-utils", "crossbeam-channel", "num_cpus"]
 fast-sha1 = ["fastsha1"]
 progress-log = ["log"]
 progress-prodash = ["prodash"]
-interuptible = ["ctrlc", "once_cell"]
+interruptible = ["ctrlc", "once_cell"]
 
 [[test]]
 name = "parallel"
@@ -48,7 +48,7 @@ fastsha1 = { package = "sha-1", version = "0.9.1", optional = true }
 log = { version = "0.4.8", optional = true }
 prodash = { version = "7.0.2", optional = true, default-features = false }
 
-# interuptible
+# interruptible
 ctrlc = { version = "3.1.4", optional = true, default-features = false, features = ['termination'] }
 once_cell = { version = "1.4.0", optional = true, default-features = false, features = ["std"] }
 
diff --git a/git-features/src/interruptible.rs b/git-features/src/interruptible.rs
@@ -1,4 +1,4 @@
-#[cfg(feature = "interuptible")]
+#[cfg(feature = "interruptible")]
 mod _impl {
     use ctrlc;
     use once_cell::sync::Lazy;
@@ -24,23 +24,26 @@ mod _impl {
         R: io::Read,
     {
         fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
-            if is_interupted() {
+            if is_interrupted() {
                 return Err(io::Error::new(io::ErrorKind::Other, "interrupted by user"));
             }
             self.inner.read(buf)
         }
     }
 
-    pub fn is_interupted() -> bool {
+    pub fn is_interrupted() -> bool {
         IS_INTERRUPTED.load(Ordering::Relaxed)
     }
 
-    pub fn interupt() {
+    pub fn interrupt() {
         IS_INTERRUPTED.store(true, Ordering::Relaxed);
     }
+    pub fn uninterrupt() {
+        IS_INTERRUPTED.store(false, Ordering::Relaxed);
+    }
 }
 
-#[cfg(not(feature = "interuptible"))]
+#[cfg(not(feature = "interruptible"))]
 mod _impl {
     use std::io;
 
@@ -60,6 +63,10 @@ mod _impl {
     pub fn is_interrupted() -> bool {
         false
     }
+
+    pub fn interrupt() {}
+
+    pub fn uninterrupt() {}
 }
 
 pub use _impl::*;
diff --git a/git-features/src/lib.rs b/git-features/src/lib.rs
@@ -1,6 +1,6 @@
 #![forbid(unsafe_code)]
 
 pub mod hash;
-pub mod interuptible;
+pub mod interruptible;
 pub mod parallel;
 pub mod progress;
diff --git a/git-odb/src/pack/bundle/write/mod.rs b/git-odb/src/pack/bundle/write/mod.rs
@@ -1,5 +1,5 @@
 use crate::pack;
-use git_features::{interuptible, progress, progress::Progress};
+use git_features::{interruptible, progress, progress::Progress};
 use std::{
     io,
     path::{Path, PathBuf},
@@ -53,7 +53,7 @@ impl pack::Bundle {
         };
         let data_path: Option<PathBuf> = data_file.as_ref().map(|f| f.as_ref().into());
         let mut pack = PassThrough {
-            reader: interuptible::Read { inner: pack },
+            reader: interruptible::Read { inner: pack },
             writer: data_file,
         };
         let eight_pages = 4096 * 8;
diff --git a/git-odb/src/pack/tree/traverse/mod.rs b/git-odb/src/pack/tree/traverse/mod.rs
@@ -3,7 +3,7 @@ use crate::{
     pack::data::EntrySlice,
     pack::tree::{Item, Tree},
 };
-use git_features::{parallel, parallel::in_parallel_if, progress::Progress};
+use git_features::{interruptible::is_interrupted, parallel, parallel::in_parallel_if, progress::Progress};
 use quick_error::quick_error;
 
 mod resolve;
@@ -23,6 +23,9 @@ quick_error! {
             source(&**err)
             from()
         }
+        Interrupted {
+            display("Interrupted by user")
+        }
     }
 }
 
@@ -112,6 +115,9 @@ where
         let input = input?;
         self.item_count += input;
         self.progress.lock().set(self.item_count as u32);
+        if is_interrupted() {
+            return Err(Error::Interrupted);
+        }
         Ok(())
     }
 
diff --git a/src/plumbing/pretty.rs b/src/plumbing/pretty.rs
@@ -198,7 +198,7 @@ fn prepare_and_run<T: Send + 'static>(
         + 'static,
 ) -> Result<T> {
     super::init_env_logger(false);
-    use git_features::interuptible::{interupt, is_interupted};
+    use git_features::interruptible::{interrupt, is_interrupted};
     match (verbose, progress) {
         (false, false) => run(None, &mut stdout(), &mut stderr()),
         (true, false) => {
@@ -214,7 +214,7 @@ fn prepare_and_run<T: Send + 'static>(
                 let tx = tx.clone();
                 move || loop {
                     std::thread::sleep(std::time::Duration::from_millis(500));
-                    if is_interupted() {
+                    if is_interrupted() {
                         tx.send(Event::UIDone).ok();
                         break;
                     }
@@ -274,7 +274,7 @@ fn prepare_and_run<T: Send + 'static>(
                     Event::UIDone => {
                         // We don't know why the UI is done, usually it's the user aborting.
                         // We need the computation to stop as well so let's wait for that to happen
-                        interupt();
+                        interrupt();
                         continue;
                     }
                     Event::ComputationDone(res, out, err) => {
diff --git a/tasks.md b/tasks.md
@@ -31,8 +31,8 @@
       system temp files)
          * [x] for lean mode
          * [x] for pretty mode
-         * [ ] allow interrupting the resolution phase too
-         * [ ] fix typo :D - thanks IJ for confusing me
+         * [x] allow interrupting the resolution phase too
+         * [x] fix typo :D - thanks IJ for confusing me
   * [ ] move --verbose, --progress and --progress-keep-open to the top-level 
   * [ ] unit tests for bundle index write
   * [ ] journey test for command-line capabilities

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-#[cfg(feature = "interuptible")]`
	`1`	`+#[cfg(feature = "interruptible")]`
`2`	`2`	`mod _impl {`
`3`	`3`	`use ctrlc;`
`4`	`4`	`use once_cell::sync::Lazy;`
`@@ -24,23 +24,26 @@ mod _impl {`
`24`	`24`	`R: io::Read,`
`25`	`25`	`{`
`26`	`26`	`fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {`
`27`		`- if is_interupted() {`
	`27`	`+ if is_interrupted() {`
`28`	`28`	`return Err(io::Error::new(io::ErrorKind::Other, "interrupted by user"));`
`29`	`29`	`}`
`30`	`30`	`self.inner.read(buf)`
`31`	`31`	`}`
`32`	`32`	`}`
`33`	`33`
`34`		`- pub fn is_interupted() -> bool {`
	`34`	`+ pub fn is_interrupted() -> bool {`
`35`	`35`	`IS_INTERRUPTED.load(Ordering::Relaxed)`
`36`	`36`	`}`
`37`	`37`
`38`		`- pub fn interupt() {`
	`38`	`+ pub fn interrupt() {`
`39`	`39`	`IS_INTERRUPTED.store(true, Ordering::Relaxed);`
`40`	`40`	`}`
	`41`	`+ pub fn uninterrupt() {`
	`42`	`+ IS_INTERRUPTED.store(false, Ordering::Relaxed);`
	`43`	`+ }`
`41`	`44`	`}`
`42`	`45`
`43`		`-#[cfg(not(feature = "interuptible"))]`
	`46`	`+#[cfg(not(feature = "interruptible"))]`
`44`	`47`	`mod _impl {`
`45`	`48`	`use std::io;`
`46`	`49`
`@@ -60,6 +63,10 @@ mod _impl {`
`60`	`63`	`pub fn is_interrupted() -> bool {`
`61`	`64`	`false`
`62`	`65`	`}`
	`66`	`+`
	`67`	`+ pub fn interrupt() {}`
	`68`	`+`
	`69`	`+ pub fn uninterrupt() {}`
`63`	`70`	`}`
`64`	`71`
`65`	`72`	`pub use _impl::*;`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@ use crate::{`
`3`	`3`	`pack::data::EntrySlice,`
`4`	`4`	`pack::tree::{Item, Tree},`
`5`	`5`	`};`
`6`		`-use git_features::{parallel, parallel::in_parallel_if, progress::Progress};`
	`6`	`+use git_features::{interruptible::is_interrupted, parallel, parallel::in_parallel_if, progress::Progress};`
`7`	`7`	`use quick_error::quick_error;`
`8`	`8`
`9`	`9`	`mod resolve;`
`@@ -23,6 +23,9 @@ quick_error! {`
`23`	`23`	`source(&**err)`
`24`	`24`	`from()`
`25`	`25`	`}`
	`26`	`+ Interrupted {`
	`27`	`+ display("Interrupted by user")`
	`28`	`+ }`
`26`	`29`	`}`
`27`	`30`	`}`
`28`	`31`
`@@ -112,6 +115,9 @@ where`
`112`	`115`	`let input = input?;`
`113`	`116`	`self.item_count += input;`
`114`	`117`	`self.progress.lock().set(self.item_count as u32);`
	`118`	`+ if is_interrupted() {`
	`119`	`+ return Err(Error::Interrupted);`
	`120`	`+ }`
`115`	`121`	`Ok(())`
`116`	`122`	`}`
`117`	`123`