From 552f236bb4fc3e0ec61fed3d39c8315b3a2d1e0b Mon Sep 17 00:00:00 2001
From: Hixie <github.com@spam.hixie.ch>
Date: Tue, 19 May 2015 15:20:01 -0700
Subject: [PATCH] More concrete Scheduler API proposal

Review URL: https://codereview.chromium.org/1139573005
---
 specs/scheduler.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 specs/scheduler.md

diff --git a/specs/scheduler.md b/specs/scheduler.md
new file mode 100644
index 00000000000..71e04cd8c82
--- /dev/null
+++ b/specs/scheduler.md
@@ -0,0 +1,57 @@
+Scheduler API
+=============
+
+```dart
+typedef void TimerCallback();
+
+class TaskSettings {
+  const TaskSettings({
+    this.idle: false, // tasks that should run during the idle phase
+    this.layout: false, // tasks that should run during the layout phase
+    this.paint: false, // tasks that should run during the paint phase
+    this.touch: false, // tasks that should run while a pointer is down
+  });
+  final bool idle;
+  final bool layout;
+  final bool paint;
+  final bool touch;
+}
+
+const idleTask = const TaskSettings(idle: true);
+const t0 = null;
+const t1ms = const Duration(milliseconds: 1.0);
+
+// Priorities
+// (these are intentionally not constants, so you can tweak them at runtime)
+int IdlePriority = 0; // tasks that can be delayed arbitrarily
+int FutureLayoutPriority = 1000; // tasks that prepare layout
+int TimerAnimationPriority = 3000; // tasks related to animations 
+int InputPriority = 4000; // input events
+int InputAnimationPriority = 5000; // framework-fired events for scrolling
+
+class Task {
+  external Task(callback, {
+    Duration delay: t0, // how long to wait before scheduling this task; null means run it now (same as duration 0)
+    Duration budget: t1ms, // how long to allow the task to run before firing an exception; null means no timeout
+    TaskSettings settings: idleTask, // what phases to allow the task to run during
+    int priority: 0, // the greater the number, the more likely it is to run
+    bool defer: false // punts this task until the next loop (after we're done with paint)
+  });
+  external void cancel(); // prevents the task from running, if it hasn't run yet
+  external bool get active; // true until fired or until canceled
+}
+
+// The Dart native mechanisms for scheduling tasks, as listed below,
+// get configured as follows:
+//
+//  delay: duration argument for the Timer constructors, otherwise null (0)
+//  budget: 1ms
+//  settings: same as for the task that triggered this task
+//  priority: same as for the task that triggered this task
+//  defer: false
+//
+// method: scheduleMicrotask(Function void callback())
+// constructor: Future.microtask(...) // calls scheduleMicrotask() to do the work
+// constructor: Timer (Duration duration, Function void callback())
+// constructor: Timer.periodic(Duration duration, Function void callback(Timer timer))
+```