enclave 0.1.0

data/ext/enclave/mruby/mrbgems/mruby-task/examples/inspection.rb

@@ -0,0 +1,65 @@
+# Task Inspection Example
+# Demonstrates task status and inspect methods
+
+puts "=== Task Inspection Demo ==="
+puts
+
+# Create some tasks
+worker1 = Task.new(name: "worker-1") do
+  puts "Worker 1: Starting"
+  puts "Worker 1: My status is #{Task.current.status}"
+  puts "Worker 1: My inspect is #{Task.current.inspect}"
+  sleep 0.5
+  puts "Worker 1: Finished"
+end
+
+worker2 = Task.new(name: "worker-2") do
+  sleep 1
+  puts "Worker 2: Finished"
+end
+
+# Inspect before running
+puts "Initial task states:"
+puts "  worker1: #{worker1.inspect}"
+puts "           status=#{worker1.status}"
+puts "  worker2: #{worker2.inspect}"
+puts "           status=#{worker2.status}"
+puts
+
+# Create an observer task
+observer = Task.new(name: "observer") do
+  sleep 0.2
+
+  puts "\nObserver checking task states:"
+  puts "  worker1: #{worker1.inspect}"
+  puts "           status=#{worker1.status}"
+  puts "  worker2: #{worker2.inspect}"
+  puts "           status=#{worker2.status}"
+
+  sleep 0.5
+
+  # Suspend worker2
+  worker2.suspend
+  puts "\nObserver suspended worker2:"
+  puts "  worker2: #{worker2.inspect}"
+  puts "           status=#{worker2.status}"
+
+  sleep 0.3
+
+  # Resume and terminate
+  worker2.resume
+  sleep 0.1
+  worker2.terminate
+
+  puts "\nObserver terminated worker2:"
+  puts "  worker2: #{worker2.inspect}"
+  puts "           status=#{worker2.status}"
+end
+
+# Run the scheduler
+Task.run
+
+puts "\n=== Final states ==="
+puts "  worker1: #{worker1.inspect} status=#{worker1.status}"
+puts "  worker2: #{worker2.inspect} status=#{worker2.status}"
+puts "  observer: #{observer.inspect} status=#{observer.status}"

data/ext/enclave/mruby/mrbgems/mruby-task/examples/priority.rb

@@ -0,0 +1,41 @@
+# Priority Scheduling Example
+# Lower priority values = higher priority (0 is highest)
+
+puts "=== Priority Scheduling Demo ==="
+puts
+
+# Create tasks with different priorities
+low_priority = Task.new(name: "low-priority", priority: 200) do
+  5.times do |i|
+    puts "  [Low Priority] iteration #{i}"
+    sleep 0.1
+  end
+end
+
+high_priority = Task.new(name: "high-priority", priority: 50) do
+  5.times do |i|
+    puts "[High Priority] iteration #{i}"
+    sleep 0.1
+  end
+end
+
+medium_priority = Task.new(name: "medium-priority", priority: 128) do
+  5.times do |i|
+    puts "    [Medium Priority] iteration #{i}"
+    sleep 0.1
+  end
+end
+
+puts "Created 3 tasks with different priorities:"
+puts "  High:   priority=50"
+puts "  Medium: priority=128"
+puts "  Low:    priority=200"
+puts
+puts "Tasks will run in priority order (highest first)"
+puts
+
+# Run the scheduler
+Task.run
+
+puts
+puts "=== All tasks completed ==="

data/ext/enclave/mruby/mrbgems/mruby-task/examples/producer_consumer.rb

