kyo.scheduler

Low-resolution clock optimized for frequent access in the scheduler.

While System.currentTimeMillis is accurate, calling it frequently creates significant overhead due to system calls. This clock uses a dedicated thread to update a volatile timestamp every millisecond, allowing other threads to read the current time without system calls.

The tradeoff of potentially being off by up to a millisecond is acceptable for scheduler operations like measuring task runtime and detecting stalled workers. The performance benefit of avoiding system calls on every time check is substantial when processing thousands of tasks per second.

The clock self-corrects any drift by measuring the actual elapsed time between updates.

A high-performance task scheduler with adaptive concurrency control and admission regulation.

The scheduler provides a foundation for concurrent task execution with features including dynamic worker pool sizing, admission control to prevent overload, work stealing for load balancing, task preemption, and comprehensive performance monitoring.

==Worker Management==

The scheduler maintains a pool of worker threads that execute tasks. The number of workers adjusts dynamically between configured minimum and maximum bounds based on system load and performance metrics. Workers can steal tasks from each other to balance load across the pool, ensuring efficient resource utilization.

==Admission Control==

An admission regulator prevents system overload by selectively rejecting tasks when the system shows signs of congestion. The admission rate adjusts automatically based on measured queuing delays, providing natural backpressure that helps maintain system stability under varying loads.

==Concurrency Control==

A concurrency regulator continuously monitors system scheduling efficiency through sophisticated timing measurements. By analyzing scheduling delays and system load, it dynamically adjusts the worker pool size to maintain optimal performance. The regulator detects both under-utilization and thread interference, scaling the thread count up or down accordingly.

==Thread Blocking and Adaptive Concurrency==

The scheduler employs a sophisticated approach to handle thread blocking that requires no explicit signaling or special handling from tasks. Instead of treating blocking as an exceptional case, the system embraces it as a natural part of task execution through its adaptive concurrency mechanism.

At its core, the scheduler uses an ephemeral thread model where workers acquire threads from a pool only when actively processing tasks. When a thread becomes blocked, the scheduler detects this through direct thread state inspection and automatically compensates by adjusting its concurrency level. This detection-and-response cycle creates a natural overflow capacity that maintains throughput even when many threads are blocked.

The design's effectiveness lies in its transparency: tasks can freely perform blocking operations without concerning themselves with thread management. When blocking occurs, the concurrency regulator observes increased scheduling delays and responds by expanding the worker pool if possible and necessary. As blocked threads resume, the improved scheduling efficiency triggers a gradual reduction in worker count.

==Loom Integration==

The scheduler seamlessly integrates with Java's Project Loom virtual threads when available, providing enhanced scalability for I/O-bound workloads. To enable virtual threads, add the JVM argument '--add-opens=java.base/java.lang=ALL-UNNAMED' and set '-Dkyo.scheduler.virtualizeWorkers=true'. The scheduler transparently manages virtual thread creation and scheduling through the worker executor.

==Monitoring==

Comprehensive metrics about scheduler operation are exposed through JMX and optional console reporting, providing detailed insight into worker utilization, task execution, regulation decisions, and system load.