[macruby-changes] [3614] MacRuby/trunk/lib/dispatch/README.rdoc

[source_changes at macosforge.org]

Revision: 3614
          http://trac.macosforge.org/projects/ruby/changeset/3614
Author:   ernest.prabhakar at gmail.com
Date:     2010-02-24 17:39:09 -0800 (Wed, 24 Feb 2010)
Log Message:
-----------
Document Dispatch::Source.interval

Modified Paths:
--------------
    MacRuby/trunk/lib/dispatch/README.rdoc

Modified: MacRuby/trunk/lib/dispatch/README.rdoc
===================================================================
--- MacRuby/trunk/lib/dispatch/README.rdoc	2010-02-25 01:38:57 UTC (rev 3613)
+++ MacRuby/trunk/lib/dispatch/README.rdoc	2010-02-25 01:39:09 UTC (rev 3614)
@@ -255,27 +255,41 @@
 	
 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.
 
----
-= UNDER CONSTRUCTION = 
-=== Timer Example
+=== Dispatch::Source.interval
 
-For example, this is how you would create a timer that prints out the current time every 30 seconds -- plus 5 microseconds leeway, in case the system wants to align it with other events to minimize power consumption.
+For example, this is how you would create a timer that prints out the current time an +interval+ of 0.5 seconds:
 
+	source = Dispatch::Source.interval(0.5) { |s| puts Time.now }
+	sleep 2
 
-	dispatch_source_t timer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, q_default); //run event handler on the default global queue
-	dispatch_time_t now = dispatch_walltime(DISPATCH_TIME_NOW, 0);
-	dispatch_source_set_timer(timer, now, 30ull*NSEC_PER_SEC, 5000ull);
-	dispatch_source_set_event_handler(timer, ^{
-		printf(“%s\n”, ctime(time(NULL)));
-	});
+=== Dispatch::Source#suspend!
 
-Sources are always created in a suspended state to allow configuration, so when you are all set they must be explicitly resumed to begin processing events. 
+This would rapidly get annoying, so you can +suspend+ the source:
 
-	dispatch_resume(timer);
+	source.suspend!
 
-You can suspend a source or dispatch queue at any time to prevent it from executing new blocks, though this will not affect blocks that are already being processed.
+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!
 
+If you change your mind, you can always +resume+ the source:
+
+	source.resume!
+	sleep 2
+
+If the +Source+ has fired one or more times, it will schedule a block containing the coalesced events. 
+
+=== Dispatch::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.  
+
+---
+= UNDER CONSTRUCTION = 
+
 === Custom Events Example
 
 GCD provides two different types of user events, which differ in how they coalesce the data passed to dispatch_source_merge_data:
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macruby-changes/attachments/20100224/6cf6350b/attachment.html>