This article explains how to use Grand Central Dispatch (GCD) from MacRuby, and is adapted from Introducing Blocks and Grand Central Dispatch at the Apple Developer Connection.

GCD is a revolutionary approach to multicore computing that is woven throughout the fabric of Mac OS X 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.

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.

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 may be helpful if you wish to better understand the underlying semantics.

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 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) 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.

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+ 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. 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)

If you just want to track completion, you can call +join+, 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)” }

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” }

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.

Concurrency would be easy if everything was 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 and mutexes), but these have their own well-known problems (e.g., deadlock, and priority inversion).

Because Ruby traditionally had a global VM lock (or GIL), 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, 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 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).

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”

The Proxy object can be called just as it if were the delegate object:

@hash = :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 = 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}” }

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.

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.

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?!?”

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.

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.

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)”

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)”

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)”

Unlike the others, this method does not have a serial equivalent, but you may recognize it from the world of distributed computing:

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]”

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

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?”

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.

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”)

You can schedule blocks directly on a queue synchronously using sync:

q.sync { puts “queue sync” }

However, it is usually more useful to schedule them asynchronously using async:

q.async { puts “queue async” }

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 provide a powerful mechanism for communicating information across multiple queues. They are another low-level mechanism you can use for synchronizing work.

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.

Next, schedule an asynchronous block that will signal when it is done:

q.async { puts “semaphore signal” semaphore.signal }

Finally, wait for that signal to arrive

puts “semaphore wait” semaphore.wait

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.

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.

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”.

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.

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.

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.

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.

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.

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.

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.

Let’s see how both of use are used for sources which deal with UNIX processes.

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 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).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 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 file.write(char) @next_char += 1 puts “Dispatch::Source.write: #{char}|#{@msg}” 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 and comparing to the relevant RubyDoc.

$ macri Dispatch $ macri Dispatch::Queue $ macri Dispatch::Group $ macri Dispatch::Semaphore However, feel free to file bugs about additional documentation you would like to see.

Development¶ ↑

Gemified by Arthur Gunn. To contribute - please fork, commit, pull request, bonus points for tests. Have a play and report bugs, request features via the issue tracker.