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)

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)

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:

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

Build Notes

The winmm library is automatically linked by the gem specification. No additional linker configuration is needed.

3.3 KiB Vendored Raw Blame History