dispatch 0.0.1pre

data/.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in dispatch.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,14 @@
+PATH
+  remote: .
+  specs:
+    dispatch (0.0.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  dispatch!

data/README.rdoc

@@ -0,0 +1,670 @@
+= Grand Central Dispatch for MacRuby
+
+== Introduction
+
+This article explains how to use Grand Central Dispatch (*GCD*) from MacRuby, and is adapted from {Introducing Blocks and Grand Central Dispatch}[http://developer.apple.com/mac/articles/cocoa/introblocksgcd.html] at the {Apple Developer Connection}[http://developer.apple.com/].
+
+=== About GCD
+	
+GCD is a revolutionary approach to multicore computing that is woven throughout the fabric of {Mac OS X}[http://www.apple.com/macosx/] version 10.6 Snow Leopard. GCD combines an easy-to-use programming model with highly-efficient system services to radically simplify the code needed to make best use of multiple processors. The technologies in GCD improve the performance, efficiency, and responsiveness of Snow Leopard out of the box, and will deliver even greater benefits as more developers adopt them.
+
+The central insight of GCD is shifting the responsibility for managing threads and their execution from applications to the operating system. As a result, programmers can write less code to deal with concurrent operations in their applications, and the system can perform more efficiently on single-processor machines, large multiprocessor servers, and everything in between. Without a pervasive approach such as GCD, even the best-written application cannot deliver optimal performance, because it doesn't have full insight into everything else happening in the system.
+
+=== The MacRuby Dispatch module
+
+GCD is natively implemented as a C API and runtime engine.  MacRuby 0.5 introduces a new "Dispatch" module, which provides a Ruby wrapper around that API. This allows Ruby blocks to be scheduled on queues for asynchronous and concurrent execution either explicitly or in response to various kinds of events, with GCD automatically mapping queues to threads as needed.  The Dispatch module provides four primary abstractions that mirror the C API:
+
+Dispatch::Queue:: The basic unit for organizing blocks. Several queues are created by default, and applications may create additional queues for their own use.
+
+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.
+
+Dispatch::Semaphore:: Synchronizes threads via a combination of waiting and signalling.
+
+
+=== What You Need
+
+The examples all assume you run the latest macirb and require the +dispatch+ library:
+
+	$ macirb
+	require 'dispatch'	
+
+We also assume that you are already familiar with Ruby, though not necessarily MacRuby. No prior knowledge of C or GCD is assumed or required, but the {dispatch(3) man page}[http://developer.apple.com/mac/library/DOCUMENTATION/Darwin/Reference/ManPages/man3/dispatch.3.html] may be helpful if you wish to better understand the underlying semantics.
+
+== Dispatch::Job: Easy Concurrency
+
+The easiest way to perform concurrent work is via a +Job+ object. Say you have a complex, long-running calculation you want to happen in the background. Create a job by passing Dispatch::Job's initializer the block you want to execute:
+
+	job = Dispatch::Job.new { Math.sqrt(10**100) }
+
+This atomically[http://en.wikipedia.org/wiki/Atomic_operation] adds the block to GCD's default concurrent queue, then returns immediately so you don't stall the main thread.
+
+Concurrent queues schedule as many simultaneous blocks as they can on a first-in/first-out (FIFO[http://en.wikipedia.org/wiki/FIFO]) basis, as long as there are threads available.  If there are spare CPUs, the system will automatically create more threads -- and reclaim them when idle -- allowing GCD to dynamically scale the number of threads based on the overall system load.  Thus (unlike with threads, which choke when you create too many) you can generally create as many jobs as you want, and GCD will do the right thing.
+
+=== Job#value: Asynchronous Return Values
+
+The downside of asynchrony is that you don't know exactly when your job will execute.  Fortunately, +Dispatch::Job+ attempts to duck-type +Thread[http://ruby-doc.org/core/classes/Thread.html]+, so you can call +value[http://ruby-doc.org/core/classes/Thread.html#M000460]+ to obtain the result of executing that block:
+
+	@result = job.value
+	puts "value (sync): #{@result} => 1.0e+50"
+	
+This will wait until the value has been calculated, allowing it to be used as an {explicit Future}[http://en.wikipedia.org/wiki/Futures_and_promises]. However, this may stall the main thread indefinitely, which reduces the benefits of concurrency.
+
+Wherever possible, you should instead attempt to figure out exactly _when_  and _why_ you need to know the result of asynchronous work. Then, call +value+ with a block to also perform _that_ work asynchronously once the value has been calculated -- all without blocking the main thread:
+
+	job.value {|v| puts "value (async): #{v} => 1.0e+50" } # (eventually)
+
+=== Job#join: Job Completion
+
+If you just want to track completion, you can call +join[http://ruby-doc.org/core/classes/Thread.html#M000462]+, which waits without returning the result:
+
+	job.join
+	puts "join done (sync)"
+	
+Similarly, call +join+ with a block to run asynchronously once the work has been completed
+
+	job.join { puts "join done (async)" }
+
+=== Job#add: Coordinating Work
+
+More commonly, you will have multiple units of work you'd like to perform in parallel.  You can add blocks to an existing job using +add:
+
+	job.add { Math.sqrt(2**64) }
+
+If there are multiple blocks in a job, +value+ will wait until they all finish then return the last value received:
+
+	job.value {|b| puts "value (async): #{b} => 4294967296.0" }
+
+=== Job#values: Returning All Values
+
+Note that values may be received out of order, since they may take differing amounts of time to complete. If you need to force a particular ordering, create a new +Job+ or call +join+ before submitting the block.
+
+Additionally, you can call +values+ to obtain all the values:
+
+	@values = job.values
+	puts "values: #{@values.inspect} => [1.0E50]"
+	job.join
+	puts "values: #{@values.inspect} => [1.0E50, 4294967296.0]"
+
+Note that unlike +value+ this will not by itself first +join+ the job, and thus does not have an asynchronous equivalent.
+
+== Dispatch::Proxy: Protecting Shared Data
+
+Concurrency would be easy if everything was {embarrassingly parallel}[http://en.wikipedia.org/wiki/Embarrassingly_parallel], but it becomes tricky when we need to share data between threads. If two threads try to modify the same object at the same time, it could lead to inconsistent (read: _corrupt_) data.  There are well-known techniques for preventing this sort of data corruption (e.g. locks[http://en.wikipedia.org/wiki/Lock_(computer_science)] and mutexes[http://en.wikipedia.org/wiki/Mutual%20eclusion]), but these have their own well-known problems (e.g., deadlock[http://en.wikipedia.org/wiki/Deadlock], and {priority inversion}[http://en.wikipedia.org/wiki/Priority_inversion]).
+
+Because Ruby traditionally had a global VM lock (or GIL[http://en.wikipedia.org/wiki/Global_Interpreter_Lock]), only one thread could modify data at a time, so developers never had to worry about these issues; then again, this also meant they didn't get much benefit from additional threads.
+
+In MacRuby, every thread has its own Virtual Machine, which means all of them can access Ruby objects at the same time -- great for concurrency, not so great for data integrity. Fortunately, GCD provides _serial queues_ for {lock-free synchronization}[http://en.wikipedia.org/wiki/Non-blocking_synchronization], by ensuring that only one thread a time accesses a particular object -- without the complexity and inefficiency of locking. Here we will focus on +Dispatch::Proxy+, a high-level construct that implements the {Actor model}[http://en.wikipedia.org/wiki/Actor_model] by wrapping any arbitrary Ruby object with a +SimpleDelegate+ that only allows execution of one method at a time (i.e., serializes data access on to a private queue).
+
+=== Job#synchronize: Creating Proxies
+
+The easiest way to create a Proxy is to first create an empty Job:
+
+	job = Dispatch::Job.new {}
+
+then ask it to wrap the object you want to modify from multiple threads:
+
+	@hash = job.synchronize Hash.new
+	puts "synchronize: #{@hash.class} => Dispatch::Proxy"
+	
+This is actually the same type of object used to manage the list of +values+:
+
+	puts "values: #{job.values.class} => Dispatch::Proxy"
+	
+=== Proxy#method_missing: Using Proxies
+
+The Proxy object can be called just as it if were the delegate object:
+
+	@hash[:foo] = :bar
+	puts "proxy: #{@hash} => {:foo=>:bar}"
+	@hash.delete :foo
+	
+Except that you can use it safely inside Dispatch blocks from multiple threads:
+	
+	[64, 100].each do |n|
+		job.add { @hash[n] = Math.sqrt(10**n) }
+	end
+	job.join
+	puts "proxy: #{@hash} => {64 => 1.0E32, 100 => 1.0E50}"
+
+In this case, each block will perform the +sqrt+ asynchronously on the concurrent queue, potentially on multiple threads
+	
+As with Dispatch::Job, you can make any invocation asynchronous by passing a block:
+
+	@hash.inspect { |s| puts "inspect: #{s} => {64 => 1.0E32, 100 => 1.0E50}" }
+
+=== Proxy#\_\_value\_\_: Returning Delegate
+
+If for any reason you need to retrieve the original (unproxied) object, simply call +__value__+:
+
+	delegate = @hash.__value__
+	puts "\n__value__: #{delegate.class} => Hash"
+	
+This differs from +SimpleDelegate#__getobj__+ (which Dispatch::Proxy inherits) in that it will first wait until any pending asynchronous blocks have executed.
+
+As elsewhere in Ruby, the "__" namespace implies "internal" methods, in this case meaning they are called directly on the proxy rather than passed to the delegate.
+
+====  Caveat: Local Variables
+
+Because Dispatch blocks may execute after the local context has gone away, you should always store Proxy objects in a non-local variable: instance, class, or global -- anything with a sigil[http://en.wikipedia.org/wiki/Sigil_(computer_programming)].
+
+Note that we can as usual _access_ local variables from inside the block; GCD automatically copies them, which is why this works as expected:
+
+	n = 42
+	job = Dispatch::Job.new { puts "n (during): #{n} => 42" }
+	job.join
+	
+but this doesn't:
+
+	n = 0
+	job = Dispatch::Job.new { n = 21 }
+	job.join
+	puts "n (after): #{n} => 0?!?"
+
+The general rule is "do *not* assign to external variables inside a Dispatch block."  Assigning local variables will have no effect (outside that block), and assigning other variables may replace your Proxy object with a non-Proxy version.  Remember also that Ruby treats the accumulation operations ("+=", "||=", etc.) as syntactic sugar over assignment, and thus those operations only affect the copy of the variable:
+
+	n = 0
+	job = Dispatch::Job.new { n += 84 }
+	job.join
+	puts "n (+=): #{n} => 0?!?"
+
+== Dispatch Enumerable: Parallel Iterations
+
+Jobs are useful when you want to run a single item in the background or to run many different operations at once. But if you want to run the _same_ operation multiple times, you can take advantage of specialized GCD iterators.  The Dispatch module defines "p_" variants of common Ruby iterators, making it trivial to parallelize existing operations.
+
+In addition, for simplicity they all are _synchronous_, meaning they won't return until all the work has completed.
+
+=== Integer#p_times
+
+The simplest iteration is defined on the +Integer+ class, and passes the index that many +times+:
+
+	5.times { |i| print "#{10**i}\t" }
+	puts "times"
+	
+becomes
+
+	5.p_times { |i| print "#{10**i}\t" }
+	puts "p_times"
+	
+Note that even though the iterator as a whole is synchronous, and blocks are scheduled in the order received, each block runs independently and therefore may complete out of order.
+
+This does add some overhead compared to the non-parallel version, so if you have a large number of relatively cheap iterations you can batch them together by specifying a +stride+:
+
+	5.p_times(3) { |i| print "#{10**i}\t" }
+	puts "p_times(3)"
+
+It doesn't change the result, but schedules fewer blocks thus amortizing the overhead over more work. Note that items _within_ a stride are executed completely in the original order, but no order is guaranteed _between_ strides.
+
+The +p_times+ method is used to implement several convenience methods on +Enumerable+, which are therefore available from any class which mixes that in (e.g, +Array+, +Hash+, etc.). These also can take an optional stride.
+
+=== Enumerable#p_each
+
+Passes each object, like +each+:
+	DAYS=%w(Mon Tue Wed Thu Fri)
+
+	DAYS.each { |day| print "#{day}\t"}
+	puts "each"
+
+	DAYS.p_each { |day| print "#{day}\t"}
+	puts "p_each"
+
+	DAYS.p_each(3) { |day| print "#{day}\t"}
+	puts "p_each(3)"
+
+=== Enumerable#p_each_with_index
+
+Passes each object and its index, like +each_with_index+:
+
+	DAYS.each_with_index { |day, i | print "#{i}:#{day}\t"}
+	puts "each_with_index"
+
+	DAYS.p_each_with_index { |day, i | print "#{i}:#{day}\t"}
+	puts "p_each_with_index"
+
+	DAYS.p_each_with_index(3) { |day, i | print "#{i}:#{day}\t"}
+	puts "p_each_with_index(3)"
+
+=== Enumerable#p_map
+
+Passes each object and collects the transformed values, like +map+:
+
+	print (0..4).map { |i| "#{10**i}\t" }.join
+	puts "map"
+	
+	print (0..4).p_map { |i| "#{10**i}\t" }.join
+	puts "p_map"
+
+	print (0..4).p_map(3) { |i| "#{10**i}\t" }.join
+	puts "p_map(3)"
+
+=== Enumerable#p_mapreduce
+
+Unlike the others, this method does not have a serial equivalent, but you may recognize it from the world of {distributed computing}[http://en.wikipedia.org/wiki/MapReduce]:
+
+	mr = (0..4).p_mapreduce(0) { |i| 10**i }
+	puts "p_mapreduce: #{mr} => 11111"
+
+This uses a parallel +inject+ (formerly known as +reduce+) to return a single value by combining the result of +map+. Unlike +inject+, you must specify an explicit initial value as the first parameter. The default accumulator is ":+", but you can specify a different symbol to +send+:
+
+	mr = (0..4).p_mapreduce([], :concat) { |i| [10**i] }
+	puts "p_mapreduce(:concat): #{mr} => [1, 1000, 10, 100, 10000]"
+	
+Because of those parameters, the optional +stride+ is now the third:
+
+	mr = (0..4).p_mapreduce([], :concat, 3) { |i| [10**i] }
+	puts "p_mapreduce(3): #{mr} => [1000, 10000, 1, 10, 100]"
+
+=== Enumerable#p_find_all
+
+Passes each object and collects those for which the block is true, like +find_all+:
+
+	puts "find_all | p_find_all | p_find_all(3)"
+	puts (0..4).find_all { |i| i.odd? }.inspect
+	puts (0..4).p_find_all { |i| i.odd? }.inspect
+	puts (0..4).p_find_all(3) { |i| i.odd? }.inspect
+	
+=== Enumerable#p_find
+
+Passes each object and returns nil if none match. Similar to +find+, it returns the first object it _finds_ for which the block is true, but unlike +find+ that may not be the _actual_ first object since blocks -- say it with me -- "may complete out of order":
+
+	puts "find | p_find | p_find(3)"
+
+	puts (0..4).find { |i| i == 5 }.nil? # => nil
+	puts (0..4).p_find { |i| i == 5 }.nil? # => nil
+	puts (0..4).p_find(3) { |i| i == 5 }.nil? # => nil
+
+	puts "#{(0..4).find { |i| i.odd? }} => 1"
+	puts "#{(0..4).p_find { |i| i.odd? }} => 1?"
+	puts "#{(0..4).p_find(3) { |i| i.odd? }} => 3?"
+
+== Queues: Serialization
+
+Most of the time, you can simply use GCD's default concurrent queues or the built-in queues associated with synchronized objects.  However, if you want more precise control you can create and use your own queues.
+
+=== Queue::new
+
+The simplest way to create a +new+ queue is by passing it a meaningful name, typically using reverse-DNS naming:
+
+	puts
+	puts q = Dispatch::Queue.new("org.macruby.queue.example")
+
+=== Queue#sync
+
+You can schedule blocks directly on a queue synchronously using +sync+:
+
+	q.sync { puts "queue sync" }
+	
+=== Queue#async
+
+However, it is usually more useful to schedule them asynchronously using +async+:
+
+	q.async { puts "queue async" }
+		
+=== Queue#join
+
+A key advantage of scheduling blocks on your own private queue is that you can ensure that all pending blocks have been executed, via a +join+:
+
+	puts "queue join"
+	q.join
+
+== Semaphores: Synchronization
+
+Semaphores provide a powerful mechanism for communicating information across multiple queues. They are another low-level mechanism you can use for synchronizing work.
+
+=== Semaphore::new
+
+First, create a semaphore using +new+:
+
+	puts
+	puts semaphore = Dispatch::Semaphore.new(0)
+
+Semaphores can be used to manage complex interactions, but here will simply  use to them signal completion of a single task by passing a +count+ of zero.
+
+=== Semaphore#signal
+
+Next, schedule an asynchronous block that will +signal+ when it is done:
+
+	q.async {
+		puts "semaphore signal"
+		semaphore.signal
+	}
+	
+=== Semaphore#wait
+
+Finally, +wait+ for that signal to arrive
+
+	puts "semaphore wait"
+	semaphore.wait
+
+	
+== 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 can be a:
+
+* Timer
+* Custom event
+* Signal
+* File descriptor (file or socket)
+* Process state change
+	
+When the source "fires", GCD will schedule the _handler_ block 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.
+
+=== Source.periodic
+
+We'll start with a simple example: a +periodic+ timer that runs every 0.4 seconds and prints out the number of pending events:
+
+	puts
+	timer = Dispatch::Source.periodic(0.4) do |src|
+	 	puts "Dispatch::Source.periodic: #{src.data}"
+	end
+	sleep 1 # => 1 1 ...
+	
+If you're familiar with the C API for GCD, be aware that a +Dispatch::Source+ is fully configured at the time of instantiation, and does not need to be +resume+d. Also, times are in seconds, not nanoseconds.
+
+=== Source#data
+
+As you can see above, the handle gets called with the source itself as a parameter, which allows you query it for the source's +data+. The meaning of the data varies with the type of +Source+, though it is always an integer. Most commonly -- as in this case -- it is a count of the number of events being processed, and thus "1".
+
+=== Source#suspend!
+
+This monotony rapidly gets annoying; to pause, just +suspend!+ the source:
+
+	timer.suspend!
+	puts "suspend!"
+	sleep 1
+
+You can suspend a source at any time to prevent it from running another block, though this will not affect a block that is already being processed.
+
+=== Source#resume!
+
+If you change your mind, you can always +resume!+ the source:
+
+	timer.resume!
+	puts "resume!"
+	sleep 1 # => 1 2 1 ...
+
+If the +Source+ has fired one or more times, it will schedule a block containing the coalesced events. In this case, we were suspended for over 2 intervals, so the next block will fire with +data+ being at least 2.
+
+=== Source#cancel!
+
+Finally, you can stop the source entirely by calling +cancel!+:
+
+	timer.cancel!
+	puts "cancel!"
+	puts
+
+Cancellation is particularly significant in MacRuby's implementation of GCD, since (due to the reliance on garbage collection) there is no other way to explicitly stop using a source.
+
+=== Custom Sources
+
+Next up are _custom_ or _application-specific_ sources, which are fired explicitly by the developer instead of in response to an external event.  These simple behaviors are the primitives upon which other sources are built.
+
+==== Source.add
+
+The +add+ source accumulates the sum of the event data (e.g., for a counter) in a thread-safe manner:
+
+	@sum = 0
+	adder = Dispatch::Source.add do |s|
+	 	puts "Dispatch::Source.add: #{s.data} (#{@sum += s.data})"
+		semaphore.signal
+	end
+
+Note that we use an instance variable (since it is re-assigned), but we don't have to +synchronize+ it -- and can safely re-assign it -- since the event handler does not need to be reentrant.
+
+==== Source#<<
+
+To fire a custom source, we invoke what GCD calls a _merge_ using the shovel operator ('+<<+'):
+
+	adder << 1
+	semaphore.wait
+	puts "sum: #{@sum} => 1"
+
+Note the use of +Semaphore#wait+ to ensure the asynchronously-scheduled event handler has been run.
+
+The name "merge" makes more sense when you see it coalesce multiple firings into a single handler:
+
+	adder.suspend!
+	adder << 3
+	adder << 5
+	puts "sum: #{@sum} => 1"
+	adder.resume!
+	semaphore.wait
+	puts "sum: #{@sum} => 9"
+	adder.cancel!
+
+Since the source is suspended -- mimicking what would happen if your event handler was busy at the time -- GCD automatically _merges_ the results together using addition.  This is useful for tracking cumulative results across multiple threads, e.g. for a progress meter.  Notice this is the event coalescing behavior used by +periodic+.
+
+==== Source.or
+
+Similarly, the +or+ source combines events using a logical OR (e.g, for booleans or bitmasks):
+
+	@mask = 0
+	masker = Dispatch::Source.or do |s|
+		@mask |= s.data
+		puts "Dispatch::Source.or: #{s.data.to_s(2)} (#{@mask.to_s(2)})"
+		semaphore.signal
+	end
+	masker << 0b0001
+	semaphore.wait
+	puts "mask: #{@mask.to_s(2)} => 1"
+	masker.suspend!
+	masker << 0b0011
+	masker << 0b1010
+	puts "mask: #{@mask.to_s(2)} => 1"
+	masker.resume!
+	semaphore.wait
+	puts "mask: #{@mask.to_s(2)} => 1011"
+	masker.cancel!
+	puts
+	
+This is primarily useful for flagging what _kinds_ of events have taken place since the last time the handler fired.
+
+=== Process Sources
+
+Let's see how both of use are used for sources which deal with UNIX processes.
+
+==== Source.process
+
+This +or+-style source takes and returns a mask of different events affecting the specified +process+:
+
+exec:: Dispatch::Source.PROC_EXEC
+exit:: Dispatch::Source.PROC_EXIT
+fork:: Dispatch::Source.PROC_FORK
+signal:: Dispatch::Source.PROC_SIGNAL
+
+[*NOTE*: +Thread#fork+ is not supported by MacRuby]
+
+The underlying API expects and returns integers, e.g.:
+
+	@event = 0
+	mask = Dispatch::Source::PROC_EXIT | Dispatch::Source::PROC_SIGNAL
+	proc_src = Dispatch::Source.process($$, mask) do |s|
+		@event |= s.data
+		puts "Dispatch::Source.process: #{s.data.to_s(2)} (#{@event.to_s(2)})"
+		semaphore.signal
+	end
+	
+In this case, we are watching the current process ('$$') for +:signal+ and (less usefully :-) +:exit+ events .
+
+==== Source#data2events
+	
+Alternatively, you can pass in array of names (symbols or strings) for the mask, and optionally use +data2events+ to convert the returned data into an array of symbols
+
+	semaphore2 = Dispatch::Semaphore.new(0)
+	@events = []
+	mask2 = [:exit, :fork, :exec, :signal]
+	proc_src2 = Dispatch::Source.process($$, mask2) do |s|
+		these = Dispatch::Source.data2events(s.data)
+		@events += these
+		puts "Dispatch::Source.process: #{these} (#{@events})"
+		semaphore2.signal
+	end
+
+==== Source.process Example
+
+To fire the event, we can, e.g., send a un-trapped signal :
+
+	sig_usr1 = Signal.list["USR1"]
+	Signal.trap(sig_usr1, "IGNORE")
+	Process.kill(sig_usr1, $$)
+	Signal.trap(sig_usr1, "DEFAULT")
+
+You can check which flags were set by _and_ing against the bitmask:
+
+	semaphore.wait
+	result = @event & mask
+	print "@event: #{result.to_s(2)} =>"
+	puts  " #{Dispatch::Source::PROC_SIGNAL.to_s(2)} (Dispatch::Source::PROC_SIGNAL)"
+	proc_src.cancel!
+
+Or equivalently, intersecting the array:
+
+	semaphore2.wait
+	puts "@events: #{(result2 = @events & mask2)} => [:signal]"
+	proc_src2.cancel!
+
+==== Source#event2num
+
+You can convert from symbol to int via +event2num+:
+
+	puts "event2num: #{Dispatch::Source.event2num(result2[0]).to_s(2)} => #{result.to_s(2)}"
+
+==== Source#data2events
+
+Similarly, use +data2events+ to turn an int into a symbol:
+
+	puts "data2events: #{Dispatch::Source.data2events(result)} => #{result2}"
+
+==== Source.signal
+
+This +Source+ overlaps slightly with the previous one, but uses +add+ to track the number of times that a specific +signal+ was fired against the *current* process:
+
+	@signals = 0
+	sig_usr2 = Signal.list["USR2"]
+	signal = Dispatch::Source.signal(sig_usr2) do |s|
+		puts "Dispatch::Source.signal: #{s.data} (#{@signals += s.data})"
+		semaphore.signal
+	end
+
+	puts "signals: #{@signals} => 0"
+	signal.suspend!
+	Signal.trap(sig_usr2, "IGNORE")
+	3.times { Process.kill(sig_usr2, $$) }
+	Signal.trap(sig_usr2, "DEFAULT")
+	signal.resume!
+	semaphore.wait
+	puts "signals: #{@signals} => 3"
+	signal.cancel!
+	puts
+
+=== File Sources
+
+Next up are sources which deal with file operations -- actually, anything that modifies a vnode, including sockets and pipes.
+
+==== Source.file
+
+This +or+-style source takes and returns a mask of different events affecting the specified +file+:
+
+delete:: Dispatch::Source.VNODE_DELETE
+write:: Dispatch::Source.VNODE_WRITE
+extend:: Dispatch::Source.VNODE_EXTEND
+attrib:: Dispatch::Source.VNODE_ATTRIB
+link:: Dispatch::Source.VNODE_LINK
+rename:: Dispatch::Source.VNODE_RENAME
+revoke:: Dispatch::Source.VNODE_REVOKE
+
+As before, the underlying API expects and returns integers, e.g.:
+
+	@fevent = 0
+	@msg = "#{$$}-#{Time.now.to_s.gsub(' ','_')}"
+	puts "msg: #{@msg}"
+	filename = "/tmp/dispatch-#{@msg}"
+	puts "filename: #{filename}"
+	file = File.open(filename, "w")
+	fmask = Dispatch::Source::VNODE_DELETE | Dispatch::Source::VNODE_WRITE
+	file_src = Dispatch::Source.file(file.fileno, fmask, q) do |s|
+		@fevent |= s.data
+		puts "Dispatch::Source.file: #{s.data.to_s(2)} (#{@fevent.to_s(2)})"
+		semaphore.signal
+	end
+	file.print @msg
+	file.flush
+	file.close
+	semaphore.wait(0.1)
+	print "fevent: #{(@fevent & fmask).to_s(2)} =>"
+	puts " #{Dispatch::Source::VNODE_WRITE.to_s(2)} (Dispatch::Source::VNODE_WRITE)"
+	File.delete(filename)
+	semaphore.wait(0.1)
+	print "fevent: #{@fevent.to_s(2)} => #{fmask.to_s(2)}"
+	puts " (Dispatch::Source::VNODE_DELETE | Dispatch::Source::VNODE_WRITE)"
+	file_src.cancel!
+	q.join
+	
+And of course can also use symbols:
+
+	@fevent2 = []
+	file = File.open(filename, "w")
+	fmask2 = %w(delete write)
+	file_src2 = Dispatch::Source.file(file, fmask2) do |s|
+		@fevent2 += Dispatch::Source.data2events(s.data)
+		puts "Dispatch::Source.file: #{Dispatch::Source.data2events(s.data)} (#{@fevent2})"
+		semaphore2.signal
+	end
+	file.print @msg
+	file.flush
+	semaphore2.wait(0.1)
+	puts "fevent2: #{@fevent2} => [:write]"
+	file_src2.cancel!
+	
+As a bonus, if you pass in an actual IO object (not just a file descriptor) the Dispatch library will automatically create a handler that closes the file for you when cancelled!
+
+==== Source.read
+
+In contrast to the previous sources, these next two refer to internal state rather than external events. Specifically, this +add+-style source avoids blocking on a +read+ by only calling the handler when it estimates there are +s.data+ unread bytes available in the buffer:
+
+	file = File.open(filename, "r")
+	@input = ""
+	reader = Dispatch::Source.read(file) do |s|
+		@input << file.read(s.data)
+		puts "Dispatch::Source.read: #{s.data}: #{@input}"
+	end
+	while (@input.size < @msg.size) do; end
+	puts "input: #{@input} => #{@msg}" # => e.g., 74323-2010-07-07_15:23:10_-0700
+	reader.cancel!
+
+Strictly speaking, the count returned by +s.data+ is only an estimate. It would be safer to instead call +@file.read(1)+ each time to avoid any risk of blocking -- but that would lead to many more block invocations, which might not be a net win.
+
+Note that since the block handler may be called many times, we can't wait on a semaphore, but instead test on the shared variable. In a real implementation you should detect end of file instead.
+
+==== Source.write
+
+This +add+-style event is similar to the above, but waits until a +write+ buffer is available:
+
+	file = File.open(filename, "w")
+	@next_char = 0
+	writer = Dispatch::Source.write(file) do |s|
+		if @next_char < @msg.size then
+			char = @msg[@next_char]
+			file.write(char)
+			@next_char += 1	
+			puts "Dispatch::Source.write: #{char}|#{@msg[@next_char..-1]}"
+		end
+	end
+	while (@next_char < @msg.size) do; end
+	puts "output: #{File.read(filename)} => #{@msg}" # e.g., 74323-2010-07-07_15:23:10_-0700
+	File.delete(filename)
+
+In this case we play it safe by only writing out a single character each time we are called, to avoid risk of blocking (and simplify our algorithm).
+
+= What's Next?
+
+This concludes our introduction to the high-level wrappers available when using +require 'dispatch'+.  These allow you to easily write concurrent, asynchronous code using simple Ruby idioms. For additional performance and fine-grained control, you may want to dive down into directly using Queues, Groups, and Semaphores. 
+At the moment, this is best done by reading the {existing C documentation for GCD}[http://developer.apple.com/mac/articles/cocoa/introblocksgcd.html] and comparing to the relevant RubyDoc.
+
+	$ macri Dispatch
+	$ macri Dispatch::Queue
+	$ macri Dispatch::Group
+	$ macri Dispatch::Semaphore
+		
+However, feel free to {file bugs}[https://www.macruby.org/auth/login/?next=/trac/newticket] about additional documentation you would like to see.