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

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.