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:

#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:

#include <robot/walltime.h>

API Reference

WallTime

Constructors

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

Static Methods

// 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

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

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

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

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

WallDuration

Constructors

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

Instance Methods

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

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

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

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

#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

#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

#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

#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

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

Sử dụng trong 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