[macruby-changes] [3639] MacRuby/trunk

[source_changes at macosforge.org]

Revision: 3639
          http://trac.macosforge.org/projects/ruby/changeset/3639
Author:   ernest.prabhakar at gmail.com
Date:     2010-02-26 17:17:02 -0800 (Fri, 26 Feb 2010)
Log Message:
-----------
Rename Dispatch::Source.interval to periodic

Modified Paths:
--------------
    MacRuby/trunk/lib/dispatch/README.rdoc
    MacRuby/trunk/lib/dispatch/source.rb
    MacRuby/trunk/spec/macruby/library/dispatch/source_spec.rb

Modified: MacRuby/trunk/lib/dispatch/README.rdoc
===================================================================
--- MacRuby/trunk/lib/dispatch/README.rdoc	2010-02-27 00:52:41 UTC (rev 3638)
+++ MacRuby/trunk/lib/dispatch/README.rdoc	2010-02-27 01:17:02 UTC (rev 3639)
@@ -18,9 +18,9 @@
 
 Dispatch::Group:: Allows applications to track the progress of blocks submitted to queues and take action when the blocks complete.
 
-Dispatch::Source:: Monitors and coalesces low-level system events so that they can be responded to asynchronously via simple event handlers.
+Source:: Monitors and coalesces low-level system events so that they can be responded to asynchronously via simple event handlers.
 
-Dispatch::Semaphore:: Synchronizes threads via a combination of waiting and signalling.
+Semaphore:: Synchronizes threads via a combination of waiting and signalling.
 
 In addition, MacRuby 0.6 provides additional, higher-level abstractions and convenience APIs such as +Job+ and +Proxy+ via the "dispatch" library (i.e., +require 'dispatch'+).
 
@@ -242,9 +242,9 @@
 
 	(0..4).p_findall(3) { |i| i.odd?} # => 3
 
-== Dispatch::Sources: Asynchronous Events
+== Sources: Asynchronous Events
 
-In addition to scheduling blocks directly, GCD makes it easy to run a block in response to various system events via a Dispatch::Source, which supports:
+In addition to scheduling blocks directly, GCD makes it easy to run a block in response to various system events via a Source, which supports:
 
 * Timers
 * Signals
@@ -255,22 +255,26 @@
 	
 When the source “fires,” GCD will schedule the handler on the specific queue if it is not currently running, or -- more importantly -- coalesce pending events if it is. This provides excellent responsiveness without the expense of either polling or binding a thread to the event source.  Plus, since the handler is never run more than once at a time, the block doesn’t even need to be reentrant -- and thus you don't need to +synchronize+ any variables that are only used there.
 
-=== Dispatch::Source.interval
+=== Source.periodic
 
-For example, this is how you would create a timer that prints out the current time an +interval+ of 0.5 seconds:
+For example, this creates a +periodic+ timer that runs every 1.2 seconds and prints out the number of pending events:
 
-	source = Dispatch::Source.interval(0.5) { |s| puts Time.now }
-	sleep 2
+	source = Source.periodic(1.2) { |src| puts src.data }
+	sleep 3 # => 1 1
 
-=== Dispatch::Source#suspend!
+=== Source#data
 
-This would rapidly get annoying, so you can +suspend+ the source:
+As you can see above, the +handler+ block gets called with the source itself as a parameter.  
 
+=== Source#suspend!
+
+This would rapidly get annoying; to pause, just +suspend!+ the source:
+
 	source.suspend!
 
 You can suspend a source at any time to prevent it from executing new blocks, though this will not affect a block that is already being processed.
 
-=== Dispatch::Source#resume!
+=== Source#resume!
 
 If you change your mind, you can always +resume+ the source:
 
@@ -279,13 +283,13 @@
 
 If the +Source+ has fired one or more times, it will schedule a block containing the coalesced events. 
 
-=== Dispatch::Source#cancel!
+=== Source#cancel!
 
 Finally,  you can stop the source entirely by calling +cancel!+:
 
 	source.cancel!
 
-This is particularly important to do in MacRuby's implementation of GCD, since there is no other way to get rid of a source.  
+This is particularly important to do in MacRuby's implementation of GCD, since (due to garbage collection) there is no other way to get rid of a source.  
 
 ---
 = UNDER CONSTRUCTION = 

Modified: MacRuby/trunk/lib/dispatch/source.rb
===================================================================
--- MacRuby/trunk/lib/dispatch/source.rb	2010-02-27 00:52:41 UTC (rev 3638)
+++ MacRuby/trunk/lib/dispatch/source.rb	2010-02-27 01:17:02 UTC (rev 3639)
@@ -76,7 +76,7 @@
         Dispatch::Source.new(Dispatch::Source::VNODE, file, mask, queue, &block)
       end
 
-      def interval(seconds, queue = Dispatch::Queue.concurrent, &block)
+      def periodic(seconds, queue = Dispatch::Queue.concurrent, &block)
         Dispatch::Source.timer(0, seconds, 0, queue, &block)
       end
     end

Modified: MacRuby/trunk/spec/macruby/library/dispatch/source_spec.rb
===================================================================
--- MacRuby/trunk/spec/macruby/library/dispatch/source_spec.rb	2010-02-27 00:52:41 UTC (rev 3638)
+++ MacRuby/trunk/spec/macruby/library/dispatch/source_spec.rb	2010-02-27 01:17:02 UTC (rev 3639)
@@ -131,13 +131,13 @@
       end          
     end
 
-    describe "interval" do
+    describe "periodic" do
       it "fires with data on how often the timer has fired" do
         @count = -1
         repeats = 2
-        @interval = 0.02
-        @src = Dispatch::Source.interval(@interval, @q) {|s| @count += s.data}
-        sleep repeats*@interval
+        @periodic = 0.02
+        @src = Dispatch::Source.periodic(@periodic, @q) {|s| @count += s.data}
+        sleep repeats*@periodic
         @q.sync { }
         @count.should == repeats
       end
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macruby-changes/attachments/20100226/fffe0578/attachment-0001.html>