[macruby-changes] [3197] MacRuby/trunk/gcd.c

source_changes at macosforge.org source_changes at macosforge.org
Wed Jan 6 15:35:24 PST 2010


Revision: 3197
          http://trac.macosforge.org/projects/ruby/changeset/3197
Author:   ernest.prabhakar at gmail.com
Date:     2010-01-06 15:35:23 -0800 (Wed, 06 Jan 2010)
Log Message:
-----------
Added rdoc for Dispatch Sources and Semaphores

Modified Paths:
--------------
    MacRuby/trunk/gcd.c

Modified: MacRuby/trunk/gcd.c
===================================================================
--- MacRuby/trunk/gcd.c	2010-01-06 21:20:18 UTC (rev 3196)
+++ MacRuby/trunk/gcd.c	2010-01-06 23:35:23 UTC (rev 3197)
@@ -615,7 +615,7 @@
  *  call-seq:
  *    Dispatch::Group.new    =>  Dispatch::Group
  *
- *  Returns a Queue group allowing for for aggregate synchronization.
+ *  Returns a Group allowing for aggregate synchronization.
  *  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’t be made until all 
@@ -701,7 +701,6 @@
     }
 }
 
-
 enum SOURCE_TYPE_ENUM
 {
     SOURCE_TYPE_DATA_ADD,
@@ -767,6 +766,21 @@
 static VALUE rb_source_on_event(VALUE self, SEL sel);
 static void rb_source_event_handler(void* sourceptr);
 
+/* 
+ *  call-seq:
+ *    Dispatch::Source.new(type, handle, mask, queue) =>  Dispatch::Source
+ *
+ *  Returns a Source used to monitor a variety of system objects and events
+ *  including file descriptors, processes, virtual filesystem nodes, signal
+ *  delivery and timers.
+ *  When a state change occurs, the dispatch source will submit its event
+ *  handler block to its target queue.
+ *  
+ *     gcdq = Dispatch::Queue.new('doc')
+ *     src = Dispatch::Source.new(Dispatch::Source::DATA_ADD, 1, 2, gcdq)
+ *
+ */
+
 static VALUE
 rb_source_init(VALUE self, SEL sel,
     VALUE type, VALUE handle, VALUE mask, VALUE queue)
@@ -788,33 +802,6 @@
     return self;
 }
 
-static VALUE
-rb_timer_init(VALUE self, SEL sel, int argc, VALUE* argv)
-{
-    dispatch_time_t start_time;
-    rb_source_t *src = RSource(self);
-    VALUE queue = Qnil, interval = Qnil, delay = Qnil, leeway = Qnil;
-    rb_scan_args(argc, argv, "31", &queue, &delay, &interval, &leeway);
-    Check_Queue(queue);
-    
-    rb_source_init(self, sel, INT2FIX(SOURCE_TYPE_TIMER),
-	    INT2FIX(0), INT2FIX(0), queue);
-
-    if (NIL_P(leeway)) {
-        leeway = INT2FIX(0);
-    }
-    if (NIL_P(delay)) {
-        start_time = DISPATCH_TIME_NOW;
-    }
-    else {
-        start_time = rb_num2timeout(delay);
-    }
-
-    dispatch_source_set_timer(src->source, start_time,
-	    rb_num2nsec(interval), rb_num2nsec(leeway));
-    return self;
-}
-
 static void
 rb_source_event_handler(void* sourceptr)
 {
@@ -876,7 +863,51 @@
 
 }
 
+
+/* 
+ *  call-seq:
+ *    Dispatch::Timer.new(delay, interval, leeway) =>  Dispatch::Timer
+ *
+ *  Returns a Source that will submit the event handler block to
+ *  the target queue after delay, repeated at interval, within leeway, via
+ *  a call to dispatch_source_set_timer(3).
+ *  A best effort attempt is made to submit the event handler block to the
+ *  target queue at the specified time; however, actual invocation may occur at
+ *  a later time even if the leeway is zero.
+ *  
+ *     gcdq = Dispatch::Queue.new('doc')
+ *     timer = Dispatch::Timer.new(Time.now, 5, 0.1)
+ *
+ */
+
 static VALUE
