# RobotNet10.Realtime

## Overview / Tổng quan

`RobotNet10.Realtime` là một wrapper library cho các tính năng realtime của Linux preempt_rt kernel. Library này cung cấp các API .NET để sử dụng các tính năng realtime như scheduling policies, CPU affinity, memory locking, và high-resolution timers.

## Features / Tính năng

- **Real-time Scheduling**: SCHED_FIFO, SCHED_RR scheduling policies
- **CPU Affinity**: Pin threads to specific CPU cores
- **Memory Locking**: Prevent memory from being swapped to disk
- **High-resolution Timers**: timerfd-based timers for precise timing
- **High-resolution Clocks**: Access to CLOCK_MONOTONIC and other Linux clocks

## Requirements / Yêu cầu

- Linux kernel with preempt_rt patch
- .NET 10.0 runtime
- Root privileges may be required for some operations (scheduling policies, memory locking)

## Usage Examples / Ví dụ Sử dụng

### Real-time Scheduling

```csharp
using RobotNet10.Realtime;

// Set SCHED_FIFO policy with priority 50
RealtimeScheduler.SetSchedulingPolicy(RealtimeSchedulingPolicy.Fifo, 50);

// Get current policy and priority
var policy = RealtimeScheduler.GetSchedulingPolicy();
var priority = RealtimeScheduler.GetPriority();

// Change priority only
RealtimeScheduler.SetPriority(75);
```

### CPU Affinity

```csharp
using RobotNet10.Realtime;

// Pin current thread to CPU 0 and 1
CpuAffinity.SetAffinity(0, 1);

// Or use CpuAffinity class for more control
var affinity = new CpuAffinity();
affinity.AddCpu(0);
affinity.AddCpu(2);
affinity.Apply();

// Get current affinity
var currentAffinity = CpuAffinity.GetAffinity();
var cpus = currentAffinity.GetCpus(); // List of CPU numbers
```

### Memory Locking

```csharp
using RobotNet10.Realtime;

// Lock all current and future memory pages
MemoryLock.LockAll(MemoryLockFlags.Current | MemoryLockFlags.Future);

// Lock a specific array
var array = new byte[1024 * 1024];
var handle = MemoryLock.LockArray(array);
try
{
    // Use array...
}
finally
{
    handle.Free();
    MemoryLock.Unlock(handle.AddrOfPinnedObject(), new IntPtr(array.Length));
}
```

### High-resolution Timer

```csharp
using RobotNet10.Realtime;

// Create a periodic timer
using var timer = new RealtimeTimer(RealtimeClockType.Monotonic);
timer.SetPeriodic(TimeSpan.FromMilliseconds(10)); // 10ms interval

// In a loop, read expirations
while (running)
{
    ulong expirations = timer.ReadExpirations();
    if (expirations > 0)
    {
        // Timer expired, do work
        DoWork();
    }
}

// One-shot timer
timer.SetOneShot(TimeSpan.FromSeconds(5)); // Fire once after 5 seconds
```

### High-resolution Clock

```csharp
using RobotNet10.Realtime;

// Use monotonic clock for measuring elapsed time
var clock = new RealtimeClock(RealtimeClockType.Monotonic);
var startTime = clock.GetTimeSpan();

// Do work...

var elapsed = clock.GetTimeSpan() - startTime;
Console.WriteLine($"Elapsed: {elapsed.TotalMilliseconds} ms");

// Get clock resolution
var resolution = clock.GetResolution();
Console.WriteLine($"Clock resolution: {resolution.TotalNanoseconds} ns");
```

## Important Notes / Lưu Ý Quan trọng

1. **Root Privileges**: Many real-time operations require root privileges. Run your application with `sudo` or set capabilities:
   ```bash
   sudo setcap cap_sys_nice+ep /path/to/your/app
   ```

2. **Memory Locking Limits**: The system has limits on how much memory can be locked. Check `/proc/sys/vm/max_locked_memory`.

3. **Priority Range**: Real-time priorities range from 1-99. Higher numbers = higher priority.

4. **Platform Specific**: This library only works on Linux. Use `#if` directives or runtime checks for cross-platform code.

5. **Thread Safety**: Most operations affect the current thread only. Use appropriate synchronization for multi-threaded applications.

## Error Handling / Xử lý Lỗi

All operations throw `RealtimeException` on failure:

```csharp
try
{
    RealtimeScheduler.SetSchedulingPolicy(RealtimeSchedulingPolicy.Fifo, 50);
}
catch (RealtimeException ex)
{
    Console.WriteLine($"Failed: {ex.Message}, errno: {ex.Errno}");
}
```

## Related Documents / Tài liệu Liên quan

- Linux man pages: `man 2 sched_setscheduler`, `man 2 timerfd_create`, etc.
- [Linux RT Wiki](https://rt.wiki.kernel.org/)
- [PREEMPT_RT Patch Documentation](https://wiki.linuxfoundation.org/realtime/documentation)