### Create New Atomic Timer (Rust)

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Initializes a new AtomicTimer with a specified duration. The timer starts counting immediately, and its initial state is not expired. Useful for setting up countdowns.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;

// Create a 5-second timer
let timer = AtomicTimer::new(Duration::from_secs(5));

// Timer is not expired initially
assert!(!timer.expired());

// Check duration
assert_eq!(timer.duration(), Duration::from_secs(5));
```

--------------------------------

### AtomicTimer::new

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Creates a new atomic timer with a specified duration. The timer starts counting immediately upon creation.

```APIDOC
## AtomicTimer::new

### Description
Creates a new atomic timer with the specified duration. The timer starts immediately upon creation with elapsed time at zero.

### Method
`new`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;

// Create a 5-second timer
let timer = AtomicTimer::new(Duration::from_secs(5));
```

### Response
#### Success Response (200)
N/A (This is a constructor)

#### Response Example
N/A
```

--------------------------------

### AtomicTimer::reset

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Resets the timer to start counting from zero again. This operation is safe for concurrent use.

```APIDOC
## AtomicTimer::reset

### Description
Resets the timer to start counting from zero again. Does not require mutable reference, making it safe for concurrent use.

### Method
`reset`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_millis(100));

thread::sleep(Duration::from_millis(150));
assert!(timer.expired());

// Reset without mutable reference
timer.reset();

// Timer now counting from zero
assert!(!timer.expired());
assert!(timer.elapsed() < Duration::from_millis(50));
```

### Response
#### Success Response (200)
N/A (This is a mutator method)

#### Response Example
N/A
```

--------------------------------

### Get Elapsed Time (Rust)

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Retrieves the time that has passed since the AtomicTimer was created or last reset. If the calculated elapsed time is negative (which should not typically occur with monotonic time), it returns `Duration::ZERO`. This is useful for measuring durations or progress.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_secs(10));

thread::sleep(Duration::from_millis(500));

let elapsed = timer.elapsed();
// Elapsed time approximately 500ms
assert!(elapsed >= Duration::from_millis(450));
assert!(elapsed <= Duration::from_millis(600));
```

--------------------------------

### Get Remaining Time with AtomicTimer

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Retrieves the time left until the AtomicTimer expires. Returns Duration::ZERO if the timer has already expired. This function is crucial for monitoring timer status in real-time applications.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_secs(1));

let remaining = timer.remaining();
// Close to 1 second remaining
assert!(remaining > Duration::from_millis(900));

thread::sleep(Duration::from_millis(500));

let remaining = timer.remaining();
// Approximately 500ms remaining
assert!(remaining < Duration::from_millis(600));

thread::sleep(Duration::from_millis(600));

// Expired timer returns zero remaining
assert_eq!(timer.remaining(), Duration::ZERO);
```

--------------------------------

### Basic Atomic Timer Usage in Rust

Source: https://github.com/roboplc/atomic-timer/blob/main/README.md

Demonstrates the basic usage of the AtomicTimer in Rust. It initializes a timer with a specified duration and checks for expiration, elapsed time, and remaining time within a loop. The timer can be reset without needing a mutable reference.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;

let timer = AtomicTimer::new(Duration::from_secs(1));
for _ in 0..100 {
    if timer.expired() {
        println!("Timer expired");
        timer.reset(); // does not need to be mutable
    } else {
        println!("Elapsed: {:?}, remaining: {:?}", timer.elapsed(), timer.remaining());
    }
    // do some work
}
```

--------------------------------

### Serialize and Deserialize AtomicTimer State

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Demonstrates how to serialize and deserialize the state of an AtomicTimer using Serde. This feature, enabled via the 'serde' flag, allows for saving and restoring timer progress, including elapsed time, which is essential for persistence.

```rust
// Cargo.toml: atomic-timer = { version = "0.3", features = ["serde"] }

use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_secs(10));
thread::sleep(Duration::from_secs(2));

// Serialize timer state
let serialized = serde_json::to_string(&timer).unwrap();
// Output: {"duration":10000000000,"elapsed":2000000000,"phe":true}

// Deserialize preserves elapsed time
let restored: AtomicTimer = serde_json::from_str(&serialized).unwrap();

// Elapsed time is preserved (~2 seconds)
assert!(restored.elapsed() >= Duration::from_millis(1900));
assert!(restored.elapsed() <= Duration::from_millis(2100));
assert!(!restored.expired());
```

--------------------------------

### Multi-threaded Atomic Timer Usage in Rust

Source: https://github.com/roboplc/atomic-timer/blob/main/README.md

Illustrates how to use AtomicTimer in a multi-threaded Rust environment using `Arc` for shared ownership. It shows how to reset the timer only if it has expired, ensuring that the expiration logic is executed by only one thread.

