From 008fba5c6626c92694a8f071b2e510289da08e3d Mon Sep 17 00:00:00 2001 From: "Spencer C. Imbleau" Date: Wed, 21 Sep 2022 12:32:35 -0400 Subject: [PATCH 1/6] Closes #254, Documentation updates --- crates/timers/src/callback.rs | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/crates/timers/src/callback.rs b/crates/timers/src/callback.rs index eaa7d5ce..9d05365b 100644 --- a/crates/timers/src/callback.rs +++ b/crates/timers/src/callback.rs @@ -33,6 +33,8 @@ pub struct Timeout { } impl Drop for Timeout { + /// Disposes of the timeout, dually cancelling this timeout by calling + /// `clearTimeout` directly. fn drop(&mut self) { if let Some(id) = self.id { clear_timeout(id); @@ -71,7 +73,7 @@ impl Timeout { } } - /// Make this timeout uncancel-able. + /// Drops this resource without clearing the timeout. /// /// Returns the identifier returned by the original `setTimeout` call, and /// therefore you can still cancel the timeout by calling `clearTimeout` @@ -133,6 +135,8 @@ pub struct Interval { } impl Drop for Interval { + /// Disposes of the interval, dually cancelling this interval by calling + /// `clearInterval` directly. fn drop(&mut self) { if let Some(id) = self.id { clear_interval(id); @@ -170,7 +174,7 @@ impl Interval { } } - /// Make this interval uncancel-able. + /// Drops this resource without clearing the interval. /// /// Returns the identifier returned by the original `setInterval` call, and /// therefore you can still cancel the interval by calling `clearInterval` From c33a0fddabf9d4c7b719d658f82fcd25b51191d5 Mon Sep 17 00:00:00 2001 From: "Spencer C. Imbleau" Date: Wed, 21 Sep 2022 12:51:29 -0400 Subject: [PATCH 2/6] Improvements to #254 --- crates/timers/src/callback.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/crates/timers/src/callback.rs b/crates/timers/src/callback.rs index 9d05365b..21e598e1 100644 --- a/crates/timers/src/callback.rs +++ b/crates/timers/src/callback.rs @@ -23,8 +23,8 @@ extern "C" { /// /// See `Timeout::new` for scheduling new timeouts. /// -/// Once scheduled, you can either `cancel` so that it doesn't run or `forget` -/// it so that it is un-cancel-able. +/// Resource Acquisition Is Initialization (RAII). Once scheduled, you can +/// `cancel`/`drop` it or `forget` it to free memory, remaining scheduled. #[derive(Debug)] #[must_use = "timeouts cancel on drop; either call `forget` or `drop` explicitly"] pub struct Timeout { @@ -125,8 +125,8 @@ impl Timeout { /// /// See `Interval::new` for scheduling new intervals. /// -/// Once scheduled, you can either `cancel` so that it ceases to fire or `forget` -/// it so that it is un-cancel-able. +/// Resource Acquisition Is Initialization (RAII). Once scheduled, you can +/// `cancel`/`drop` it or `forget` it to free memory, remaining scheduled. #[derive(Debug)] #[must_use = "intervals cancel on drop; either call `forget` or `drop` explicitly"] pub struct Interval { From 074b78e56ba239e90c4839b9564d966a6a9cfd54 Mon Sep 17 00:00:00 2001 From: "Spencer C. Imbleau (he/him)" Date: Thu, 22 Sep 2022 20:35:18 -0400 Subject: [PATCH 3/6] Update crates/timers/src/callback.rs Co-authored-by: Muhammad Hamza --- crates/timers/src/callback.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/timers/src/callback.rs b/crates/timers/src/callback.rs index 21e598e1..e78915d7 100644 --- a/crates/timers/src/callback.rs +++ b/crates/timers/src/callback.rs @@ -73,7 +73,7 @@ impl Timeout { } } - /// Drops this resource without clearing the timeout. + /// Forgets this resource without clearing the timeout. /// /// Returns the identifier returned by the original `setTimeout` call, and /// therefore you can still cancel the timeout by calling `clearTimeout` From 3a27bc751c537ae94e5c3b4ccb687938c4b36f82 Mon Sep 17 00:00:00 2001 From: "Spencer C. Imbleau (he/him)" Date: Thu, 22 Sep 2022 20:35:24 -0400 Subject: [PATCH 4/6] Update crates/timers/src/callback.rs Co-authored-by: Muhammad Hamza --- crates/timers/src/callback.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/timers/src/callback.rs b/crates/timers/src/callback.rs index e78915d7..3d3e29ae 100644 --- a/crates/timers/src/callback.rs +++ b/crates/timers/src/callback.rs @@ -125,8 +125,8 @@ impl Timeout { /// /// See `Interval::new` for scheduling new intervals. /// -/// Resource Acquisition Is Initialization (RAII). Once scheduled, you can -/// `cancel`/`drop` it or `forget` it to free memory, remaining scheduled. +/// Once scheduled, you can [`drop`] the [`Interval`] to clear it or [`forget`](Interval::forget) to leak it. Once forgotten, the interval will keep running forever. +/// This pattern is known as Resource Acquisition Is Initialization (RAII). #[derive(Debug)] #[must_use = "intervals cancel on drop; either call `forget` or `drop` explicitly"] pub struct Interval { From d8f864ba7b30e98efb41eb69ce1448775b9d0e90 Mon Sep 17 00:00:00 2001 From: "Spencer C. Imbleau (he/him)" Date: Thu, 22 Sep 2022 20:35:30 -0400 Subject: [PATCH 5/6] Update crates/timers/src/callback.rs Co-authored-by: Muhammad Hamza --- crates/timers/src/callback.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/timers/src/callback.rs b/crates/timers/src/callback.rs index 3d3e29ae..d42884df 100644 --- a/crates/timers/src/callback.rs +++ b/crates/timers/src/callback.rs @@ -23,8 +23,8 @@ extern "C" { /// /// See `Timeout::new` for scheduling new timeouts. /// -/// Resource Acquisition Is Initialization (RAII). Once scheduled, you can -/// `cancel`/`drop` it or `forget` it to free memory, remaining scheduled. +/// Once scheduled, you can [`drop`] the [`Timeout`] to clear it or [`forget`](Timeout::forget) to leak it. Once forgotten, the interval will keep running forever. +/// This pattern is known as Resource Acquisition Is Initialization (RAII). #[derive(Debug)] #[must_use = "timeouts cancel on drop; either call `forget` or `drop` explicitly"] pub struct Timeout { From 1396cbdac12ba0898467f3c879e440d9a79d9ab7 Mon Sep 17 00:00:00 2001 From: "Spencer C. Imbleau (he/him)" Date: Thu, 22 Sep 2022 20:38:53 -0400 Subject: [PATCH 6/6] Update callback.rs --- crates/timers/src/callback.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/timers/src/callback.rs b/crates/timers/src/callback.rs index d42884df..fbc89bd6 100644 --- a/crates/timers/src/callback.rs +++ b/crates/timers/src/callback.rs @@ -174,7 +174,7 @@ impl Interval { } } - /// Drops this resource without clearing the interval. + /// Forget this resource without clearing the interval. /// /// Returns the identifier returned by the original `setInterval` call, and /// therefore you can still cancel the interval by calling `clearInterval`