# Realtime Integration Guide / Hướng dẫn Tích hợp Realtime
## 📋 Overview / Tổng quan
Tài liệu này mô tả cách tích hợp tính năng Linux realtime (preempt_rt) vào ScriptTask và cách enable/disable tính năng này ở compile time.
## 🔧 Enabling Realtime Support / Bật Hỗ trợ Realtime
### Step 1: Uncomment DefineConstants / Bỏ comment DefineConstants
Trong file `RobotNet10.ScriptEngine.csproj`, uncomment dòng sau:
```xml
net10.0enableenable$(DefineConstants);REALTIME
```
### Step 2: Build Project / Build Dự án
```bash
dotnet build srcs/RobotNet10/Commons/RobotNet10.ScriptEngine/RobotNet10.ScriptEngine.csproj
```
Khi `REALTIME` symbol được define:
- Code realtime sẽ được compile vào binary
- ScriptTask sẽ sử dụng `RealtimeTimer` thay vì `System.Threading.Timer`
- Có thể configure realtime scheduling policy và CPU affinity
Khi `REALTIME` symbol **KHÔNG** được define:
- Code realtime sẽ bị loại bỏ hoàn toàn (không compile)
- ScriptTask sử dụng `System.Threading.Timer` (standard .NET timer)
- Không có dependency vào Linux-specific APIs
## 📝 Usage Examples / Ví dụ Sử dụng
### Example 1: Basic Realtime Task / Task Realtime Cơ bản
```csharp
using RobotNet10.ScriptEngine.Models;
using Microsoft.CodeAnalysis.Scripting;
// Create ScriptTaskModel with compiled script runner
var taskModel = new ScriptTaskModel(
name: "HighPriorityTask",
interval: 1, // 1 second
autoStart: true,
code: scriptCode,
runner: compiledScriptRunner
);
// Create ScriptGlobals with dictionaries
var globals = new ScriptGlobals(
scriptRobotNet: robotNetGlobals,
scriptApp: appGlobals,
scriptVariables: variables,
scriptParameters: parameters
);
// Create task with realtime options
var realtimeOptions = new RealtimeTaskOptions
{
Enabled = true,
SetSchedulingPolicy = true,
SchedulingPolicy = RealtimeSchedulingPolicy.Fifo,
Priority = 50,
ClockType = RealtimeClockType.Monotonic
};
var task = new ScriptTask(
model: taskModel,
globals: globals,
realtimeOptions: realtimeOptions
);
```
### Example 2: Task with CPU Affinity / Task với CPU Affinity
```csharp
var taskModel = new ScriptTaskModel(
name: "PinnedTask",
interval: 2,
autoStart: true,
code: scriptCode,
runner: compiledScriptRunner
);
var globals = new ScriptGlobals(
scriptRobotNet: robotNetGlobals,
scriptApp: appGlobals,
scriptVariables: variables,
scriptParameters: parameters
);
var realtimeOptions = new RealtimeTaskOptions
{
Enabled = true,
SetSchedulingPolicy = true,
SchedulingPolicy = RealtimeSchedulingPolicy.Fifo,
Priority = 75,
CpuAffinity = new[] { 0, 1 }, // Pin to CPU 0 and 1
ClockType = RealtimeClockType.Monotonic
};
var task = new ScriptTask(
model: taskModel,
globals: globals,
realtimeOptions: realtimeOptions
);
```
### Example 3: Disable Realtime for Specific Task / Tắt Realtime cho Task Cụ thể
```csharp
var taskModel = new ScriptTaskModel(
name: "StandardTask",
interval: 5,
autoStart: true,
code: scriptCode,
runner: compiledScriptRunner
);
var globals = new ScriptGlobals(
scriptRobotNet: robotNetGlobals,
scriptApp: appGlobals,
scriptVariables: variables,
scriptParameters: parameters
);
var realtimeOptions = new RealtimeTaskOptions
{
Enabled = false // Use standard timer even if REALTIME is defined
};
var task = new ScriptTask(
model: taskModel,
globals: globals,
realtimeOptions: realtimeOptions
);
```
### Example 4: Without Realtime Options / Không có Realtime Options
```csharp
var taskModel = new ScriptTaskModel(
name: "StandardTask",
interval: 10,
autoStart: true,
code: scriptCode,
runner: compiledScriptRunner
);
var globals = new ScriptGlobals(
scriptRobotNet: robotNetGlobals,
scriptApp: appGlobals,
scriptVariables: variables,
scriptParameters: parameters
);
// If realtimeOptions is null or not provided, uses standard timer
var task = new ScriptTask(
model: taskModel,
globals: globals
// realtimeOptions: null (default)
);
```
## ⚙️ RealtimeTaskOptions Configuration / Cấu hình RealtimeTaskOptions
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Enabled` | `bool` | `true` | Enable/disable realtime features for this task |
| `SetSchedulingPolicy` | `bool` | `true` | Whether to set realtime scheduling policy |
| `SchedulingPolicy` | `RealtimeSchedulingPolicy` | `Fifo` | SCHED_FIFO or SCHED_RR |
| `Priority` | `int` | `50` | Priority (1-99, higher = higher priority) |
| `CpuAffinity` | `int[]?` | `null` | CPU cores to pin thread to (null = no affinity) |
| `ClockType` | `RealtimeClockType` | `Monotonic` | Clock type for timer (Monotonic recommended) |
| `NonBlocking` | `bool` | `false` | **Note**: Always set to `true` internally for async monitoring |
## 🎯 How It Works / Cách Hoạt động
### Without REALTIME Symbol / Không có REALTIME Symbol
```mermaid
graph LR
A[ScriptTask.Start] --> B[System.Threading.Timer]
B --> C[ExecuteTask callback]
C --> D[Task execution]
```
### With REALTIME Symbol / Có REALTIME Symbol
```mermaid
graph LR
A[ScriptTask.Start] --> B{RealtimeOptions Enabled?}
B -->|Yes| C[RealtimeTimer timerfd]
B -->|No| D[System.Threading.Timer]
C --> E[Create Dedicated Thread Highest Priority]
E --> F[Set Scheduling Policy SCHED_FIFO/RR in thread]
E --> G[Set CPU Affinity in thread if configured]
E --> H[MonitorRealtimeTimer loop in thread]
H --> I[ReadExpirations non-blocking]
I --> J{Is Paused?}
J -->|No| K[ExecuteTask]
J -->|Yes| L[Skip Execution]
D --> K
```
## 🔑 Key Features / Tính năng Chính
### 1. High-Resolution Timer / Timer Độ phân giải Cao
- **RealtimeTimer**: Sử dụng Linux `timerfd` API
- **Accuracy**: Nanosecond precision
- **Better than**: `System.Threading.Timer` (millisecond precision)
### 2. Dedicated Thread with Highest Priority / Thread Riêng với Độ Ưu tiên Cao nhất
- **Dedicated Thread**: Tạo thread riêng cho realtime monitoring với `IsBackground = false`
- **Thread Priority**: Set SCHED_FIFO/SCHED_RR với priority cao nhất trong thread
- **Isolation**: Realtime monitoring chạy độc lập, không bị ảnh hưởng bởi các thread khác
- **CPU Affinity**: Pin thread to specific CPU cores (nếu configured)
- **Reduces cache misses**: Improves determinism
### 3. Real-time Scheduling / Lập lịch Real-time
- **SCHED_FIFO**: First-In-First-Out, highest priority threads run first
- **SCHED_RR**: Round-Robin, time-sliced real-time scheduling
- **Priority**: 1-99 (higher = higher priority)
- **Applied in thread**: Scheduling policy được set trong dedicated thread, không ảnh hưởng main thread
### 4. Pause/Resume Behavior / Hành vi Pause/Resume
- **Timer continues**: Khi paused, timer/realtime loop vẫn tiếp tục chạy
- **Skip execution**: Chỉ skip execution khi timer expire (check `_isPaused` flag)
- **Instant resume**: Resume ngay lập tức không cần restart timer
- **No interruption**: Timer không bị gián đoạn khi pause/resume
### 5. ScriptTask Constructor / Constructor của ScriptTask
- **ScriptTaskModel**: Nhận model chứa metadata và `ScriptRunner