109 lines
3.3 KiB
Markdown
Vendored
109 lines
3.3 KiB
Markdown
Vendored
# hal-win-task
|
|
|
|
Windows Hardware Abstraction Layer (HAL) implementation for mruby-task.
|
|
|
|
## Description
|
|
|
|
Provides timer and interrupt support for the mruby-task cooperative scheduler on Windows platforms. Uses multimedia timer (`timeSetEvent`/`timeKillEvent`) for periodic timer ticks, and `CRITICAL_SECTION` for interrupt protection.
|
|
|
|
## Supported Platforms
|
|
|
|
- Windows 7 and later
|
|
- Windows Server 2008 R2 and later
|
|
- All versions with multimedia timer support
|
|
|
|
## Requirements
|
|
|
|
- Windows operating system
|
|
- Multimedia timer API (`winmm.lib`)
|
|
- Visual C++, MinGW, or compatible compiler
|
|
|
|
## Usage
|
|
|
|
### Explicit HAL Selection (Recommended)
|
|
|
|
```ruby
|
|
MRuby::Build.new do |conf|
|
|
# ... other configuration ...
|
|
|
|
# Specify Windows HAL - automatically brings in mruby-task
|
|
conf.gem core: 'hal-win-task'
|
|
end
|
|
```
|
|
|
|
### Auto-detection (Development)
|
|
|
|
```ruby
|
|
MRuby::Build.new do |conf|
|
|
# ... other configuration ...
|
|
|
|
# Auto-detects and selects hal-win-task on Windows platforms
|
|
conf.gem core: 'mruby-task'
|
|
end
|
|
```
|
|
|
|
## Implementation Details
|
|
|
|
### Timer Mechanism
|
|
|
|
- Uses Windows multimedia timer (`timeSetEvent`) for periodic callbacks
|
|
- Timer interval configured by `MRB_TICK_UNIT` (default: 4ms)
|
|
- `TIME_KILL_SYNCHRONOUS` flag ensures clean timer shutdown
|
|
- Requests 1ms timer resolution via `timeBeginPeriod(1)`
|
|
|
|
### Interrupt Protection
|
|
|
|
- Critical sections protected using `CRITICAL_SECTION` objects
|
|
- Prevents race conditions during task queue modifications
|
|
- `EnterCriticalSection`/`LeaveCriticalSection` used for mutual exclusion
|
|
- Supports nested critical sections (automatic lock counting)
|
|
|
|
### Multi-VM Support
|
|
|
|
- Supports up to `MRB_TASK_MAX_VMS` concurrent mruby VM instances (default: 8)
|
|
- Single shared timer ticks all registered VMs
|
|
- Per-VM task counters optimize timer usage (timer disabled when idle)
|
|
- Interlocked operations (`InterlockedIncrement`/`InterlockedDecrement`) for thread safety
|
|
|
|
### Timer Optimization
|
|
|
|
The implementation dynamically enables/disables the timer based on task state:
|
|
|
|
- **Timer enabled** when: Multiple ready tasks OR any waiting tasks exist
|
|
- **Timer disabled** when: Single task or all tasks dormant/suspended
|
|
- Reduces CPU usage and power consumption when scheduler is idle
|
|
|
|
## Configuration
|
|
|
|
Override these macros in your build config if needed:
|
|
|
|
```ruby
|
|
conf.gem core: 'hal-win-task' do |spec|
|
|
# Custom tick interval (10ms instead of default 4ms)
|
|
spec.build.defines << 'MRB_TICK_UNIT=10'
|
|
|
|
# Custom timeslice (5 ticks instead of default 3)
|
|
spec.build.defines << 'MRB_TIMESLICE_TICK_COUNT=5'
|
|
|
|
# More concurrent VMs (16 instead of default 8)
|
|
spec.build.defines << 'MRB_TASK_MAX_VMS=16'
|
|
end
|
|
```
|
|
|
|
## Known Limitations
|
|
|
|
- Timer resolution typically limited to 1-2ms even with `timeBeginPeriod(1)`
|
|
- Multimedia timers consume system resources (kernel timer objects)
|
|
- Timer callbacks execute in separate thread context (handled internally)
|
|
- Not suitable for hard real-time requirements
|
|
- May interfere with other multimedia applications requesting different timer resolutions
|
|
|
|
## See Also
|
|
|
|
- `mruby-task` - Core task scheduler
|
|
- `hal-posix-task` - POSIX/Unix HAL implementation
|
|
- Task scheduler documentation: `mrbgems/mruby-task/README.md`
|
|
|
|
## Build Notes
|
|
|
|
The `winmm` library is automatically linked by the gem specification. No additional linker configuration is needed.
|