feat(core): expose `async_runtime` module (#1576)

.changes/expose-async-runtime.md

@@ -0,0 +1,5 @@
+---
+"tauri": patch
+---
+
+Expose `async_runtime` module.

core/tauri/src/api/command.rs

@@ -16,7 +16,7 @@ use std::os::windows::process::CommandExt;
 #[cfg(windows)]
 const CREATE_NO_WINDOW: u32 = 0x0800_0000;
 
-use crate::api::private::async_runtime::{channel, spawn, Receiver, RwLock};
+use crate::async_runtime::{channel, spawn, Receiver, RwLock};
 use os_pipe::{pipe, PipeWriter};
 use serde::Serialize;
 use shared_child::SharedChild;
@@ -203,7 +203,7 @@ mod test {
     let cmd = Command::new("cat").args(&["test/api/test.txt"]);
     let (mut rx, _) = cmd.spawn().unwrap();
 
-    crate::api::private::async_runtime::block_on(async move {
+    crate::async_runtime::block_on(async move {
       while let Some(event) = rx.recv().await {
         match event {
           CommandEvent::Terminated(payload) => {
@@ -225,7 +225,7 @@ mod test {
     let cmd = Command::new("cat").args(&["test/api/"]);
     let (mut rx, _) = cmd.spawn().unwrap();
 
-    crate::api::private::async_runtime::block_on(async move {
+    crate::async_runtime::block_on(async move {
       while let Some(event) = rx.recv().await {
         match event {
           CommandEvent::Terminated(payload) => {

core/tauri/src/api/mod.rs

@@ -68,33 +68,6 @@ pub struct PackageInfo {
 // Not public API
 #[doc(hidden)]
 pub mod private {
-  // Core API only.
-  pub mod async_runtime {
-    use once_cell::sync::OnceCell;
-    use tokio::runtime::Runtime;
-    pub use tokio::sync::{
-      mpsc::{channel, Receiver, Sender},
-      Mutex, RwLock,
-    };
-
-    use std::future::Future;
-
-    static RUNTIME: OnceCell<Runtime> = OnceCell::new();
-
-    pub fn block_on<F: Future>(task: F) -> F::Output {
-      let runtime = RUNTIME.get_or_init(|| Runtime::new().unwrap());
-      runtime.block_on(task)
-    }
-
-    pub fn spawn<F>(task: F)
-    where
-      F: Future + Send + 'static,
-      F::Output: Send + 'static,
-    {
-      let runtime = RUNTIME.get_or_init(|| Runtime::new().unwrap());
-      runtime.spawn(task);
-    }
-  }
   pub use once_cell::sync::OnceCell;
 
   pub trait AsTauriContext {

core/tauri/src/async_runtime.rs

@@ -0,0 +1,35 @@
+// Copyright 2019-2021 Tauri Programme within The Commons Conservancy
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-License-Identifier: MIT
+
+//! The singleton async runtime used by Tauri and exposed to consumers.
+//! Wraps a `tokio` Runtime and is meant to be used by initialization code, such as plugins `initialization` and app `setup` hooks.
+//! Fox more complex use cases, consider creating your own runtime.
+//! For command handlers, it's recommended to use a plain `async fn` command.
+
+use once_cell::sync::OnceCell;
+use tokio::runtime::Runtime;
+pub use tokio::sync::{
+  mpsc::{channel, Receiver, Sender},
+  Mutex, RwLock,
+};
+
+use std::future::Future;
+
+static RUNTIME: OnceCell<Runtime> = OnceCell::new();
+
+/// Run a future to completion on runtime.
+pub fn block_on<F: Future>(task: F) -> F::Output {
+  let runtime = RUNTIME.get_or_init(|| Runtime::new().unwrap());
+  runtime.block_on(task)
+}
+
+/// Spawn a future onto the runtime.
+pub fn spawn<F>(task: F)
+where
+  F: Future + Send + 'static,
+  F::Output: Send + 'static,
+{
+  let runtime = RUNTIME.get_or_init(|| Runtime::new().unwrap());
+  runtime.spawn(task);
+}

core/tauri/src/lib.rs

@@ -10,12 +10,14 @@
 //! Tauri uses (and contributes to) the MIT licensed project that you can find at [webview](https://github.com/webview/webview).
 #![warn(missing_docs, rust_2018_idioms)]
 
-pub(crate) use crate::api::private::async_runtime;
 /// The Tauri error enum.
 pub use error::Error;
 pub use tauri_macros::{command, generate_handler};
 
+/// Core API.
 pub mod api;
+/// Async runtime.
+pub mod async_runtime;
 /// The Tauri API endpoints.
 mod endpoints;
 mod error;