elementdrawing 1.0.0

package/src/core/scheduler.c

@@ -0,0 +1,702 @@
+/*
+ * scheduler.c - ElementDrawing Core: Cooperative Scheduler
+ *
+ * Implements a priority-based cooperative scheduler for the
+ * ElementDrawing engine. Supports multiple priority levels,
+ * frame budget tracking, yielding for main thread responsiveness,
+ * and task lifecycle management.
+ */
+
+#include "bridge.h"
+
+/* ================================================================
+ * Internal Constants
+ * ================================================================ */
+
+#define ED_SCHEDULER_IMMEDIATE_INDEX   1
+#define ED_SCHEDULER_USER_BLOCK_INDEX  2
+#define ED_SCHEDULER_NORMAL_INDEX      3
+#define ED_SCHEDULER_LOW_INDEX         4
+#define ED_SCHEDULER_IDLE_INDEX        5
+
+/* ================================================================
+ * Scheduler Task Pool
+ * ================================================================ */
+
+typedef struct EDSchedulerTaskPool {
+    EDSchedulerTask* free_list;
+    uint32_t allocated;
+    uint32_t returned;
+} EDSchedulerTaskPool;
+
+static EDSchedulerTaskPool g_task_pool = {0};
+
+static EDSchedulerTask* ed_task_alloc(void)
+{
+    if (g_task_pool.free_list) {
+        EDSchedulerTask* task = g_task_pool.free_list;
+        g_task_pool.free_list = task->next;
+        g_task_pool.free_list = NULL;
+        memset(task, 0, sizeof(EDSchedulerTask));
+        task->is_running = false;
+        task->is_cancelled = false;
+        g_task_pool.allocated++;
+        return task;
+    }
+
+    EDSchedulerTask* task = (EDSchedulerTask*)calloc(1, sizeof(EDSchedulerTask));
+    if (task) g_task_pool.allocated++;
+    return task;
+}
+
+static void ed_task_free(EDSchedulerTask* task)
+{
+    if (!task) return;
+    task->next = g_task_pool.free_list;
+    g_task_pool.free_list = task;
+    g_task_pool.returned++;
+}
+
+/* ================================================================
+ * Expiration Time Computation
+ * ================================================================ */
+
+static uint64_t ed_scheduler_compute_expiration(EDSchedulerPriority priority)
+{
+    uint64_t now = ed_get_timestamp_ms();
+
+    switch (priority) {
+        case ED_PRIORITY_IMMEDIATE:
+            return now; /* Must execute immediately */
+        case ED_PRIORITY_USER_BLOCKING:
+            return now + 100; /* 100ms budget */
+        case ED_PRIORITY_NORMAL:
+            return now + ED_FIBER_WORK_EXPIRATION; /* 5s budget */
+        case ED_PRIORITY_LOW:
+            return now + 10000; /* 10s budget */
+        case ED_PRIORITY_IDLE:
+            return UINT64_MAX; /* No deadline */
+        default:
+            return now + ED_FIBER_WORK_EXPIRATION;
+    }
+}
+
+/* ================================================================
+ * Priority Queue Index Mapping
+ * ================================================================ */
+
+static uint32_t ed_priority_to_index(EDSchedulerPriority priority)
+{
+    if (priority >= ED_SCHEDULER_MIN_PRIORITY && priority <= ED_SCHEDULER_MAX_PRIORITY) {
+        return (uint32_t)priority;
+    }
+    return ED_SCHEDULER_NORMAL_INDEX;
+}
+
+/* ================================================================
+ * Scheduler Creation and Destruction
+ * ================================================================ */
+
+EDScheduler* ed_scheduler_create(void)
+{
+    EDScheduler* scheduler = (EDScheduler*)calloc(1, sizeof(EDScheduler));
+    if (!scheduler) return NULL;
+
+    /* Initialize priority queues (indices 1-5) */
+    for (int i = 0; i < 6; i++) {
+        scheduler->queues[i] = NULL;
+        scheduler->queue_sizes[i] = 0;
+    }
+
+    scheduler->total_tasks = 0;
+    scheduler->completed_tasks = 0;
+    scheduler->cancelled_tasks = 0;
+    scheduler->frame_start = 0;
+    scheduler->frame_deadline = 0;
+    scheduler->is_working = false;
+    scheduler->should_yield = false;
+    scheduler->current_priority = ED_PRIORITY_NORMAL;
+    scheduler->current_task = NULL;
+    scheduler->next_task_id = 1;
+
+    ed_log_debug("Scheduler created");
+    return scheduler;
+}
+
+void ed_scheduler_destroy(EDScheduler* scheduler)
+{
+    if (!scheduler) return;
+
+    /* Cancel and free all tasks in all priority queues */
+    for (int i = 0; i < 6; i++) {
+        EDSchedulerTask* task = scheduler->queues[i];
+        while (task) {
+            EDSchedulerTask* next = task->next;
+            task->is_cancelled = true;
+            ed_task_free(task);
+            task = next;
+        }
+        scheduler->queues[i] = NULL;
+    }
+
+    ed_log_debug("Scheduler destroyed (completed=%u, cancelled=%u)",
+                 scheduler->completed_tasks, scheduler->cancelled_tasks);
+
+    free(scheduler);
+}
+
+/* ================================================================
+ * Task Scheduling
+ * ================================================================ */
+
+uint32_t ed_scheduler_schedule(EDScheduler* scheduler, EDSchedulerPriority priority,
+                                EDSchedulerCallback callback, void* data)
+{
+    if (!scheduler || !callback) return 0;
+
+    uint32_t idx = ed_priority_to_index(priority);
+
+    /* Check queue capacity */
+    if (scheduler->queue_sizes[idx] >= ED_SCHEDULER_MAX_QUEUE_SIZE) {
+        ed_log_warn("Scheduler queue %u full (%u tasks), dropping task",
+                    idx, scheduler->queue_sizes[idx]);
+        return 0;
+    }
+
+    /* Allocate task */
+    EDSchedulerTask* task = ed_task_alloc();
+    if (!task) return 0;
+
+    task->id = scheduler->next_task_id++;
+    task->priority = priority;
+    task->callback = callback;
+    task->data = data;
+    task->expiration_time = ed_scheduler_compute_expiration(priority);
+    task->start_time = 0;
+    task->is_running = false;
+    task->is_cancelled = false;
+    task->is_recurring = false;
+    task->interval_ms = 0;
+
+    /* Insert into priority queue (sorted by expiration time) */
+    EDSchedulerTask** prev = &scheduler->queues[idx];
+    EDSchedulerTask* current = scheduler->queues[idx];
+
+    while (current && current->expiration_time <= task->expiration_time) {
+        prev = &current->next;
+        current = current->next;
+    }
+
+    task->next = current;
+    *prev = task;
+
+    scheduler->queue_sizes[idx]++;
+    scheduler->total_tasks++;
+
+    ed_log_debug("Scheduled task %u (priority=%u, expiration=%llu)",
+                 task->id, priority,
+                 (unsigned long long)task->expiration_time);
+
+    return task->id;
+}
+
+/* ================================================================
+ * Task Cancellation
+ * ================================================================ */
+
+bool ed_scheduler_cancel(EDScheduler* scheduler, uint32_t task_id)
+{
+    if (!scheduler || task_id == 0) return false;
+
+    /* Search all priority queues for the task */
+    for (int i = 0; i < 6; i++) {
+        EDSchedulerTask** prev = &scheduler->queues[i];
+        EDSchedulerTask* task = scheduler->queues[i];
+
+        while (task) {
+            if (task->id == task_id) {
+                task->is_cancelled = true;
+
+                /* Remove from queue */
+                *prev = task->next;
+                scheduler->queue_sizes[i]--;
+                scheduler->cancelled_tasks++;
+
+                /* If currently running, just mark cancelled */
+                if (task->is_running) {
+                    ed_log_debug("Task %u marked for cancellation (running)", task_id);
+                    return true;
+                }
+
+                ed_task_free(task);
+                ed_log_debug("Task %u cancelled", task_id);
+                return true;
+            }
+            prev = &task->next;
+            task = task->next;
+        }
+    }
+
+    ed_log_warn("Task %u not found for cancellation", task_id);
+    return false;
+}
+
+/* ================================================================
+ * Work Execution
+ * ================================================================ */
+
+static EDSchedulerTask* ed_scheduler_pick_next_task(EDScheduler* scheduler)
+{
+    if (!scheduler) return NULL;
+
+    /* Pick the highest priority task with the earliest deadline */
+    for (int i = 1; i < 6; i++) {
+        if (scheduler->queues[i]) {
+            EDSchedulerTask* task = scheduler->queues[i];
+            scheduler->queues[i] = task->next;
+            scheduler->queue_sizes[i]--;
+            return task;
+        }
+    }
+
+    return NULL;
+}
+
+void ed_scheduler_work(EDScheduler* scheduler)
+{
+    if (!scheduler) return;
+
+    scheduler->is_working = true;
+    scheduler->frame_start = ed_get_timestamp_ms();
+    scheduler->frame_deadline = scheduler->frame_start + ED_SCHEDULER_FRAME_BUDGET;
+    scheduler->should_yield = false;
+
+    uint32_t tasks_executed = 0;
+
+    while (!scheduler->should_yield) {
+        EDSchedulerTask* task = ed_scheduler_pick_next_task(scheduler);
+        if (!task) break; /* No more tasks */
+
+        /* Skip cancelled tasks */
+        if (task->is_cancelled) {
+            ed_task_free(task);
+            continue;
+        }
+
+        /* Execute the task */
+        scheduler->current_task = task;
+        scheduler->current_priority = task->priority;
+        task->is_running = true;
+        task->start_time = ed_get_timestamp_ms();
+
+        ed_log_debug("Executing task %u (priority=%u)",
+                     task->id, task->priority);
+
+        /* Call the task callback */
+        if (task->callback) {
+            task->callback(task->data);
+        }
+
+        task->is_running = false;
+        scheduler->current_task = NULL;
+        scheduler->completed_tasks++;
+        tasks_executed++;
+
+        /* Handle recurring tasks */
+        if (task->is_recurring && !task->is_cancelled) {
+            task->is_running = false;
+            task->start_time = 0;
+            task->expiration_time = ed_get_timestamp_ms() + task->interval_ms;
+            task->next = NULL;
+
+            /* Re-insert into queue */
+            uint32_t idx = ed_priority_to_index(task->priority);
+            EDSchedulerTask** prev = &scheduler->queues[idx];
+            EDSchedulerTask* current = scheduler->queues[idx];
+            while (current && current->expiration_time <= task->expiration_time) {
+                prev = &current->next;
+                current = current->next;
+            }
+            task->next = current;
+            *prev = task;
+            scheduler->queue_sizes[idx]++;
+        } else {
+            ed_task_free(task);
+        }
+
+        /* Check if we should yield */
+        if (ed_scheduler_should_yield(scheduler)) {
+            scheduler->should_yield = true;
+            ed_log_debug("Scheduler yielding after %u tasks", tasks_executed);
+        }
+
+        /* Safety: limit tasks per frame */
+        if (tasks_executed >= ED_SCHEDULER_MAX_CALLBACKS) {
+            ed_log_warn("Scheduler hit max callbacks per frame (%u)",
+                        tasks_executed);
+            break;
+        }
+    }
+
+    scheduler->is_working = false;
+    scheduler->current_priority = ED_PRIORITY_NORMAL;
+}
+
+/* ================================================================
+ * Yield Detection
+ * ================================================================ */
+
+bool ed_scheduler_should_yield(EDScheduler* scheduler)
+{
+    if (!scheduler) return false;
+
+    /* Check frame deadline */
+    uint64_t now = ed_get_timestamp_ms();
+    if (now >= scheduler->frame_deadline) {
+        return true;
+    }
+
+    /* Check if higher priority work arrived */
+    if (scheduler->current_priority > ED_PRIORITY_IMMEDIATE) {
+        for (int i = 1; i < (int)scheduler->current_priority; i++) {
+            if (scheduler->queue_sizes[i] > 0) {
+                return true; /* Higher priority work pending */
+            }
+        }
+    }
+
+    return false;
+}
+
+/* ================================================================
+ * Flush Operations
+ * ================================================================ */
+
+void ed_scheduler_flush_all(EDScheduler* scheduler)
+{
+    if (!scheduler) return;
+
+    uint64_t saved_deadline = scheduler->frame_deadline;
+    scheduler->frame_deadline = UINT64_MAX; /* Effectively infinite deadline */
+    scheduler->should_yield = false;
+
+    /* Execute all remaining tasks */
+    uint32_t total = 0;
+    while (true) {
+        EDSchedulerTask* task = ed_scheduler_pick_next_task(scheduler);
+        if (!task) break;
+
+        if (task->is_cancelled) {
+            ed_task_free(task);
+            continue;
+        }
+
+        scheduler->current_task = task;
+        task->is_running = true;
+        task->start_time = ed_get_timestamp_ms();
+
+        if (task->callback) {
+            task->callback(task->data);
+        }
+
+        task->is_running = false;
+        scheduler->completed_tasks++;
+        total++;
+        ed_task_free(task);
+    }
+
+    scheduler->frame_deadline = saved_deadline;
+    scheduler->should_yield = false;
+    scheduler->current_task = NULL;
+
+    ed_log_debug("Flushed all scheduler tasks (%u executed)", total);
+}
+
+void ed_scheduler_advance(EDScheduler* scheduler)
+{
+    if (!scheduler) return;
+
+    /* Advance the frame: update frame timing */
+    scheduler->frame_start = ed_get_timestamp_ms();
+    scheduler->frame_deadline = scheduler->frame_start + ED_SCHEDULER_FRAME_BUDGET;
+    scheduler->should_yield = false;
+}
+
+/* ================================================================
+ * Priority and Status Queries
+ * ================================================================ */
+
+EDSchedulerPriority ed_scheduler_get_current_priority(EDScheduler* scheduler)
+{
+    return scheduler ? scheduler->current_priority : ED_PRIORITY_NORMAL;
+}
+
+void ed_scheduler_start_profiling(EDScheduler* scheduler)
+{
+    if (!scheduler) return;
+    /* In a real implementation, enable detailed timing collection */
+    ed_log_debug("Scheduler profiling started");
+}
+
+void ed_scheduler_stop_profiling(EDScheduler* scheduler)
+{
+    if (!scheduler) return;
+    ed_log_debug("Scheduler profiling stopped");
+}
+
+uint64_t ed_scheduler_get_frame_deadline(EDScheduler* scheduler)
+{
+    return scheduler ? scheduler->frame_deadline : 0;
+}
+
+uint32_t ed_scheduler_get_pending_count(EDScheduler* scheduler)
+{
+    if (!scheduler) return 0;
+
+    uint32_t total = 0;
+    for (int i = 1; i < 6; i++) {
+        total += scheduler->queue_sizes[i];
+    }
+    return total;
+}
+
+/* ================================================================
+ * Recurring Task Support
+ * ================================================================ */
+
+static uint32_t ed_scheduler_schedule_recurring(EDScheduler* scheduler,
+                                                  EDSchedulerPriority priority,
+                                                  EDSchedulerCallback callback,
+                                                  void* data,
+                                                  uint32_t interval_ms)
+{
+    if (!scheduler || !callback || interval_ms == 0) return 0;
+
+    uint32_t task_id = ed_scheduler_schedule(scheduler, priority, callback, data);
+    if (task_id == 0) return 0;
+
+    /* Find the task and mark it as recurring */
+    uint32_t idx = ed_priority_to_index(priority);
+    EDSchedulerTask* task = scheduler->queues[idx];
+    while (task) {
+        if (task->id == task_id) {
+            task->is_recurring = true;
+            task->interval_ms = interval_ms;
+            break;
+        }
+        task = task->next;
+    }
+
+    return task_id;
+}
+
+/* ================================================================
+ * Deferred Value Scheduling
+ *
+ * Implements the deferred value pattern: schedule a low-priority
+ * update that can be interrupted by higher priority work.
+ * ================================================================ */
+
+typedef struct EDDeferredValue {
+    void* value;
+    EDSchedulerPriority priority;
+    uint32_t task_id;
+} EDDeferredValue;
+
+static void ed_scheduler_deferred_callback(void* data)
+{
+    EDDeferredValue* deferred = (EDDeferredValue*)data;
+    if (!deferred) return;
+
+    /* In a real implementation, this would trigger a re-render
+     * with the deferred value */
+    ed_log_debug("Deferred value update executed (priority=%u)",
+                 deferred->priority);
+}
+
+static uint32_t ed_scheduler_schedule_deferred(EDScheduler* scheduler,
+                                                 void* value,
+                                                 EDSchedulerPriority priority)
+{
+    if (!scheduler) return 0;
+
+    EDDeferredValue* deferred = (EDDeferredValue*)calloc(1, sizeof(EDDeferredValue));
+    if (!deferred) return 0;
+
+    deferred->value = value;
+    deferred->priority = priority;
+    deferred->task_id = 0;
+
+    EDSchedulerPriority effective_priority =
+        (priority < ED_PRIORITY_LOW) ? ED_PRIORITY_LOW : priority;
+
+    uint32_t task_id = ed_scheduler_schedule(
+        scheduler, effective_priority,
+        ed_scheduler_deferred_callback, deferred);
+
+    deferred->task_id = task_id;
+    return task_id;
+}
+
+/* ================================================================
+ * Transition Scheduling
+ *
+ * Implements the startTransition pattern: schedule work at
+ * a lower priority that doesn't block user input.
+ * ================================================================ */
+
+typedef struct EDTransition {
+    void (*callback)(void* data);
+    void* data;
+    bool is_pending;
+} EDTransition;
+
+static void ed_scheduler_transition_callback(void* data)
+{
+    EDTransition* transition = (EDTransition*)data;
+    if (!transition || !transition->callback) return;
+
+    transition->is_pending = true;
+    transition->callback(transition->data);
+    transition->is_pending = false;
+}
+
+static uint32_t ed_scheduler_start_transition(EDScheduler* scheduler,
+                                                void (*callback)(void*),
+                                                void* data)
+{
+    if (!scheduler || !callback) return 0;
+
+    EDTransition* transition = (EDTransition*)calloc(1, sizeof(EDTransition));
+    if (!transition) return 0;
+
+    transition->callback = callback;
+    transition->data = data;
+    transition->is_pending = false;
+
+    return ed_scheduler_schedule(
+        scheduler, ED_PRIORITY_LOW,
+        ed_scheduler_transition_callback, transition);
+}
+
+/* ================================================================
+ * Starvation Prevention
+ *
+ * Prevents low-priority tasks from being starved by continuously
+ * arriving high-priority tasks. After a configurable number of
+ * high-priority tasks, we promote one lower-priority task.
+ * ================================================================ */
+
+#define ED_STARVATION_THRESHOLD 50
+#define ED_STARVATION_BOOST_DURATION 1
+
+typedef struct EDStarvationState {
+    uint32_t consecutive_high_priority;
+    uint32_t boost_count;
+    bool is_boosting;
+} EDStarvationState;
+
+static EDStarvationState g_starvation = {0};
+
+static bool ed_scheduler_check_starvation(EDScheduler* scheduler)
+{
+    if (!scheduler) return false;
+
+    /* If we've executed too many high-priority tasks in a row,
+     * it's time to boost lower priority */
+    if (g_starvation.consecutive_high_priority >= ED_STARVATION_THRESHOLD) {
+        g_starvation.is_boosting = true;
+        g_starvation.boost_count = ED_STARVATION_BOOST_DURATION;
+        g_starvation.consecutive_high_priority = 0;
+        return true;
+    }
+
+    if (g_starvation.is_boosting) {
+        g_starvation.boost_count--;
+        if (g_starvation.boost_count == 0) {
+            g_starvation.is_boosting = false;
+        }
+        return true;
+    }
+
+    return false;
+}
+
+static void ed_scheduler_record_priority_executed(EDSchedulerPriority priority)
+{
+    if (priority <= ED_PRIORITY_USER_BLOCKING) {
+        g_starvation.consecutive_high_priority++;
+    } else {
+        g_starvation.consecutive_high_priority = 0;
+    }
+}
+
+/* ================================================================
+ * Batch Scheduling
+ *
+ * Schedule multiple tasks as a group, ensuring they are all
+ * processed in the same frame if possible.
+ * ================================================================ */
+
+typedef struct EDScheduleBatch {
+    uint32_t task_ids[ED_SCHEDULER_MAX_CALLBACKS];
+    uint32_t count;
+} EDScheduleBatch;
+
+static void ed_scheduler_batch_init(EDScheduleBatch* batch)
+{
+    if (!batch) return;
+    batch->count = 0;
+}
+
+static uint32_t ed_scheduler_batch_add(EDScheduler* scheduler, EDScheduleBatch* batch,
+                                        EDSchedulerPriority priority,
+                                        EDSchedulerCallback callback, void* data)
+{
+    if (!scheduler || !batch || !callback) return 0;
+    if (batch->count >= ED_SCHEDULER_MAX_CALLBACKS) return 0;
+
+    uint32_t id = ed_scheduler_schedule(scheduler, priority, callback, data);
+    if (id > 0) {
+        batch->task_ids[batch->count++] = id;
+    }
+    return id;
+}
+
+static void ed_scheduler_batch_cancel(EDScheduler* scheduler, EDScheduleBatch* batch)
+{
+    if (!scheduler || !batch) return;
+
+    for (uint32_t i = 0; i < batch->count; i++) {
+        ed_scheduler_cancel(scheduler, batch->task_ids[i]);
+    }
+    batch->count = 0;
+}
+
+/* ================================================================
+ * Scheduler Statistics
+ * ================================================================ */
+
+typedef struct EDSchedulerStats {
+    uint32_t total_scheduled;
+    uint32_t total_completed;
+    uint32_t total_cancelled;
+    uint32_t current_pending;
+    uint64_t total_execution_time;
+    uint32_t starvation_boosts;
+} EDSchedulerStats;
+
+static EDSchedulerStats ed_scheduler_get_stats(EDScheduler* scheduler)
+{
+    EDSchedulerStats stats = {0};
+    if (!scheduler) return stats;
+
+    stats.total_scheduled = scheduler->total_tasks;
+    stats.total_completed = scheduler->completed_tasks;
+    stats.total_cancelled = scheduler->cancelled_tasks;
+    stats.current_pending = ed_scheduler_get_pending_count(scheduler);
+    stats.total_execution_time = 0; /* Would accumulate from task timings */
+    stats.starvation_boosts = 0;
+
+    return stats;
+}