selector example marked up for code-guide, plus improvements to blink and button-blink examples

npryce · npryce · commit c5e21e9d8040 · 2013-06-03T00:51:39.000+02:00
diff --git a/examples/blink b/examples/blink
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+#||
 #|| Blink
 #|| =====
 #||
@@ -65,4 +66,4 @@ with led:
         #|.
 
 #|| The next example, [button-blink](button-blink), shows how to also
-#|| read the state of a GPIO input pin connected to a push-button.
+#|| read the state of a GPIO input pin connected to a push-button.
diff --git a/examples/button-blink b/examples/button-blink
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+#||
 #|| Button Blink
 #|| ============
 #|| 
@@ -37,8 +38,7 @@ with button, led:
 
 #|| However, there's a flaw in this program. If you repeatedly press
 #|| and release the button you can see that the program can take up to
-#|| half a second to react. The program should react to the button
-#|| immediately. To do so it must handle GPIO interrupts in an _event
-#|| loop_. That's what we'll look at in the 
-#|| [selector-button-blink](selector-button-blink) example.
-
+#|| half a second to react. Ideally the program would react to the
+#|| button immediately. To do so it must handle GPIO interrupts in an
+#|| _event loop_, which we'll look at in the [next
+#|| example](selector-button-blink).
diff --git a/examples/selector-button-blink b/examples/selector-button-blink
@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-
+#||
 #|| Event-Driven Input/Output
 #|| ========================= 
 #||
@@ -15,43 +15,94 @@
 #|| driven_: reacting as soon as the signal at the input pin changes
 #|| and using timer events to decide when to blink the LED.
 #|| 
-#|| An event loop is driven by a `Selector` object, which holds a
-#|| number of _event sources_ and waits for an event to occur on one
-#|| of them. An event-driven program creates a Selector, creates
-#|| _event source_ objects that can signal events, adds those event
-#|| sources to the Selector, and repeatedly waits on the Selector for
-#|| events to occur.
+#|| An event-driven program uses a `Selector` object to wait for
+#|| events to occur on a number of _event sources_ -- for example GPIO
+#|| input pins, timers or network connections. The program creates a
+#|| Selector, creates _event source_ objects that can signal events,
+#|| adds the event sources to the Selector, and runs an _event loop_
+#|| in which it waits on the Selector for an events to occur and then
+#|| handles the latest event reported by the Selector.
 #|| 
 #|| As we are converting the button-blink example to be event-driven,
-#|| we have two event sources: the GPIO pin connected to the button
-#|| and a repeating timer that, when started, tells the program when
-#|| to blink the LED.
+#|| we need two event sources: the GPIO pin connected to the button
+#|| and, because we can't put the process to sleep for half a second
+#|| to blink the LED, a repeating timer that tells the program when to
+#|| turn the LED off it is currently on and vice versa.
 
 from quick2wire.gpio import pins, In, Out, Both
 from quick2wire.selector import Selector, Timer
 
+#| [1] We create the selector that will drive our event loop
 selector = Selector()
+#|.
 button = pins.pin(0, direction=In, interrupt=Both)
 led = pins.pin(1, direction=Out)
+
+#| [2] We also create a repeating Timer to trigger the blinking of the
+#| LED.  The _interval_ parameter specifies the time, in seconds,
+#| between Timer events.
 timer = Timer(interval=0.5)
+#|.
 
+#| [3] Like the button and led Pins, the selector and timer consume
+#| operating-system resources, so we add them to the with statement to
+#| ensure that they are closed.
 with selector, button, led, timer:
+#|.
+    #| [4] We have to add the button and timer to the selector before the
+    #| selector will report their events.
     selector.add(button)
     selector.add(timer)
-    
-    print("ready")
+    #|.
     
     while True:
+        #| [5] Now the program's main loop must wait for selector
+        #| events.  When the button or timer signals an event, the
+        #| selector stores a reference to the object that is ready to
+        #| be processed in its _ready_ property and returns from its
+        #| `wait()` method.
         selector.wait()
+        #|.
+        
+        #| [6] If the timer is ready, we invert the value of the
+        #| led pin, so that it blinks on and off.
+        if selector.ready == timer:
+            #| [7] The program must "consume" the latest timer event
+            #| by waiting for it, otherwise the timer will continually
+            #| signal that it is ready, making our program run in a
+            #| busy-loop.
+            timer.wait()
+            #|.
+            
+            led.value = not led.value
+        #|.
         
-        if selector.ready == button:
-            if button.value:
+        #| [8] If the button is ready, the program reads the
+        #| button state. If the value at the GPIO pin is one
+        #| (voltage high), the button has been pressed; if zero
+        #| (voltage low), it has been released.
+        elif selector.ready == button:
+            is_pressed = button.value
+            
+            #| [9] We can use the value read from the button in an if
+            #| statement (in Python, 0 is treated as false and 1 as
+            #| true)
+            if is_pressed:
+            #|.
+                #| [10] If the button has been pressed, the program
+                #| turns on the LED and starts the timer, so that it
+                #| generates the events that makes the program blinks
+                #| the LED on and off.
                 led.value = 1
                 timer.start()
+                #|.
             else:
+                #| [11] If the button has been released, the program
+                #| turns of the LED and stops the timer so that timer
+                #| events won't turn LED on again.
                 led.value = 0
                 timer.stop()
-        
-        elif selector.ready == timer:
-            timer.wait()
-            led.value = not led.value
+                #|.
+        #|.
+#|| When you run this program you will see that it reacts promptly to
+#|| button presses.
