Merge branch 'master' of github.com:rustwasm/gloo into future-gate

Author: Aehmlo

.azure-pipelines.yml

@@ -0,0 +1,15 @@
+pr: ["master"]
+
+jobs:
+  - job:
+    pool:
+      vmImage: 'ubuntu-16.04'
+    steps:
+      - template: .ci/install-rust.yml
+        parameters:
+          rust_version: stable
+      - bash: |
+          export RUST_BACKTRACE=1
+          cargo check --all || exit
+          cargo test --all || exit
+        displayName: Run cargo check and test 

.ci/install-rust.yml

@@ -0,0 +1,14 @@
+steps:
+  - script: |
+      set -e
+      curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain $RUSTUP_TOOLCHAIN
+      echo "##vso[task.setvariable variable=PATH;]$PATH:$HOME/.cargo/bin"
+    env:
+      RUSTUP_TOOLCHAIN: ${{parameters.rust_version}}
+    displayName: Install Rust
+
+  # All platforms.
+  - script: |
+        rustc -Vv
+        cargo -V
+    displayName: Query rust and cargo versions

.gitignore

@@ -1,3 +1,5 @@
 /target
 **/*.rs.bk
 Cargo.lock
+
+guide/book

CONTRIBUTING.md

@@ -141,6 +141,8 @@ Here is a checklist that all Gloo utility crates should fulfill:
 
 * [ ] Crate's root module documentation has at least one realistic example.
 
+* [ ] Crate has at least a brief description of how to use it in the Gloo guide.
+
 [unwrap-throw]: https://docs.rs/wasm-bindgen/0.2.37/wasm_bindgen/trait.UnwrapThrowExt.html
 [api-guidelines]: https://rust-lang-nursery.github.io/api-guidelines/
 

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.1.0"
 
 [dependencies]
 gloo-timers = { version = "0.1.0", path = "crates/timers" }
+gloo-console-timer = { version = "0.1.0", path = "crates/console-timer" }
 
 [features]
 default = []

crates/console-timer/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "gloo-console-timer"
+version = "0.1.0"
+authors = ["Rust and WebAssembly Working Group"]
+edition = "2018"
+
+[dependencies.web-sys]
+version = "0.3.14"
+features = [
+    "console",
+]
+
+[dev-dependencies]
+wasm-bindgen-test = "0.2.37"
+gloo-timers = { version = "0.1.0", path = "../timers" }

crates/console-timer/src/lib.rs

@@ -0,0 +1,102 @@
+/*!
+
+The `console.time` and `console.timeEnd` functions allow you to log the
+timing of named operations to the browser's developer tools console. You
+call `console.time("foo")` when the operation begins, and call
+`console.timeEnd("foo")` when it finishes.
+
+Additionally, these measurements will show up in your browser's profiler's
+"timeline" or "waterfall" view.
+
+[See MDN for more info](https://developer.mozilla.org/en-US/docs/Web/API/console#Timers).
+
+This API wraps both the `time` and `timeEnd` calls into a single type
+named `ConsoleTimer`, ensuring both are called.
+
+## Scoped Measurement
+
+Wrap code to be measured in a closure with `ConsoleTimer::scope`.
+
+```no_run
+use gloo_console_timer::ConsoleTimer;
+
+let value = ConsoleTimer::scope("foo", || {
+    // Place code to be measured here
+    // Optionally return a value.
+});
+```
+
+## RAII-Style Measurement
+
+For scenarios where `ConsoleTimer::scope` can't be used, like with
+asynchronous operations, you can use `ConsoleTimer::new` to create a timer.
+The measurement ends when the timer object goes out of scope / is dropped.
+
+```no_run
+use gloo_console_timer::ConsoleTimer;
+use gloo_timers::Timeout;
+
+// Start timing a new operation.
+let timer = ConsoleTimer::new("foo");
+
+// And then asynchronously finish timing.
+let timeout = Timeout::new(1_000, move || {
+    drop(timer);
+});
+```
+ */
+
+#![deny(missing_docs, missing_debug_implementations)]
+
+use web_sys::console;
+
+/// A console time measurement.
+///
+/// See `ConsoleTimer::scope` for starting a labeled time measurement
+/// of code wrapped in a closure.
+#[derive(Debug)]
+pub struct ConsoleTimer<'a> {
+    label: &'a str,
+}
+
+impl<'a> ConsoleTimer<'a> {
+    /// Starts a console time measurement. The measurement
+    /// ends when the constructed `ConsoleTimer` object is dropped.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use gloo_console_timer::ConsoleTimer;
+    ///
+    /// let _timer = ConsoleTimer::new("foo");
+    /// ```
+    pub fn new(label: &'a str) -> ConsoleTimer<'a> {
+        console::time_with_label(label);
+        ConsoleTimer { label }
+    }
+
+    /// Starts a scoped console time measurement
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use gloo_console_timer::ConsoleTimer;
+    ///
+    /// let value = ConsoleTimer::scope("foo", || {
+    ///     // Code to measure here
+    /// });
+    /// ```
+    pub fn scope<F, T>(label: &str, f: F) -> T
+    where
+        F: FnOnce() -> T,
+    {
+        let _timer = ConsoleTimer::new(label);
+        f()
+    }
+}
+
+impl<'a> Drop for ConsoleTimer<'a> {
+    fn drop(&mut self) {
+        console::time_end_with_label(self.label);
+    }
+}

crates/console-timer/tests/web.rs

@@ -0,0 +1,15 @@
+//! Test suite for the Web and headless browsers.
+
+#![cfg(target_arch = "wasm32")]
+
+use gloo_console_timer::ConsoleTimer;
+use wasm_bindgen_test::*;
+
+wasm_bindgen_test_configure!(run_in_browser);
+
+#[wasm_bindgen_test]
+fn scoped_timer_returns_value() {
+    let value = ConsoleTimer::scope("foo", || true);
+
+    assert!(value);
+}

guide/book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["The Rust and WebAssembly Working Group"]
+multilingual = false
+src = "src"
+title = "Gloo Guide"

guide/src/SUMMARY.md

@@ -0,0 +1,6 @@
+# The Gloo Guide
+
+- [Introduction](./introduction.md)
+- [Using Gloo crates](./using-gloo.md)
+- [Timers](./timers.md)
+- [Console-timer](./console-timer.md)

guide/src/console-timer.md

@@ -0,0 +1 @@
+## Console Timer

guide/src/introduction.md

@@ -0,0 +1,14 @@
+# Introduction
+
+Welcome to the Gloo Guide, an introductory guide about [Gloo](https://github.com/rustwasm/gloo).
+Gloo is a toolkit for building web applications and libraries with Rust and Wasm, composed of 
+modular crates. [Gloo crates](https://github.com/rustwasm/gloo/tree/master/crates)
+include example code, both in their respective `example` folders, and commented in their code, as well
+as [API documentation](https://docs.rs/gloo/). The purpose of this guide is to complement these 
+by providing narritive description, 
+and step-by-step of how to use Gloo and its crates.
+ 
+This guide assumes familiarity with the [Rust language](https://www.rust-lang.org/), and web programming. 
+If you'd like to learn Rust,
+check out the [Rust Book](https://doc.rust-lang.org/book/index.html). The [MDN web docs](https://developer.mozilla.org/en-US/)
+is a good reference for web programming.

guide/src/timers.md

@@ -0,0 +1 @@
+## Timers

guide/src/using-gloo.md

@@ -0,0 +1 @@
+## Using Gloo crates

src/lib.rs

@@ -4,4 +4,5 @@
 #![deny(missing_docs, missing_debug_implementations)]
 
 // Re-exports of toolkit crates.
+pub use gloo_console_timer as console_timer;
 pub use gloo_timers as timers;