robot_time/WALLTIME_LIBRARY.md

# WallTime Standalone Library

## Tổng quan

`walltime.h` là một **header-only library** độc lập cung cấp các class `WallTime` và `WallDuration` để làm việc với thời gian thực (wall-clock time). Thư viện này có thể được sử dụng độc lập hoặc như một phần của `robot_time` library.

## Đặc điểm

- ✅ **Header-only**: Chỉ cần include một file header
- ✅ **Không cần khởi tạo**: Có thể sử dụng ngay
- ✅ **Thread-safe**: An toàn khi sử dụng trong multi-threaded applications
- ✅ **Cross-platform**: Hoạt động trên Linux, Windows, macOS
- ✅ **Nanosecond precision**: Độ chính xác nanosecond
- ✅ **Không phụ thuộc**: Chỉ sử dụng C++ standard library

## Cài đặt

### Cách 1: Sử dụng trực tiếp (Header-only)

Chỉ cần copy file `walltime.h` vào project của bạn:

```cpp
#include "walltime.h"  // hoặc đường dẫn tương đối
```

### Cách 2: Sử dụng với robot_time library

Nếu bạn đã có `robot_time` library:

```cpp
#include <robot/walltime.h>
```

## API Reference

### WallTime

#### Constructors

```cpp
robot::WallTime t1;                          // Default: (0, 0)
robot::WallTime t2(1234567890, 123456789);  // (sec, nsec)
robot::WallTime t3(1234567890.123456789);   // From seconds (double)
```

#### Static Methods

```cpp
// Get current wall-clock time
robot::WallTime now = robot::WallTime::now();

// Sleep until a specific time
robot::WallTime target = robot::WallTime::now() + robot::WallDuration(5.0);
bool success = robot::WallTime::sleepUntil(target);

// Check if using system time (always true)
bool is_system = robot::WallTime::isSystemTime();  // Always returns true
```

#### Instance Methods

```cpp
robot::WallTime t = robot::WallTime::now();

// Convert to seconds
double seconds = t.toSec();

// Convert to nanoseconds
uint64_t nanoseconds = t.toNSec();

// Initialize from seconds
t.fromSec(1234567890.123456789);

// Initialize from nanoseconds
t.fromNSec(1234567890123456789ULL);

// Check if zero
bool is_zero = t.isZero();
```

#### Arithmetic Operations

```cpp
robot::WallTime t = robot::WallTime::now();
robot::WallDuration d(5.0);

// Addition
robot::WallTime future = t + d;

// Subtraction
robot::WallTime past = t - d;

// Duration subtraction
robot::WallDuration elapsed = future - t;

// Compound assignment
t += d;
t -= d;
```

#### Comparison Operators

```cpp
robot::WallTime t1, t2;

bool eq = (t1 == t2);
bool ne = (t1 != t2);
bool lt = (t1 < t2);
bool gt = (t1 > t2);
bool le = (t1 <= t2);
bool ge = (t1 >= t2);
```

#### Constants

```cpp
robot::WallTime::ZERO  // (0, 0)
robot::WallTime::MAX   // Maximum representable time
robot::WallTime::MIN   // Minimum representable time
```

### WallDuration

#### Constructors

```cpp
robot::WallDuration d1;                    // Default: (0, 0)
robot::WallDuration d2(5, 123456789);      // (sec, nsec)
robot::WallDuration d3(5.123456789);       // From seconds (double)
```

#### Instance Methods

```cpp
robot::WallDuration d(5.0);

// Convert to seconds
double seconds = d.toSec();

// Convert to nanoseconds
int64_t nanoseconds = d.toNSec();

// Initialize from seconds
d.fromSec(5.123456789);

// Initialize from nanoseconds
d.fromNSec(5123456789LL);

// Sleep for this duration
bool success = d.sleep();

// Check if zero
bool is_zero = d.isZero();
```

#### Arithmetic Operations

```cpp
robot::WallDuration d1(5.0);
robot::WallDuration d2(3.0);

// Addition
robot::WallDuration sum = d1 + d2;

// Subtraction
robot::WallDuration diff = d1 - d2;

// Negation
robot::WallDuration neg = -d1;

// Multiplication
robot::WallDuration scaled = d1 * 2.0;

// Compound assignment
d1 += d2;
d1 -= d2;
```

#### Comparison Operators