+rb_timer_init(VALUE self, SEL sel, int argc, VALUE* argv)
+{
+    dispatch_time_t start_time;
+    rb_source_t *src = RSource(self);
+    VALUE queue = Qnil, interval = Qnil, delay = Qnil, leeway = Qnil;
+    rb_scan_args(argc, argv, "31", &queue, &delay, &interval, &leeway);
+    Check_Queue(queue);
+    
+    rb_source_init(self, sel, INT2FIX(SOURCE_TYPE_TIMER),
+	    INT2FIX(0), INT2FIX(0), queue);
+
+    if (NIL_P(leeway)) {
+        leeway = INT2FIX(0);
+    }
+    if (NIL_P(delay)) {
+        start_time = DISPATCH_TIME_NOW;
+    }
+    else {
+        start_time = rb_num2timeout(delay);
+    }
+
+    dispatch_source_set_timer(src->source, start_time,
+	    rb_num2nsec(interval), rb_num2nsec(leeway));
+    return self;
+}
+
+static VALUE
 rb_semaphore_alloc(VALUE klass, SEL sel)
 {
     NEWOBJ(s, rb_semaphore_t);
@@ -886,6 +917,29 @@
     return (VALUE)s;
 }
 
+
+/* 
+ *  call-seq:
+ *    Dispatch::Semaphore.new(count) =>  Dispatch::Semaphore
+ *
+ *  Returns a Semaphore used to synchronize threads through a combination of
+ *  waiting and signalling
+ *
+ *  If the count parameter is equal to zero, the semaphore is useful for
+ *  synchronizing completion of work:
+ *
+ *     gcdq = Dispatch::Queue.new('doc')
+ *     sema = Dispatch::Semaphore.new(0)
+ *     gcdq.async { puts "Begin."; sema.signal }
+ *     puts "Waiting..."
+ *     sema.wait
+ *     puts "End!"
+ *
+ *  If the count parameter is greater than zero, then the semaphore is useful
+ *  for managing a finite pool of resources.
+ *
+ */
+
 static VALUE
 rb_semaphore_init(VALUE self, SEL sel, VALUE value)
 {
@@ -899,22 +953,53 @@
     return self;
 }
 
+/* 
+ *  call-seq:
+ *    sema.signal => true or false
+ *
+ *  Signals the semaphore to wake up any waiting threads
+ *
+ *  Returns true if no thread is waiting, false otherwise
+ *
+ *     gcdq = Dispatch::Queue.new('doc')
+ *     sema = Dispatch::Semaphore.new(0)
+ *     gcdq.async { sleep 0.1; sema.signal } #=> false
+ *     sema.wait
+ *
+ */
 static VALUE
-rb_semaphore_wait(VALUE self, SEL sel, int argc, VALUE *argv)
+rb_semaphore_signal(VALUE self, SEL sel)
 {
-    VALUE num;
-    rb_scan_args(argc, argv, "01", &num);
-    return dispatch_semaphore_wait(RSemaphore(self)->sem, rb_num2timeout(num))
+    return dispatch_semaphore_signal(RSemaphore(self)->sem)
      == 0	? Qtrue : Qfalse;
 }
 
+/* 
+ *  call-seq:
+ *    sema.wait(timeout) => true or false
+ *
+ *  Waits (blocks the thread) until a signal arrives or the timeout expires.
+ *  Timeout defaults to DISPATCH_TIME_FOREVER.
+ *
+ *  Returns true if signalled, false if timed out.
+ *
+ *     gcdq = Dispatch::Queue.new('doc')
+ *     sema = Dispatch::Semaphore.new(0)
+ *     gcdq.async { sleep 0.1; sema.signal }
+ *     sema.wait #=> true
+ *
+ */
+
 static VALUE
-rb_semaphore_signal(VALUE self, SEL sel)
+rb_semaphore_wait(VALUE self, SEL sel, int argc, VALUE *argv)
 {
-    return dispatch_semaphore_signal(RSemaphore(self)->sem)
+    VALUE num;
+    rb_scan_args(argc, argv, "01", &num);
+    return dispatch_semaphore_wait(RSemaphore(self)->sem, rb_num2timeout(num))
      == 0	? Qtrue : Qfalse;
 }
 
+
 static IMP rb_semaphore_finalize_super;
 
 static void
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macruby-changes/attachments/20100106/ef713180/attachment.html>


More information about the macruby-changes mailing list