calog/vendor/mruby/mrbgems/hal-posix-task

hal-posix-task

POSIX Hardware Abstraction Layer (HAL) implementation for mruby-task.

Description

Provides timer and interrupt support for the mruby-task cooperative scheduler on POSIX-compliant platforms. Uses SIGALRM and setitimer() for periodic timer ticks, and sigprocmask() for interrupt protection.

Supported Platforms

• Linux
• macOS
• BSD (FreeBSD, OpenBSD, NetBSD)
• Other POSIX-compliant Unix systems

Requirements

• POSIX-compliant operating system
• Signal support (SIGALRM, sigaction, sigprocmask)
• Timer support (setitimer, ITIMER_REAL)

Usage

Explicit HAL Selection (Recommended)

MRuby::Build.new do |conf|
  # ... other configuration ...

  # Specify POSIX HAL - automatically brings in mruby-task
  conf.gem core: 'hal-posix-task'
end

Auto-detection (Development)

MRuby::Build.new do |conf|
  # ... other configuration ...

  # Auto-detects and selects hal-posix-task on POSIX platforms
  conf.gem core: 'mruby-task'
end

Implementation Details

Timer Mechanism

• Uses setitimer(ITIMER_REAL, ...) to generate periodic SIGALRM signals
• Timer interval configured by MRB_TICK_UNIT (default: 4ms)
• Signal handler calls mrb_tick() for all registered VM instances

Interrupt Protection

• Critical sections protected using sigprocmask() to block SIGALRM
• Prevents race conditions during task queue modifications
• Supports nested critical sections through signal masking

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)

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-posix-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

• SIGALRM conflicts with other code using the same signal
• Timer resolution limited by platform (typically 1-10ms)
• Signal delivery may be delayed under heavy system load
• Not suitable for hard real-time requirements

See Also

• mruby-task - Core task scheduler
• hal-win-task - Windows HAL implementation
• Task scheduler documentation: mrbgems/mruby-task/README.md