@@ -0,0 +1,58 @@
+# Producer/Consumer Example
+# Demonstrates task coordination using shared state
+
+puts "=== Producer/Consumer Demo ==="
+puts
+
+# Shared buffer
+$buffer = []
+$max_items = 10
+$produced = 0
+
+# Producer task
+producer = Task.new(name: "producer") do
+  $max_items.times do |i|
+    # Produce an item
+    item = "item-#{i}"
+    $buffer << item
+    $produced += 1
+    puts "Producer: created #{item} (buffer size: #{$buffer.size})"
+
+    sleep 0.3
+  end
+  puts "Producer: finished producing #{$max_items} items"
+end
+
+# Consumer task
+consumer = Task.new(name: "consumer") do
+  consumed = 0
+
+  while consumed < $max_items
+    if $buffer.empty?
+      puts "Consumer: buffer empty, waiting..."
+      sleep 0.2
+    else
+      item = $buffer.shift
+      consumed += 1
+      puts "Consumer: consumed #{item} (#{consumed}/#{$max_items})"
+      sleep 0.5
+    end
+  end
+
+  puts "Consumer: finished consuming #{consumed} items"
+end
+
+# Monitor task
+monitor = Task.new(name: "monitor") do
+  loop do
+    sleep 1
+    puts "Monitor: produced=#{$produced}, buffer=#{$buffer.size}, remaining=#{$max_items - $produced}"
+    break if $produced >= $max_items && $buffer.empty?
+  end
+end
+
+# Run the scheduler
+Task.run
+
+puts "\n=== All tasks completed ==="
+puts "Final state: produced=#{$produced}, buffer=#{$buffer.size}"

data/ext/enclave/mruby/mrbgems/mruby-task/examples/simple.rb

@@ -0,0 +1,27 @@
+# Simple Task Example
+# Basic usage of mruby-task
+
+puts "=== Simple Task Demo ==="
+puts
+
+# Create a simple task
+Task.new(name: "hello") do
+  3.times do |i|
+    puts "Hello from task, iteration #{i}"
+    sleep 0.5
+  end
+end
+
+# Create another task
+Task.new(name: "world") do
+  3.times do |i|
+    puts "World from task, iteration #{i}"
+    sleep 0.7
+  end
+end
+
+# Run the scheduler - blocks until all tasks complete
+puts "Starting tasks..."
+Task.run
+
+puts "All tasks completed!"

data/ext/enclave/mruby/mrbgems/mruby-task/examples/statistics.rb

@@ -0,0 +1,59 @@
+# Task Statistics Example
+# Demonstrates Task.stat for monitoring scheduler state
+
+def print_stats(label)
+  stat = Task.stat
+  puts "\n#{label}"
+  puts "  Tick: #{stat[:tick]}, Next wakeup: #{stat[:wakeup_tick]}"
+  puts "  Ready:     #{stat[:ready][:count]} tasks"
+  puts "  Waiting:   #{stat[:waiting][:count]} tasks"
+  puts "  Suspended: #{stat[:suspended][:count]} tasks"
+  puts "  Dormant:   #{stat[:dormant][:count]} tasks"
+end
+
+puts "=== Task Statistics Demo ==="
+
+print_stats("Initial state:")
+
+# Create several tasks
+workers = []
+5.times do |i|
+  workers << Task.new(name: "worker-#{i}") do
+    sleep 0.5
+    puts "Worker #{i} completed"
+  end
+end
+
+print_stats("After creating 5 tasks:")
+
+# Create a monitor task
+monitor = Task.new(name: "monitor") do
+  sleep 0.1
+  print_stats("Monitor: After 0.1s:")
+
+  # Suspend a couple tasks
+  workers[2].suspend
+  workers[3].suspend
+
+  print_stats("Monitor: After suspending 2 tasks:")
+
+  sleep 0.5
+
+  print_stats("Monitor: After 0.5s more:")
+
+  # Resume suspended tasks
+  workers[2].resume
+  workers[3].resume
+
+  print_stats("Monitor: After resuming tasks:")
+
+  # Wait for all workers
+  workers.each(&:join)
+end
+
+# Run the scheduler
+Task.run
+
+print_stats("Final state:")
+
+puts "\n=== Demo complete ==="

data/ext/enclave/mruby/mrbgems/mruby-task/examples/suspend_resume.rb

