Revision: 3639 http://trac.macosforge.org/projects/ruby/changeset/3639 Author: ernest.prabhakar@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