Revision: 3349 http://trac.macosforge.org/projects/ruby/changeset/3349 Author: ernest.prabhakar@gmail.com Date: 2010-01-26 16:14:21 -0800 (Tue, 26 Jan 2010) Log Message: ----------- Minor doc and formatting cleanup Modified Paths: -------------- MacRuby/trunk/gcd.c Modified: MacRuby/trunk/gcd.c =================================================================== --- MacRuby/trunk/gcd.c 2010-01-26 23:25:28 UTC (rev 3348) +++ MacRuby/trunk/gcd.c 2010-01-27 00:14:21 UTC (rev 3349) @@ -21,8 +21,8 @@ #include "id.h" #include "vm.h" #include <libkern/OSAtomic.h> - #include <syslog.h> - #include <stdarg.h> +#include <syslog.h> +#include <stdarg.h> // TODO: These structures need to be wrapped in a Data struct, // otherwise there are crashes when one tries to add an instance @@ -191,14 +191,15 @@ * * The three priority levels are: +:low+, +:default+, * +:high+, corresponding to the DISPATCH_QUEUE_PRIORITY_HIGH, - * DISPATCH_QUEUE_PRIORITY_DEFAULT, and DISPATCH_QUEUE_PRIORITY_LOW (detailed - * in the dispatch_queue_create(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...] man page). The GCD thread dispatcher + * DISPATCH_QUEUE_PRIORITY_DEFAULT, and DISPATCH_QUEUE_PRIORITY_LOW + * (detailed in the dispatch_queue_create(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...] + * 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.async { print 'doc' } } + * 5.times { gcdq.async { print 'foo' } } * gcdq_2 = Dispatch::Queue.concurrent(:low) * gcdq_2.sync { print 'bar' } # will always print 'foofoofoofoofoobar'. * @@ -289,7 +290,7 @@ */ static VALUE -rb_queue_initialize(VALUE self, SEL sel, VALUE name) +rb_queue_init(VALUE self, SEL sel, VALUE name) { StringValue(name); @@ -438,7 +439,8 @@ * call-seq: * gcdq.after(delay) { block } * - * Runs the passed block after the given delay (in seconds). + * Runs the passed block after the given delay (in seconds) using + * dispatch_after(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...], * * gcdq.after(0.5) { puts 'wait is over :)' } * @@ -470,7 +472,8 @@ * call-seq: * gcdq.apply(count) { |index| block } * - * Runs a block count number of times in parallel via dispatch_apply(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...], + * Runs a block count number of times in parallel via + * dispatch_apply(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...], * passing in an index and waiting until all of them are done * * gcdq = Dispatch::Queue.new('doc') @@ -523,8 +526,9 @@ * call-seq: * obj.suspend! * - * Suspends the operation of a dispatch object (queue or source). - * To resume operation, call +resume!+. + * Suspends the operation of a + * dispatch_object(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...] + * (queue or source). To resume operation, call +resume!+. * * gcdq = Dispatch::Queue.new('doc') * gcdq.dispatch { sleep 1 } @@ -549,8 +553,9 @@ * call-seq: * obj.resume! * - * Resumes the operation of a dispatch object (queue or source). - * To suspend operation, call +suspend!+. + * Resumes the operation of a + * dispatch_object(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...] + * (queue or source). To suspend operation, call +suspend!+. * * gcdq = Dispatch::Queue.new('doc') * gcdq.dispatch { sleep 1 } @@ -607,7 +612,9 @@ * call-seq: * Dispatch::Group.new => Dispatch::Group * - * Returns a Group allowing for aggregate synchronization. + * Returns a Group allowing for aggregate synchronization, as defined in: + * dispatch_group_create(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...] + * You can dispatch multiple blocks and track when they all complete, * even though they might run on different queues. * This behavior can be helpful when progress can not be made until all @@ -618,7 +625,7 @@ */ static VALUE -rb_group_initialize(VALUE self, SEL sel) +rb_group_init(VALUE self, SEL sel) { RGroup(self)->group = dispatch_group_create(); assert(RGroup(self)->group != NULL); @@ -674,7 +681,7 @@ VALUE num; rb_scan_args(argc, argv, "01", &num); return dispatch_group_wait(RGroup(self)->group, rb_num2timeout(num)) - == 0 ? Qtrue : Qfalse; + == 0 ? Qtrue : Qfalse; } static IMP rb_group_finalize_super; @@ -855,12 +862,14 @@ * call-seq: * src.handle => Number * - * Returns the underlying handle to the dispatch source (i.e. file descriptor, - * process identifer, etc.). For Ruby, this must be representable as a Number. + * Returns the underlying Ruby handle for the dispatch source (i.e. file, + * file descriptor, process identifer, etc.). * * gcdq = Dispatch::Queue.new('doc') - * src = Dispatch::Source.new(Dispatch::Source::DATA_ADD, 0, 0, gcdq) { } - * puts src.handle #=> 0 + * name = "/var/tmp/gcd_spec_source-#{$$}-#{Time.now}" + * file = File.open(name, "w") + * src = Dispatch::Source.new(Dispatch::Source::WRITE, file, 0, gcdq) { } + * puts src.handle #=> file */ static VALUE @@ -1007,7 +1016,9 @@ * Dispatch::Semaphore.new(count) => Dispatch::Semaphore * * Returns a Semaphore used to synchronize threads through a combination of - * waiting and signalling + * waiting and signalling, as detailed in the + * dispatch_semaphore_create(3)[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPag...] + * man page. * * If the count parameter is equal to zero, the semaphore is useful for * synchronizing completion of work: @@ -1029,8 +1040,8 @@ { dispatch_semaphore_t s = dispatch_semaphore_create(NUM2LONG(value)); if (s == NULL) { - rb_raise(rb_eArgError, "Can't create semaphore based on value `%ld'", - NUM2LONG(value)); + rb_raise(rb_eArgError, "Can't create semaphore based on value `%ld'", + NUM2LONG(value)); } RSemaphore(self)->sem = s; RSemaphore(self)->count = NUM2LONG(value); @@ -1054,8 +1065,8 @@ static VALUE rb_semaphore_signal(VALUE self, SEL sel) { - return dispatch_semaphore_signal(RSemaphore(self)->sem) - == 0 ? Qtrue : Qfalse; + return dispatch_semaphore_signal(RSemaphore(self)->sem) == 0 + ? Qtrue : Qfalse; } /* @@ -1079,7 +1090,7 @@ VALUE num; rb_scan_args(argc, argv, "01", &num); return dispatch_semaphore_wait(RSemaphore(self)->sem, rb_num2timeout(num)) - == 0 ? Qtrue : Qfalse; + == 0 ? Qtrue : Qfalse; } @@ -1117,7 +1128,7 @@ rb_dispatch_begin_thread(void) { if (old_dispatch_begin_thread_4GC != NULL) { - (*old_dispatch_begin_thread_4GC)(); + (*old_dispatch_begin_thread_4GC)(); } rb_vm_register_current_alien_thread(); } @@ -1126,7 +1137,7 @@ rb_dispatch_end_thread(void) { if (old_dispatch_end_thread_4GC != NULL) { - (*old_dispatch_end_thread_4GC)(); + (*old_dispatch_end_thread_4GC)(); } rb_vm_unregister_current_alien_thread(); } @@ -1202,7 +1213,7 @@ rb_queue_get_concurrent, -1); rb_objc_define_method(*(VALUE *)cQueue, "current", rb_queue_get_current, 0); rb_objc_define_method(*(VALUE *)cQueue, "main", rb_queue_get_main, 0); - rb_objc_define_method(cQueue, "initialize", rb_queue_initialize, 1); + rb_objc_define_method(cQueue, "initialize", rb_queue_init, 1); rb_objc_define_method(cQueue, "apply", rb_queue_apply, 1); rb_objc_define_method(cQueue, "async", rb_queue_dispatch_async, -1); rb_objc_define_method(cQueue, "sync", rb_queue_dispatch_sync, 0); @@ -1235,7 +1246,7 @@ */ cGroup = rb_define_class_under(mDispatch, "Group", rb_cObject); rb_objc_define_method(*(VALUE *)cGroup, "alloc", rb_group_alloc, 0); - rb_objc_define_method(cGroup, "initialize", rb_group_initialize, 0); + rb_objc_define_method(cGroup, "initialize", rb_group_init, 0); rb_objc_define_method(cGroup, "notify", rb_group_notify, 1); rb_objc_define_method(cGroup, "on_completion", rb_group_notify, 1); rb_objc_define_method(cGroup, "wait", rb_group_wait, -1); @@ -1312,6 +1323,11 @@ rb_semaphore_finalize_super = rb_objc_install_method2((Class)cSemaphore, "finalize", (IMP)rb_semaphore_finalize); +/* + * Constants for use with + * dispatch_time(3)[http://developer.apple.com/Mac/library/documentation/Darwin/Reference/ManPag...] + */ + rb_define_const(mDispatch, "TIME_NOW", ULL2NUM(DISPATCH_TIME_NOW)); rb_define_const(mDispatch, "TIME_FOREVER", ULL2NUM(DISPATCH_TIME_FOREVER));