@@ -0,0 +1,47 @@
+# Suspend and Resume Example
+# Demonstrates manual task control
+
+puts "=== Suspend/Resume Demo ==="
+puts
+
+$counter = 0
+
+# Create a worker task
+worker = Task.new(name: "worker") do
+  10.times do |i|
+    puts "Worker: iteration #{i}, counter=#{$counter}"
+    $counter += 1
+    sleep 0.2
+  end
+  puts "Worker: finished!"
+end
+
+# Create a controller task
+controller = Task.new(name: "controller") do
+  sleep 0.5
+
+  puts "\nController: Suspending worker..."
+  worker.suspend
+  puts "Controller: Worker status = #{worker.status}"
+
+  sleep 1
+
+  puts "\nController: Incrementing counter while worker is suspended..."
+  5.times do
+    $counter += 10
+    puts "Controller: counter=#{$counter}"
+    sleep 0.2
+  end
+
+  puts "\nController: Resuming worker..."
+  worker.resume
+  puts "Controller: Worker status = #{worker.status}"
+
+  # Wait for worker to finish
+  worker.join
+end
+
+# Run the scheduler
+Task.run
+
+puts "\n=== Final counter value: #{$counter} ==="

data/ext/enclave/mruby/mrbgems/mruby-task/examples/task_pass.rb

@@ -0,0 +1,21 @@
+$global = 0
+task = Task.new do
+  10.times do |i|
+    puts "Task #{i} is running"
+    $global += 1
+    sleep 1
+  end
+end
+
+while true
+  sleep 0.5
+  if $global < 6
+    puts "Global variable is less than 6, waiting..."
+    Task.pass
+  else
+    break
+  end
+end
+
+puts "Global variable reached 6, exiting loop"
+Task.run

data/ext/enclave/mruby/mrbgems/mruby-task/include/task.h

