add WallTime và WallTimer

2026-01-13 14:29:16 +07:00
parent 35b77e9fa2
commit 750dc94c61
12 changed files with 3225 additions and 1 deletions
--- a/WALLTIME_LIBRARY.md
+++ b/WALLTIME_LIBRARY.md
@@ -0,0 +1,362 @@
+# 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
+