feat: add one time job

Author: tuyentv96

Cargo.toml

@@ -33,5 +33,15 @@ name = "async_simple"
 path = "examples/async_simple.rs"
 required-features = ["async"]
 
+[[example]]
+name = "one_time_execution"
+path = "examples/one_time_execution.rs"
+required-features = ["sync"]
+
+[[example]]
+name = "async_one_time_execution"
+path = "examples/async_one_time_execution.rs"
+required-features = ["async"]
+
 [package.metadata.docs.rs]
 features = ["async", "sync"]

README.md

@@ -13,6 +13,7 @@ A lightweight, thread-safe cron job scheduler for Rust with support for both syn
 - ⚡ **Sync & Async** - Choose the execution mode that fits your application
 - 🌍 **Timezone Aware** - Full timezone support via chrono
 - 🎯 **Second Precision** - 7-field cron expressions with second-level scheduling
+- ⏰ **One-Time Execution** - Schedule tasks to run once at a specific time or after a delay
 - 🔧 **Runtime Control** - Add, remove, start, and stop jobs dynamically
 - 🛡️ **Thread Safe** - Built with Rust's safety guarantees
 
@@ -99,6 +100,61 @@ sec  min  hour  day  month  weekday  year
 
 ## Advanced Examples
 
+### One-Time Execution
+
+Schedule tasks to run exactly once at a specific time or after a delay:
+
+```rust
+use chrono::{Duration, Utc};
+use cron_tab::Cron;
+
+fn main() {
+    let mut cron = Cron::new(Utc);
+
+    // Execute once after a delay
+    cron.add_fn_after(std::time::Duration::from_secs(5), || {
+        println!("This runs once after 5 seconds");
+    }).unwrap();
+
+    // Execute once at a specific datetime
+    let target_time = Utc::now() + Duration::seconds(10);
+    cron.add_fn_once(target_time, || {
+        println!("This runs once at the specified time");
+    }).unwrap();
+
+    cron.start();
+    std::thread::sleep(std::time::Duration::from_secs(12));
+    cron.stop();
+}
+```
+
+### Async One-Time Execution
+
+```rust
+use chrono::{Duration, Utc};
+use cron_tab::AsyncCron;
+
+#[tokio::main]
+async fn main() {
+    let mut cron = AsyncCron::new(Utc);
+
+    // Execute once after a delay
+    cron.add_fn_after(std::time::Duration::from_secs(5), || async {
+        println!("Async task runs once after 5 seconds");
+    }).await.unwrap();
+
+    // Execute once at a specific datetime
+    let target_time = Utc::now() + Duration::seconds(10);
+    cron.add_fn_once(target_time, || async {
+        println!("Async task runs once at the specified time");
+    }).await.unwrap();
+
+    cron.start().await;
+    tokio::time::sleep(std::time::Duration::from_secs(12)).await;
+    cron.stop().await;
+}
+```
+
 ### Managing Jobs Dynamically
 
 ```rust
@@ -118,7 +174,7 @@ fn main() {
 
     // Remove the job dynamically
     cron.remove(job_id);
-    
+
     cron.stop();
 }
 ```

examples/async_one_time_execution.rs