@@ -0,0 +1,143 @@
+/*
+** task.h - Task scheduler
+**
+** See Copyright Notice in mruby.h
+*/
+
+#ifndef MRUBY_TASK_H
+#define MRUBY_TASK_H
+
+#include <mruby.h>
+
+/*
+ * Task status values (bit-mapped)
+ */
+enum {
+  MRB_TASK_STATUS_DORMANT   = 0x00,  /* Not started or finished */
+  MRB_TASK_STATUS_READY     = 0x02,  /* Ready to run */
+  MRB_TASK_STATUS_RUNNING   = 0x03,  /* Currently executing */
+  MRB_TASK_STATUS_WAITING   = 0x04,  /* Waiting for condition */
+  MRB_TASK_STATUS_SUSPENDED = 0x08,  /* Manually suspended */
+};
+
+/*
+ * Task wait reason
+ */
+enum {
+  MRB_TASK_REASON_NONE  = 0x00,  /* No specific reason */
+  MRB_TASK_REASON_SLEEP = 0x01,  /* Sleeping for time */
+  MRB_TASK_REASON_MUTEX = 0x02,  /* Waiting for mutex (reserved) */
+  MRB_TASK_REASON_JOIN  = 0x04,  /* Waiting for another task */
+};
+
+/*
+ * Task structure - represents a single task in the scheduler
+ *
+ * Memory-optimized layout:
+ * - Removed priority_preemption (always equals priority): 1 byte
+ * - Removed started flag (inferred from c.status): 1 byte
+ * - Unified wakeup_tick/join/mutex into single union: 4 bytes
+ * - Removed redundant proc field (stored in c.ci->proc): 8 bytes
+ * - Unified timeslice/result into state union: ~4 bytes
+ * Total savings: ~18 bytes per task (14% reduction)
+ */
+typedef struct mrb_task {
+  struct mrb_task *next;           /* Linked list pointer */
+  uint8_t priority;                /* Priority (0-255, 0=highest) */
+  uint8_t status;                  /* Current status (TASKSTATUS enum) */
+  uint8_t reason;                  /* Wait reason (TASKREASON enum) */
+  mrb_value name;                  /* Optional task name */
+
+  /* Wait-specific data - mutually exclusive based on reason field */
+  union {
+    uint32_t wakeup_tick;          /* Tick count to wake up (REASON_SLEEP) */
+    const struct mrb_task *join;   /* Task being waited on (REASON_JOIN) */
+    void *mutex;                   /* Mutex pointer (REASON_MUTEX, reserved) */
+  } wait;
+
+  mrb_value self;                  /* Ruby Task object reference */
+
+  /* State-specific data - mutually exclusive based on status */
+  union {
+    volatile uint8_t timeslice;    /* Remaining ticks (RUNNING only) */
+    mrb_value result;              /* Task return value (DORMANT only) */
+  } state;
+
+  struct mrb_context c;            /* Execution context (stack, callinfo, etc) */
+} mrb_task;
+
+/*
+ * Task queue configuration
+ * (mrb_task_state is defined in mruby.h)
+ */
+#define MRB_NUM_TASK_QUEUE 4
+
+/* Queue indices */
+#define MRB_TASK_QUEUE_DORMANT   0
+#define MRB_TASK_QUEUE_READY     1
+#define MRB_TASK_QUEUE_WAITING   2
+#define MRB_TASK_QUEUE_SUSPENDED 3
+
+/* Configuration */
+#ifndef MRB_TICK_UNIT
+#define MRB_TICK_UNIT 4  /* Tick period in milliseconds */
+#endif
+
+#ifndef MRB_TIMESLICE_TICK_COUNT
+#define MRB_TIMESLICE_TICK_COUNT 3  /* Number of ticks per timeslice */
+#endif
+
+#define TASK_STACK_INIT_SIZE 64   /* Initial task stack size */
+#define TASK_CI_INIT_SIZE 4       /* Initial task callinfo size */
+
+/*
+ * HAL (Hardware Abstraction Layer) functions
+ * Platform-specific implementations must provide these
+ */
+void mrb_task_hal_init(mrb_state *mrb);
+void mrb_task_hal_final(mrb_state *mrb);
+void mrb_task_enable_irq(void);
+void mrb_task_disable_irq(void);
+void mrb_task_hal_idle_cpu(mrb_state *mrb);
+
+/*
+ * GC integration
+ */
+void mrb_task_mark_all(mrb_state *mrb);
+
+/*
+ * Core task scheduler API
+ */
+MRB_API void mrb_tick(mrb_state *mrb);
+MRB_API mrb_value mrb_task_run(mrb_state *mrb);
+MRB_API mrb_value mrb_task_run_once(mrb_state *mrb);
+
+/*
+ * Task creation API
+ */
+MRB_API mrb_value mrb_create_task(mrb_state *mrb, struct RProc *proc, mrb_value name, mrb_value priority, mrb_value top_self);
+
+/*
+ * Synchronous execution API (for picoruby-wasm)
+ */
+MRB_API mrb_value mrb_execute_proc_synchronously(mrb_state *mrb, mrb_value proc, mrb_int argc, const mrb_value *argv);
+
+/*
+ * Task control API
+ * Note: mrb_task_run is the main scheduler loop (for picoruby-sandbox and picoruby-wasm)
+ */
+MRB_API void mrb_suspend_task(mrb_state *mrb, mrb_value task);
+MRB_API void mrb_resume_task(mrb_state *mrb, mrb_value task);
+MRB_API void mrb_terminate_task(mrb_state *mrb, mrb_value task);
+MRB_API mrb_bool mrb_stop_task(mrb_state *mrb, mrb_value task);
+MRB_API mrb_value mrb_task_value(mrb_state *mrb, mrb_value task);
+MRB_API mrb_value mrb_task_status(mrb_state *mrb, mrb_value self);
+
+/*
+ * Task context management API (for picoruby-sandbox)
+ */
+MRB_API void mrb_task_init_context(mrb_state *mrb, mrb_value task, struct RProc *proc);
+MRB_API void mrb_task_reset_context(mrb_state *mrb, mrb_value task);
+MRB_API void mrb_task_proc_set(mrb_state *mrb, mrb_value task, struct RProc *proc);
+
+#endif /* MRUBY_TASK_H */

