[macruby-changes] [3196] MacRuby/trunk/gcd.c
source_changes at macosforge.org
source_changes at macosforge.org
Wed Jan 6 13:20:19 PST 2010
Revision: 3196
http://trac.macosforge.org/projects/ruby/changeset/3196
Author: ernest.prabhakar at gmail.com
Date: 2010-01-06 13:20:18 -0800 (Wed, 06 Jan 2010)
Log Message:
-----------
Updated GCD documentation to reflect current API
Modified Paths:
--------------
MacRuby/trunk/gcd.c
Modified: MacRuby/trunk/gcd.c
===================================================================
--- MacRuby/trunk/gcd.c 2010-01-06 04:51:57 UTC (rev 3195)
+++ MacRuby/trunk/gcd.c 2010-01-06 21:20:18 UTC (rev 3196)
@@ -28,7 +28,8 @@
/*
*
* Grand Central Dispatch (GCD) is a novel approach to multicore computing
- * that is built into Mac OS X version 10.6 Snow Leopard. In particular, GCD
+ * that is built into Mac OS X version 10.6 Snow Leopard, and available as
+ * open source via the libdispatch project. In particular, GCD
* shifts responsibility for managing threads and their execution from
* applications to the operating system. This allows programmers to easily
* refactor their programs into small chunks of independent work, which GCD
@@ -191,7 +192,7 @@
*
* Returns one of the global concurrent priority queues.
*
- * A dispatch queue is a FIFO queue to which you can submit tasks in the form of a block.
+ * A dispatch queue is a FIFO queue that accepts tasks in the form of a block.
* Blocks submitted to dispatch queues are executed on a pool of threads fully
* managed by the system. Dispatched tasks execute one at a time in FIFO order.
* GCD takes take of using multiple cores effectively and better accommodate
@@ -205,15 +206,15 @@
* The three priority levels are: <code>:low</code>, <code>:default</code>,
* <code>:high</code>, corresponding to the DISPATCH_QUEUE_PRIORITY_HIGH,
* DISPATCH_QUEUE_PRIORITY_DEFAULT, and DISPATCH_QUEUE_PRIORITY_LOW (detailed
- * in the dispatch_queue_create(3) man page). The Grand Central thread dispatcher
+ * in the dispatch_queue_create(3) man page). The GCD thread dispatcher
* will perform actions submitted to the high priority queue before any actions
* submitted to the default or low queues, and will only perform actions on the
* low queues if there are no actions queued on the high or default queues.
*
* gcdq = Dispatch::Queue.concurrent(:high)
- * 5.times { gcdq.dispatch { print 'foo' } }
+ * 5.times { gcdq.async { print 'doc' } }
* gcdq_2 = Dispatch::Queue.concurrent(:low)
- * gcdq.dispatch(:low) { print 'bar' } # will always print 'foofoofoofoofoobar'.
+ * gcdq_2.sync { print 'bar' } # will always print 'foofoofoofoofoobar'.
*
*/
static VALUE
@@ -278,26 +279,26 @@
*
* Returns a new serial dispatch queue.
*
- * A dispatch is a FIFO queue to which you can submit tasks in the form of a block.
+ * A dispatch is a FIFO queue to which you can submit tasks via a block.
* Blocks submitted to dispatch queues are executed on a pool of threads fully
* managed by the system. Dispatched tasks execute one at a time in FIFO order.
- * GCD takes take of using multiple cores effectively and better accommodate
+ * GCD takes take of using multiple cores effectively to better accommodate
* the needs of all running applications, matching them to the
* available system resources in a balanced fashion.
*
- * Use this kind of GCD queue to ensure that tasks execute in a predictable order.
+ * Use serial GCD queues to ensure that tasks execute in a predictable order.
* It’s a good practice to identify a specific purpose for each serial queue,
* such as protecting a resource or synchronizing key processes.
- * Create as many of them as necessary - serial queues are extremely lightweight
+ * Create as many as you need - serial queues are extremely lightweight
* (with a total memory footprint of less than 300 bytes); however, remember to
* use concurrent queues if you need to perform idempotent tasks in parallel.
* Dispatch queues need to be labeled and thereofore you need to pass a name
* to create your queue. By convention, labels are in reverse-DNS style.
*
* gcdq = Dispatch::Queue.new('org.macruby.gcd.example')
- * gcdq.dispatch { p 'foo' }
- * gcdq.dispatch { p 'bar' }
- * gcdq.dispatch(true) {}
+ * gcdq.async { p 'doc' }
+ * gcdq.async { p 'bar' }
+ * gcdq.sync {}
*
*/
@@ -371,24 +372,25 @@
/*
* call-seq:
- * gcdq.dispatch(synchronicity) { i = 42 }
+ * gcdq.async(group=nil) { @i = 42 }
*
- * Yields the passed block synchronously or asynchronously.
- * By default the block is yielded asynchronously:
+ * Yields the passed block asynchronously via dispatch_async(3):
*
* gcdq = Dispatch::Queue.new('doc')
- * i = 42
- * gcdq.dispatch { i = 42 }
- * while i == 0 do; end
- * i #=> 42
+ * @i = 42
+ * gcdq.async { @i = 42 }
+ * while @i == 0 do; end
+ * p @i #=> 42
*
- * If you want to yield the block synchronously pass <code>true</code> as the
- * argument.
+ * If a group is specified, the dispatch will be associated with that group
+ * via dispatch_group_async(3)
*
* gcdq = Dispatch::Queue.new('doc')
- * i = 42
- * gcdq.dispatch(true) { i = 42 }
- * i #=> 42
+ * gcdg = Dispatch::Group.new
+ * @i = 42
+ * gcdq.async(g) { @i = 42 }
+ * g.wait
+ * p @i #=> 42
*
*/
@@ -414,6 +416,20 @@
return Qnil;
}
+/*
+ * call-seq:
+ * gcdq.sync { @i = 42 }
+ *
+ * Yields the passed block synchronously via dispatch_sync(3):
+ *
+ * gcdq = Dispatch::Queue.new('doc')
+ * @i = 42
+ * gcdq.sync { @i = 42 }
+ * p @i #=> 42
+ *
+ */
+
+
static VALUE
rb_queue_dispatch_sync(VALUE self, SEL sel)
{
@@ -450,14 +466,15 @@
/*
* call-seq:
- * gcdq.apply(amount_size) { block }
+ * gcdq.apply(count) { |index| block }
*
- * Runs a block and yields it as many times as asked
+ * Runs a block count number of times in parallel via dispatch_apply(3),
+ * passing in an index and waiting until all of them are done
*
- * gcdq = Dispatch::Queue.new('foo')
- * i = 0
- * gcdq.apply(10) { i += 1 }
- * i #=> 10
+ * gcdq = Dispatch::Queue.new('doc')
+ * @result = []
+ * gcdq.apply(5) {|i| @result[i] = i*i }
+ * p @result #=> [0, 1, 4, 9, 16, 25]
*
*/
@@ -491,7 +508,7 @@
* call-seq:
* gcdq.label -> str
*
- * Returns the label of the dispatch queue.
+ * Returns the label of the dispatch queue (aliased to 'to_s')
*
* gcdq = Dispatch::Queue.new('doc')
* gcdq.label #=> 'doc'
@@ -513,37 +530,39 @@
return Qnil; // never reached
}
+
/*
* call-seq:
- * obj.resume!
+ * obj.suspend!
*
- * Resumes a suspended dispatch object (group, source or queue).
+ * Suspends the operation of a dispatch object (queue or source).
+ * To resume operation, call <code>resume!</code>.
*
- * obj.suspend!
- * obj.suspended? #=> true
- * obj.resume!
+ * gcdq = Dispatch::Queue.new('doc')
+ * gcdq.dispatch { sleep 1 }
+ * gcdq.suspend!
+ * gcdq.suspended? #=> true
+ * gcdq.resume!
*
*/
static VALUE
-rb_dispatch_resume(VALUE self, SEL sel)
+rb_dispatch_suspend(VALUE self, SEL sel)
{
rb_dispatch_obj_t *dobj = RDispatch(self);
- if (dobj->suspension_count > 0) {
- dobj->suspension_count--;
- dispatch_resume(dobj->obj);
- }
+ dobj->suspension_count++;
+ dispatch_suspend(dobj->obj);
return Qnil;
}
/*
* call-seq:
- * obj.suspend!
+ * obj.resume!
*
- * Suspends the operation of a dispatch object (group, source or queue).
- * To resume operation, call <code>resume!</code>.
+ * Resumes the operation of a dispatch object (queue or source).
+ * To suspend operation, call <code>suspend!</code>.
*
- * gcdq = Dispatch::Queue.new('foo')
+ * gcdq = Dispatch::Queue.new('doc')
* gcdq.dispatch { sleep 1 }
* gcdq.suspend!
* gcdq.suspended? #=> true
@@ -552,11 +571,13 @@
*/
static VALUE
-rb_dispatch_suspend(VALUE self, SEL sel)
+rb_dispatch_resume(VALUE self, SEL sel)
{
rb_dispatch_obj_t *dobj = RDispatch(self);
- dobj->suspension_count++;
- dispatch_suspend(dobj->obj);
+ if (dobj->suspension_count > 0) {
+ dobj->suspension_count--;
+ dispatch_resume(dobj->obj);
+ }
return Qnil;
}
@@ -566,6 +587,8 @@
*
* Returns <code>true</code> if <i>obj</i> is suspended.
*
+ * gcdq = Dispatch::Queue.new('doc')
+ * gcdq.dispatch { sleep 1 }
* gcdq.suspend!
* gcdq.suspended? #=> true
* gcdq.resume!
@@ -597,7 +620,6 @@
* even though they might run on different queues.
* This behavior can be helpful when progress can’t be made until all
* of the specified tasks are complete.
- *
*
* gcdg = Dispatch::Group.new
*
@@ -614,16 +636,15 @@
/*
* call-seq:
- * gcdg.notify { block }
+ * grp.notify { block }
*
- * Schedules a block to be called when a group of previously submitted dispatches
- * have completed.
+ * Asynchronously schedules a block to be called when the previously
+ * submitted dispatches for that group have completed.
*
- *
- * gcdg = Dispatch::Group.new
- * gcdg.notify { print 'bar' }
- * gcdg.dispatch(Dispatch::Queue.concurrent) { print 'foo' }
- * # prints 'foobar'
+ * gcdq = Dispatch::Queue.new('doc')
+ * grp = Dispatch::Group.new
+ * gcdq.async(grp) { print 'doc' }
+ * grp.notify { print 'bar' } #=> foobar
*/
static VALUE
@@ -651,11 +672,12 @@
* If the supplied timeout is nil, the function will wait indefinitely until
* the specified group becomes empty, always returning true.
*
- * q = Dispatch::Queue.new('org.macruby.documentation')
+ * gcdq = Dispatch::Queue.new('doc')
* grp = Dispatch::Group.new
- * grp.dispatch(q) { sleep 4 }
- * grp.wait(5) # true
+ * gcdq.async(grp) { sleep 4 }
+ * grp.wait(5) #=> true
*/
+
static VALUE
rb_group_wait(VALUE self, SEL sel, int argc, VALUE *argv)
{
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macruby-changes/attachments/20100106/48eab17a/attachment-0001.html>
More information about the macruby-changes
mailing list