```cpp
robot::WallDuration d1, d2;

bool eq = (d1 == d2);
bool ne = (d1 != d2);
bool lt = (d1 < d2);
bool gt = (d1 > d2);
bool le = (d1 <= d2);
bool ge = (d1 >= d2);
```

#### Constants

```cpp
robot::WallDuration::ZERO  // (0, 0)
robot::WallDuration::MAX   // Maximum representable duration
robot::WallDuration::MIN   // Minimum representable duration (negative)
```

## Ví dụ sử dụng

### Ví dụ 1: Đo thời gian thực thi

```cpp
#include <robot/walltime.h>
#include <iostream>

void measureExecutionTime()
{
    robot::WallTime start = robot::WallTime::now();
    
    // Do some work
    for (int i = 0; i < 1000000; ++i)
    {
        // ... your code ...
    }
    
    robot::WallTime end = robot::WallTime::now();
    robot::WallDuration elapsed = end - start;
    
    std::cout << "Execution time: " << elapsed.toSec() << " seconds" << std::endl;
}
```

### Ví dụ 2: Timeout

```cpp
#include <robot/walltime.h>

bool doWorkWithTimeout(double timeout_seconds)
{
    robot::WallTime start = robot::WallTime::now();
    robot::WallDuration timeout(timeout_seconds);
    
    while (true)
    {
        if (robot::WallTime::now() - start > timeout)
        {
            std::cout << "Timeout!" << std::endl;
            return false;
        }
        
        // Do work
        if (workComplete())
        {
            return true;
        }
        
        robot::WallDuration(0.1).sleep();  // Sleep 100ms
    }
}
```

### Ví dụ 3: Sleep until

```cpp
#include <robot/walltime.h>

void scheduleTask()
{
    // Schedule task 5 seconds from now
    robot::WallTime target = robot::WallTime::now() + robot::WallDuration(5.0);
    
    // Do other work...
    
    // Sleep until target time
    robot::WallTime::sleepUntil(target);
    
    // Execute task
    executeTask();
}
```

### Ví dụ 4: Rate limiting

```cpp
#include <robot/walltime.h>

class RateLimiter
{
private:
    robot::WallTime last_time_;
    robot::WallDuration min_interval_;
    
public:
    RateLimiter(double min_rate_hz) 
        : min_interval_(1.0 / min_rate_hz)
        , last_time_(robot::WallTime::now())
    {}
    
    void wait()
    {
        robot::WallTime now = robot::WallTime::now();
        robot::WallDuration elapsed = now - last_time_;
        
        if (elapsed < min_interval_)
        {
            robot::WallDuration remaining = min_interval_ - elapsed;
            remaining.sleep();
        }
        
        last_time_ = robot::WallTime::now();
    }
};

// Usage
RateLimiter limiter(10.0);  // 10 Hz max
while (running)
{
    limiter.wait();
    doWork();
}
```

## So sánh với robot_time::WallTime

Thư viện standalone này tương thích với `robot::WallTime` trong `robot_time` library:

| Đặc điểm | Standalone `walltime.h` | `robot_time::WallTime` |
|----------|------------------------|------------------------|
| Header-only | ✅ Có | ❌ Cần link library |
| Dependencies | Chỉ C++ stdlib | Cần robot_time |
| API | Giống nhau | Giống nhau |
| Performance | Tương đương | Tương đương |
| Kích thước | Nhỏ hơn | Lớn hơn |

## Build và Test

### Compile test file

```bash
g++ -std=c++17 -I./include test/walltime_standalone_test.cpp -o walltime_test
./walltime_test
```

### Sử dụng trong CMake

```cmake
# Option 1: Header-only (không cần link)
target_include_directories(your_target PRIVATE 
    ${CMAKE_CURRENT_SOURCE_DIR}/include)

# Option 2: Với robot_time library
find_package(robot_time REQUIRED)
target_link_libraries(your_target PRIVATE robot_time)
```

## Requirements

- **C++17** hoặc cao hơn
- **Compiler**: GCC 7+, Clang 5+, MSVC 2017+

## License

BSD License - Tương tự như robot_time library

## Tài liệu tham khảo

- `WALLTIME_USAGE.md` - Hướng dẫn chi tiết về WallTime
- `examples/walltime_example.cpp` - Các ví dụ sử dụng
- `test/walltime_standalone_test.cpp` - Unit tests