From cedb809c21868db51d99bcad455287ea50a65a53 Mon Sep 17 00:00:00 2001
From: Thomas Harte <thomas.harte@gmail.com>
Date: Sun, 20 Aug 2017 10:53:25 -0400
Subject: [PATCH] =?UTF-8?q?Sketched=20out=20a=20protocol=20designed=20to?=
 =?UTF-8?q?=20save=20processing=20time=20on=20anything=20that=20may=20slee?=
 =?UTF-8?q?p=20=E2=80=94=20probably=20just=20disk=20controllers=20for=20no?=
 =?UTF-8?q?w=20but=20one=20can=20easily=20imagine=20it=20being=20applicabl?=
 =?UTF-8?q?e=20to=20printers,=20and=20possibly=20sound=20chips=20with=20su?=
 =?UTF-8?q?itable=20changes=20in=20guarantee=20for=20sound=20packet=20rece?=
 =?UTF-8?q?ivers.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ClockReceiver/Sleeper.h                       | 46 +++++++++++++++++++
 .../Clock Signal.xcodeproj/project.pbxproj    |  2 +
 2 files changed, 48 insertions(+)
 create mode 100644 ClockReceiver/Sleeper.h

diff --git a/ClockReceiver/Sleeper.h b/ClockReceiver/Sleeper.h
new file mode 100644
index 000000000..caa837cf8
--- /dev/null
+++ b/ClockReceiver/Sleeper.h
@@ -0,0 +1,46 @@
+//
+//  Sleeper.h
+//  Clock Signal
+//
+//  Created by Thomas Harte on 20/08/2017.
+//  Copyright © 2017 Thomas Harte. All rights reserved.
+//
+
+#ifndef Sleeper_h
+#define Sleeper_h
+
+/*!
+	A sleeper is any component that sometimes requires a clock but at other times is 'asleep' — i.e. is not doing
+	any clock-derived work, so needn't receive a clock. A disk controller is an archetypal example.
+
+	A sleeper will signal sleeps and wakes to an observer.
+
+	This is intended to allow for performance improvements to machines with components that can sleep. The observer
+	callout is virtual so the intended use case is that a machine holds a component that might sleep. Its transitions
+	into and out of sleep are sufficiently infrequent that a virtual call to announce them costs sufficiently little that
+	the saved ::run_fors add up to a substantial amount.
+
+	By convention, sleeper components must be willing to accept ::run_for even after announcing sleep. It's a hint,
+	not a command.
+*/
+class Sleeper {
+	public:
+		Sleeper() : sleep_observer_(nullptr) {}
+
+		class SleepObserver {
+			public:
+				/// Called to inform an observer that the component @c component has either gone to sleep or become awake.
+				void set_component_is_sleeping(void *component, bool is_sleeping) = 0;
+		};
+
+		/// Registers @c observer as the new sleep observer;
+		void set_sleep_observer(SleepObserver *observer) {
+			sleep_observer_ = delegate;
+		}
+
+	protected:
+		/// Provided for subclasses; send sleep announcements to the sleep_observer_.
+		SleepObserver *sleep_observer_;
+};
+
+#endif /* Sleeper_h */
diff --git a/OSBindings/Mac/Clock Signal.xcodeproj/project.pbxproj b/OSBindings/Mac/Clock Signal.xcodeproj/project.pbxproj
index 106529857..7ed659817 100644
--- a/OSBindings/Mac/Clock Signal.xcodeproj/project.pbxproj	
+++ b/OSBindings/Mac/Clock Signal.xcodeproj/project.pbxproj	
@@ -678,6 +678,7 @@
 		4BAD9B941F43D7E900724854 /* UnformattedTrack.cpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.cpp; path = UnformattedTrack.cpp; sourceTree = "<group>"; };
 		4BAD9B951F43D7E900724854 /* UnformattedTrack.hpp */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.cpp.h; path = UnformattedTrack.hpp; sourceTree = "<group>"; };
 		4BB06B211F316A3F00600C7A /* ForceInline.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = ForceInline.h; sourceTree = "<group>"; };
+		4BB146C61F49D7D700253439 /* Sleeper.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = Sleeper.h; sourceTree = "<group>"; };
 		4BB17D4C1ED7909F00ABD1E1 /* tests.expected.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; name = tests.expected.json; path = FUSE/tests.expected.json; sourceTree = "<group>"; };
 		4BB17D4D1ED7909F00ABD1E1 /* tests.in.json */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text.json; name = tests.in.json; path = FUSE/tests.in.json; sourceTree = "<group>"; };
 		4BB297E51B587D8300A49093 /*  start */ = {isa = PBXFileReference; lastKnownFileType = file; path = " start"; sourceTree = "<group>"; };
@@ -2280,6 +2281,7 @@
 			children = (
 				4BF6606A1F281573002CB053 /* ClockReceiver.hpp */,
 				4BB06B211F316A3F00600C7A /* ForceInline.h */,
+				4BB146C61F49D7D700253439 /* Sleeper.h */,
 			);
 			name = ClockReceiver;
 			path = ../../ClockReceiver;