@@ -0,0 +1,114 @@
+//! Example demonstrating async one-time task execution at a specific time or after a delay.
+//!
+//! This example shows how to use the `add_fn_once` and `add_fn_after` methods
+//! with async functions to schedule tasks that execute exactly once.
+
+use chrono::{Duration, Utc};
+use cron_tab::AsyncCron;
+use std::sync::Arc;
+use tokio::sync::Mutex;
+
+#[tokio::main]
+async fn main() {
+    println!("=== Async One-Time Task Execution Example ===\n");
+
+    let mut cron = AsyncCron::new(Utc);
+
+    // Shared counter to track execution
+    let counter = Arc::new(Mutex::new(0));
+
+    // Example 1: Execute once after a delay
+    println!("Scheduling async job to execute after 2 seconds...");
+    let counter1 = Arc::clone(&counter);
+    cron.add_fn_after(std::time::Duration::from_secs(2), move || {
+        let counter = Arc::clone(&counter1);
+        async move {
+            let mut count = counter.lock().await;
+            *count += 1;
+            println!("[After 2s] Async job executed! Counter: {}", *count);
+
+            // Simulate async work
+            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        }
+    })
+    .await
+    .unwrap();
+
+    // Example 2: Execute once at a specific datetime
+    let target_time = Utc::now() + Duration::seconds(4);
+    println!(
+        "Scheduling async job to execute at specific time: {}",
+        target_time.format("%H:%M:%S")
+    );
+    let counter2 = Arc::clone(&counter);
+    cron.add_fn_once(target_time, move || {
+        let counter = Arc::clone(&counter2);
+        async move {
+            let mut count = counter.lock().await;
+            *count += 10;
+            println!(
+                "[At {}] Async job executed! Counter: {}",
+                target_time.format("%H:%M:%S"),
+                *count
+            );
+
+            // Simulate async work
+            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        }
+    })
+    .await
+    .unwrap();
+
+    // Example 3: Execute once after 6 seconds
+    println!("Scheduling async job to execute after 6 seconds...");
+    let counter3 = Arc::clone(&counter);
+    cron.add_fn_after(std::time::Duration::from_secs(6), move || {
+        let counter = Arc::clone(&counter3);
+        async move {
+            let mut count = counter.lock().await;
+            *count += 100;
+            println!("[After 6s] Async job executed! Counter: {}", *count);
+
+            // Simulate async work
+            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
+        }
+    })
+    .await
+    .unwrap();
+
+    // Example 4: Mix with recurring job
+    println!("Scheduling recurring async job every 3 seconds...");
+    let recurring_counter = Arc::new(Mutex::new(0));
+    let recurring_counter1 = Arc::clone(&recurring_counter);
+    cron.add_fn("*/3 * * * * * *", move || {
+        let counter = Arc::clone(&recurring_counter1);
+        async move {
+            let mut count = counter.lock().await;
+            *count += 1;
+            println!("[Recurring] Executed {} times", *count);
+
+            // Simulate async work
+            tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+        }
+    })
+    .await
+    .unwrap();
+
+    // Start the scheduler
+    println!("\nStarting scheduler...\n");
+    cron.start().await;
+
+    // Let it run for 8 seconds
+    tokio::time::sleep(std::time::Duration::from_secs(8)).await;
+
+    // Stop the scheduler
+    cron.stop().await;
+
+    println!("\n=== Execution Complete ===");
+    println!("Final one-time counter: {}", *counter.lock().await);
+    println!(
+        "Final recurring counter: {}",
+        *recurring_counter.lock().await
+    );
+    println!("\nNote: One-time jobs execute exactly once and are automatically removed.");
+}

examples/one_time_execution.rs

@@ -0,0 +1,77 @@
+//! Example demonstrating one-time task execution at a specific time or after a delay.
+//!
+//! This example shows how to use the `add_fn_once` and `add_fn_after` methods
+//! to schedule tasks that execute exactly once.
+
+use chrono::{Duration, Utc};
+use cron_tab::Cron;
+use std::sync::{Arc, Mutex};
+
+fn main() {
+    println!("=== One-Time Task Execution Example ===\n");
+
+    let mut cron = Cron::new(Utc);
+
+    // Shared counter to track execution
+    let counter = Arc::new(Mutex::new(0));
+
+    // Example 1: Execute once after a delay
+    println!("Scheduling job to execute after 2 seconds...");
+    let counter1 = Arc::clone(&counter);
+    cron.add_fn_after(std::time::Duration::from_secs(2), move || {
+        let mut count = counter1.lock().unwrap();
+        *count += 1;
+        println!("[After 2s] Job executed! Counter: {}", *count);
+    })
+    .unwrap();
+
+    // Example 2: Execute once at a specific datetime
+    let target_time = Utc::now() + Duration::seconds(4);
+    println!(
+        "Scheduling job to execute at specific time: {}",
+        target_time.format("%H:%M:%S")
+    );
+    let counter2 = Arc::clone(&counter);
+    cron.add_fn_once(target_time, move || {
+        let mut count = counter2.lock().unwrap();
+        *count += 10;
+        println!("[At {}] Job executed! Counter: {}", target_time.format("%H:%M:%S"), *count);
+    })
+    .unwrap();
+
+    // Example 3: Execute once after 6 seconds
+    println!("Scheduling job to execute after 6 seconds...");
+    let counter3 = Arc::clone(&counter);
+    cron.add_fn_after(std::time::Duration::from_secs(6), move || {
+        let mut count = counter3.lock().unwrap();
+        *count += 100;
+        println!("[After 6s] Job executed! Counter: {}", *count);
+    })
+    .unwrap();
+
+    // Example 4: Mix with recurring job
+    println!("Scheduling recurring job every 3 seconds...");
+    let recurring_counter = Arc::new(Mutex::new(0));
+    let recurring_counter1 = Arc::clone(&recurring_counter);
+    cron.add_fn("*/3 * * * * * *", move || {
+        let mut count = recurring_counter1.lock().unwrap();
+        *count += 1;
+        println!("[Recurring] Executed {} times", *count);
+    })
+    .unwrap();
+
+    // Start the scheduler
+    println!("\nStarting scheduler...\n");
+    cron.start();
+
+    // Let it run for 8 seconds
+    std::thread::sleep(std::time::Duration::from_secs(8));
+
+    // Stop the scheduler
+    cron.stop();
+
+    println!("\n=== Execution Complete ===");
+    println!("Final one-time counter: {}", *counter.lock().unwrap());
+    println!("Final recurring counter: {}", *recurring_counter.lock().unwrap());
+    println!("\nNote: One-time jobs execute exactly once and are automatically removed.");
+}