```rust
use atomic_timer::AtomicTimer;
use std::sync::Arc;
use std::time::Duration;

let timer = Arc::new(AtomicTimer::new(Duration::from_secs(1)));
for _ in 0..10 {
    let timer = timer.clone();
    std::thread::spawn(move || {
        for _ in 0..100 {
            if timer.reset_if_expired() {
                println!("Timer expired");
                // react to the timer expiration
                // guaranteed to be true only for one thread
            }
            // do some other work
        }
    });
}
```

--------------------------------

### Create Pre-Expired Atomic Timer (Rust)

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Creates an AtomicTimer that is immediately in an expired state. This is useful for scenarios where an action should be triggered as soon as the timer is first checked or when a timer needs to be reset to a completed state.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;

// Create a pre-expired timer
let timer = AtomicTimer::new_expired(Duration::from_secs(1));

// Timer is immediately expired
assert!(timer.expired());
assert_eq!(timer.remaining(), Duration::ZERO);

// Reset to start fresh countdown
timer.reset();
assert!(!timer.expired());
```

--------------------------------

### Permit Handle Expiration (Rust)

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Provides a mechanism to signal that an expiration event has been observed, without resetting the timer. Returns `true` only once per expiration cycle across all threads, ensuring an event is handled atomically. The permit is reset when the timer is reset.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_millis(100));

// Not expired yet, returns false
assert!(!timer.permit_handle_expiration());

thread::sleep(Duration::from_millis(150));

// First call returns true
assert!(timer.permit_handle_expiration());

// Subsequent calls return false (flag consumed)
assert!(!timer.permit_handle_expiration());

// Reset restores the permit for next expiration
timer.reset();
```

--------------------------------

### AtomicTimer::permit_handle_expiration

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Returns `true` only once per expiration cycle across all threads, without resetting the timer.

```APIDOC
## AtomicTimer::permit_handle_expiration

### Description
Similar to `reset_if_expired` but does not reset the timer. Returns `true` only once per expiration cycle across all threads. The flag resets when the timer is reset.

### Method
`permit_handle_expiration`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_millis(100));

// Not expired yet, returns false
assert!(!timer.permit_handle_expiration());

thread::sleep(Duration::from_millis(150));

// First call returns true
assert!(timer.permit_handle_expiration());

// Subsequent calls return false (flag consumed)
assert!(!timer.permit_handle_expiration());

// Reset restores the permit for next expiration
timer.reset();
```

### Response
#### Success Response (200)
- **permit_granted** (bool) - `true` if this is the first call to grant a permit for the current expiration cycle, `false` otherwise.

#### Response Example
```json
{
  "permit_granted": true
}
```
```

--------------------------------

### Reset Atomic Timer (Rust)

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Resets the AtomicTimer to its initial state, effectively restarting the countdown from zero. This operation is safe for concurrent use as it does not require a mutable reference.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_millis(100));

thread::sleep(Duration::from_millis(150));
assert!(timer.expired());

// Reset without mutable reference
timer.reset();

// Timer now counting from zero
assert!(!timer.expired());
assert!(timer.elapsed() < Duration::from_millis(50));
```

--------------------------------

### AtomicTimer::new_expired

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Creates a new atomic timer that is initialized in an expired state.

```APIDOC
## AtomicTimer::new_expired

### Description
Creates a new atomic timer that is already in an expired state. Useful for triggering immediate action on first check.

### Method
`new_expired`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;

// Create a pre-expired timer
let timer = AtomicTimer::new_expired(Duration::from_secs(1));
```

### Response
#### Success Response (200)
N/A (This is a constructor)

#### Response Example
N/A
```

--------------------------------

### AtomicTimer::elapsed

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Returns the time elapsed since the timer was created or last reset.

```APIDOC
## AtomicTimer::elapsed

### Description
Returns the time elapsed since the timer was created or last reset. Returns `Duration::ZERO` if elapsed time is negative.

### Method
`elapsed`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_secs(10));

thread::sleep(Duration::from_millis(500));

let elapsed = timer.elapsed();
// Elapsed time approximately 500ms
assert!(elapsed >= Duration::from_millis(450));
assert!(elapsed <= Duration::from_millis(600));
```

### Response
#### Success Response (200)
- **elapsed_time** (Duration) - The time elapsed since the timer was created or last reset.

#### Response Example
```json
{
  "elapsed_time": "500ms"
}
```
```

--------------------------------

### Reset AtomicTimer to New Duration

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Sets a new duration for the AtomicTimer and resets its elapsed time to zero simultaneously. This operation effectively restarts the timer with a new interval, ensuring predictable timing from the moment of the call.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_secs(1));

thread::sleep(Duration::from_millis(500));

// Change to 2-second timer and reset
timer.reset_to_duration(Duration::from_secs(2));