data/ext/enclave/mruby/mrbgems/mruby-task/include/task_hal.h

@@ -0,0 +1,162 @@
+/*
+** task_hal.h - Task scheduler Hardware Abstraction Layer (HAL)
+**
+** See Copyright Notice in mruby.h
+**
+** This header defines the HAL interface that platform-specific implementations
+** must provide. The HAL separates platform-specific timer and interrupt handling
+** from the core task scheduler logic.
+*/
+
+#ifndef MRUBY_TASK_HAL_H
+#define MRUBY_TASK_HAL_H
+
+#include <mruby.h>
+
+/*
+ * Configuration - can be overridden in platform-specific build configs
+ */
+
+/* Tick period in milliseconds - how often the timer fires */
+#ifndef MRB_TICK_UNIT
+#define MRB_TICK_UNIT 4
+#endif
+
+/* Number of timer ticks per task timeslice */
+#ifndef MRB_TIMESLICE_TICK_COUNT
+#define MRB_TIMESLICE_TICK_COUNT 3
+#endif
+
+/* Maximum number of concurrent mrb_state instances with task scheduler */
+#ifndef MRB_TASK_MAX_VMS
+#define MRB_TASK_MAX_VMS 8
+#endif
+
+/*
+ * HAL Interface Functions
+ *
+ * Platform-specific implementations (hal-posix-task, hal-win-task, etc.)
+ * must provide these functions.
+ */
+
+/**
+ * Initialize hardware timer and interrupt system
+ *
+ * Called once during mruby-task gem initialization. Should set up a periodic
+ * timer that calls mrb_tick(mrb) every MRB_TICK_UNIT milliseconds.
+ *
+ * Requirements:
+ * - Initialize platform-specific timer hardware/APIs
+ * - Set up timer to fire every MRB_TICK_UNIT milliseconds
+ * - Register mrb_state for multi-VM support if needed
+ * - Initialize interrupt protection mechanisms (mutexes, signal masks, etc.)
+ * - Timer should call mrb_tick() on each tick for all registered VMs
+ *
+ * @param mrb The mruby state to associate with the timer
+ */
+void mrb_hal_task_init(mrb_state *mrb);
+
+/**
+ * Cleanup timer and interrupt resources
+ *
+ * Called during mruby-task gem finalization. Should clean up all resources
+ * allocated by mrb_hal_task_init().
+ *
+ * Requirements:
+ * - Stop and cleanup platform timer
+ * - Unregister mrb_state from multi-VM support
+ * - Free any allocated HAL resources
+ * - If last VM, cleanup global HAL state
+ *
+ * @param mrb The mruby state to disassociate from the timer
+ */
+void mrb_hal_task_final(mrb_state *mrb);
+
+/**
+ * Enable timer interrupts (exit critical section)
+ *
+ * Called by the task scheduler when it's safe to allow timer interrupts.
+ * Should enable timer interrupts/callbacks that were disabled by
+ * mrb_task_disable_irq().
+ *
+ * Requirements:
+ * - Must be reentrant (can be called multiple times)
+ * - Should use nesting counter or equivalent for nested critical sections
+ * - On POSIX: unmask signals
+ * - On Windows: leave critical section
+ * - On embedded: enable timer interrupts
+ */
+void mrb_task_enable_irq(void);
+
+/**
+ * Disable timer interrupts (enter critical section)
+ *
+ * Called by the task scheduler before modifying shared task state.
+ * Should disable timer interrupts/callbacks to prevent concurrent access.
+ *
+ * Requirements:
+ * - Must be reentrant (can be called multiple times)
+ * - Should use nesting counter or equivalent for nested critical sections
+ * - On POSIX: block signals
+ * - On Windows: enter critical section
+ * - On embedded: disable timer interrupts
+ */
+void mrb_task_disable_irq(void);
+
+/**
+ * Put CPU in low-power/idle mode
+ *
+ * Called by the scheduler when no tasks are ready to run but some tasks
+ * are waiting or suspended. Should briefly idle the CPU or sleep for
+ * approximately MRB_TICK_UNIT milliseconds to allow timer to fire.
+ *
+ * Requirements:
+ * - Should return when timer fires or after ~MRB_TICK_UNIT milliseconds
+ * - Must allow timer interrupts to occur during idle
+ * - On POSIX: usleep() or nanosleep()
+ * - On Windows: Sleep()
+ * - On embedded: platform-specific sleep/wait-for-interrupt instruction
+ *
+ * @param mrb The mruby state (for context, may be unused)
+ */
+void mrb_hal_task_idle_cpu(mrb_state *mrb);
+
+/**
+ * Sleep for specified microseconds in wall-clock time
+ *
+ * Called by sleep functions when in root context (not in a task).
+ * Should sleep for the specified number of microseconds in real wall-clock
+ * time, allowing timer interrupts to occur during the sleep.
+ *
+ * Requirements:
+ * - Sleep for approximately usec microseconds in wall-clock time
+ * - Must allow timer interrupts/callbacks during sleep
+ * - Should handle interruptions gracefully and complete full sleep duration
+ * - On POSIX: use clock_gettime + nanosleep loop for accuracy
+ * - On Windows: use Sleep() with millisecond conversion
+ * - On embedded: platform-specific delay with interrupt support
+ *
+ * @param mrb The mruby state (for context, may be unused)
+ * @param usec Number of microseconds to sleep
+ */
+void mrb_hal_task_sleep_us(mrb_state *mrb, mrb_int usec);
+
+/*
+ * Core scheduler function (implemented in task.c, called by HAL)
+ */
+
+/**
+ * Tick handler - advances scheduler time and wakes sleeping tasks
+ *
+ * HAL timer callback must call this function every MRB_TICK_UNIT milliseconds
+ * for each registered mrb_state. This function:
+ * - Increments the global tick counter
+ * - Decrements running task's timeslice
+ * - Wakes tasks whose sleep time has expired
+ * - Triggers context switches when needed
+ *
+ * @param mrb The mruby state to tick
+ */
+void mrb_tick(mrb_state *mrb);
+
+#endif /* MRUBY_TASK_HAL_H */

