Hi Rich, On Feb 9, 2010, at 4:23 PM, Rich Morin wrote:

Unfortunately, I don't have any specific patterns of my own to offer, as yet. So, I'm hoping that Rich and Ernie might be willing to tell the rest of us about their approaches and rationales.

Interesting. For what it's worth, here's the process I've ended up following for GCD. Note that I didn't really start out with this plan, it largely emerged as I went along http://svn.macosforge.org/repository/ruby/MacRuby/trunk/gcd.c A. Create a thin veneer that "almost" matches the underlying C API - except: 1. Turn data structures into true objects, and their functions into methods 2. Map underlying memory management to Ruby garbage collection 3. Prevent Ruby code from ever creating hard C crashes 4. Take advantage of optional arguments to reduce API "noise" 5. Namespace constants 6. Where possible, combine related methods together to prevent sequencing errors The last is the most controversial. In this particular case, I implemented GCD sources in a way that automatically configures them during "new", which is much simpler but also reduces flexibility. I am fairly (but not 100%) certain that this handles all the common cases, so I believe it an acceptable tradeoff -- but I could be wrong. http://svn.macosforge.org/repository/ruby/MacRuby/trunk/lib/dispatch/ B. Create a high-level convenience API that: 1. Encapsulates common design patterns 2. Hides infrequently used options behind default arguments 3. Provides Ruby idioms and duck-types 4. Allows trivial invocation of the most common cases The jury is still out on whether I've succeeded, but my initial attempts to use the API to implement itself are promising.

I'd also like to hear about other projects (and notions) in this area.

I assume you're familiar with Ruby FFI? Worth asking over there, as presumably they've wrestled with this issue before... Hope this helps, -- Ernie P.

Hi Jordan, On Feb 10, 2010, at 12:30 AM, Jordan K. Hubbard wrote:

P.S. Is it just me, or do other people have a really hard time turning specs into usage-case examples when they read them?

In answer to your plea, I've not only commented up the Dispatch module with examples: http://svn.macosforge.org/repository/ruby/MacRuby/trunk/lib/dispatch/dispatc... I've expanded them into a sample-macruby script: http://svn.macosforge.org/repository/ruby/MacRuby/trunk/sample-macruby/Scrip... (also below) Note that this requires the latest nightly to work, as I redid the semantics of Dispatch.group. Fairly minimal, but something to start with. Does that help? -- Ernie P. #!/usr/local/bin/macruby require 'dispatch' puts "\n Use Dispatch.async to do stuff in the background" Dispatch.async { p "Did this later" } sleep 0.1 puts "\n Use Dispatch.group to track when stuff completes" g = Dispatch.group { p "Do this" } Dispatch.group(g) { p "and that" } g.wait p "Done" puts "\n Use Dispatch.fork to capture return values in a Future" f = Dispatch.fork { 2+2 } p f.value puts " - pass a block to return the value asynchronously" f.value { |v| p "Returns #{v}" } sleep 0.1 puts "\n Use Dispatch.queue_for to create a private serial queue" puts " - synchronizes access to shared data structures" a = Array.new q = Dispatch.queue_for(a) puts " - has a (mostly) unique name:" p q q.async { a << "change me" } puts " - uses sync to block and flush queue" q.sync { p a } puts "\n Use with a group for more complex dependencies, " q.async(g) { a << "more change" } Dispatch.group(g) do tmp = "complex calculation" q.async(g) { a << tmp } end puts " - uses notify to execute block when done" g.notify(q) { p a } q.sync {} puts "\n Use Dispatch.wrap to serialize object using an Actor" b = Dispatch.wrap(Array) b << "safely change me" p b.size # => 1 (synchronous return) b.size {|n| p "Size=#{n}"} # => "Size=1" (asynchronous return)

Hi Jordan, On Feb 12, 2010, at 11:12 AM, Jordan K. Hubbard wrote:

That's definitely a good start, yes, though I must confess to not quite understanding the dispatch.fork example?

All Dispatch.fork does is allow you to access the return value of the block (whenever it is available), either synchronously or asynchronously. In other words, I'm trying to make Futures duck-type to Ruby threads, with allow a return 'value'. I've annotated the file with return values, which may make things a bit clearer.

...

http://svn.macosforge.org/repository/ruby/MacRuby/trunk/sample-macruby/Scrip...

Perhaps part of the problem is that I'm using the same method for return both synchronously (direct) and asynchronously (continuation passing style). It leads to a more concise API, and a fairly powerful pattern once you are used to it, but perhaps that is overly clever. What do you think? I'm also working on a full-fleged article that uses actual, y'know, sentences, which may help once it is done... -- Ernie P.