assert_eq!(timer.duration(), Duration::from_secs(2));
assert!(!timer.expired());
assert!(timer.elapsed() < Duration::from_millis(50));
```

--------------------------------

### Force Expiration of AtomicTimer

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Immediately expires the AtomicTimer, regardless of its set duration. This is useful for manual control, cancellation, or testing scenarios where immediate timer termination is required.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;

let timer = AtomicTimer::new(Duration::from_secs(60));

// Timer not expired (has 60 seconds)
assert!(!timer.expired());
assert!(timer.remaining() > Duration::from_secs(59));

// Force immediate expiration
timer.expire_now();

// Timer now expired
assert!(timer.expired());
assert_eq!(timer.remaining(), Duration::ZERO);
```

--------------------------------

### Atomically Reset if Expired (Rust)

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Checks if the AtomicTimer has expired and resets it if it has. This method is designed for scenarios where only one thread should handle the expiration event. It returns `true` only to the thread that successfully performed the reset.

```rust
use atomic_timer::AtomicTimer;
use std::sync::Arc;
use std::time::Duration;
use std::thread;

let timer = Arc::new(AtomicTimer::new(Duration::from_millis(100)));

thread::sleep(Duration::from_millis(150));

// Spawn multiple threads checking expiration
let mut handles = vec![];
for i in 0..5 {
    let timer = timer.clone();
    handles.push(thread::spawn(move || {
        if timer.reset_if_expired() {
            println!("Thread {} handled expiration", i);
            return true;
        }
        false
    }));
}

// Only one thread will return true
let results: Vec<bool> = handles.into_iter().map(|h| h.join().unwrap()).collect();
assert_eq!(results.iter().filter(|&&v| v).count(), 1);
```

--------------------------------

### Check Timer Expiration (Rust)

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Determines if the AtomicTimer has reached or exceeded its set duration. This operation is atomic and non-blocking, suitable for frequent checks in multithreaded applications.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_millis(100));

// Timer not expired yet
assert!(!timer.expired());

// Wait for expiration
thread::sleep(Duration::from_millis(150));

// Timer now expired
assert!(timer.expired());
```

--------------------------------

### Change AtomicTimer Duration

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Modifies the duration of an existing AtomicTimer without resetting its elapsed time. This allows for dynamic adjustment of timer intervals during runtime, potentially leading to immediate expiration if the new duration is shorter than the elapsed time.

```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_secs(10));

thread::sleep(Duration::from_millis(100));

// Change duration to 50ms - timer becomes expired
timer.set_duration(Duration::from_millis(50));

assert!(timer.expired());
assert_eq!(timer.duration(), Duration::from_millis(50));
```

--------------------------------

### AtomicTimer::reset_if_expired

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Atomically checks if the timer has expired and resets it if so. Returns `true` if a reset occurred.

```APIDOC
## AtomicTimer::reset_if_expired

### Description
Atomically checks if the timer has expired and resets it if so. Returns `true` if reset occurred. In multi-threaded environments, only one thread receives `true`.

### Method
`reset_if_expired`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use atomic_timer::AtomicTimer;
use std::sync::Arc;
use std::time::Duration;
use std::thread;

let timer = Arc::new(AtomicTimer::new(Duration::from_millis(100)));

thread::sleep(Duration::from_millis(150));

// Spawn multiple threads checking expiration
let mut handles = vec![];
for i in 0..5 {
    let timer = timer.clone();
    handles.push(thread::spawn(move || {
        if timer.reset_if_expired() {
            println!("Thread {} handled expiration", i);
            return true;
        }
        false
    }));
}

// Only one thread will return true
let results: Vec<bool> = handles.into_iter().map(|h| h.join().unwrap()).collect();
assert_eq!(results.iter().filter(|&&v| v).count(), 1);
```

### Response
#### Success Response (200)
- **reset_occurred** (bool) - `true` if the timer was expired and reset, `false` otherwise.

#### Response Example
```json
{
  "reset_occurred": true
}
```
```

--------------------------------

### AtomicTimer::expired

Source: https://context7.com/roboplc/atomic-timer/llms.txt

Checks if the timer has expired. This is a non-blocking atomic read operation.

```APIDOC
## AtomicTimer::expired

### Description
Returns `true` if the timer has expired (elapsed time >= duration). This is a non-blocking atomic read operation.

### Method
`expired`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
use atomic_timer::AtomicTimer;
use std::time::Duration;
use std::thread;

let timer = AtomicTimer::new(Duration::from_millis(100));

// Timer not expired yet
assert!(!timer.expired());

// Wait for expiration
thread::sleep(Duration::from_millis(150));

// Timer now expired
assert!(timer.expired());
```

### Response
#### Success Response (200)
- **expired** (bool) - `true` if the timer has expired, `false` otherwise.

#### Response Example
```json
{
  "expired": true
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.