data/ext/enclave/mruby/mrbgems/mruby-task/mrbgem.rake

@@ -0,0 +1,36 @@
+MRuby::Gem::Specification.new('mruby-task') do |spec|
+  spec.license = 'MIT'
+  spec.authors = 'mruby developers'
+  spec.summary = 'Cooperative multitasking with preemptive scheduling'
+
+  # Enable task scheduler globally (required for vm.c integration)
+  spec.build.defines << 'MRB_USE_TASK_SCHEDULER'
+
+  # Check if HAL gem is loaded
+  # HAL gems must be explicitly specified in build config (recommended) or via auto-selection below
+  spec.build.gems.one? { |g| g.name =~ /^hal-.*-task$/ } or begin
+    # No HAL found - determine appropriate error message or auto-load
+    suggested_hal = if spec.for_windows?
+      # Windows (including MinGW) - use Windows HAL
+      'hal-win-task'
+    elsif RUBY_PLATFORM =~ /linux|darwin|bsd/
+      'hal-posix-task'
+    else
+      nil
+    end
+
+    if suggested_hal
+      # Auto-load HAL gem for convenience (for development)
+      # This works because HAL gems declare dependency on mruby-task
+      warn "mruby-task: No HAL specified, loading #{suggested_hal} (explicit selection recommended)"
+      spec.build.gem core: suggested_hal
+    else
+      # Unknown platform - fail with helpful message
+      fail "mruby-task: No HAL available for platform '#{RUBY_PLATFORM}'.\n" \
+           "Please specify HAL gem explicitly in your build config:\n" \
+           "  conf.gem core: 'hal-posix-task'   # For Linux/macOS/BSD\n" \
+           "  conf.gem core: 'hal-win-task'     # For Windows\n" \
+           "Or create custom HAL - see mrbgems/mruby-task/README.md"
+    end
+  end
+end