Async Programming 101

gistfile1.nim

# async procs compatible the framework have a type like: 
iterator asyncProc: TPromise[TBlob] = 
   yield download(url) # download is a function that returns a promise

# there is a loop that works like this:
coroutine = asyncProc()
...
proc stepCoroutine(coro) =
   var promise = coro()
   promise.onCompleted do:
     if not finished(coro): stepCoroutine(coro)

# the promises are fulfilled(completed) by an async event loop library
http://nikhilm.github.com/uvbook/basics.html
http://www.boost.org/doc/libs/1_52_0/doc/html/boost_asio/overview/core/basics.html
http://libevent.org/
# it possible to implement such library on top of the current async sockets in nimrod,
# but they are based on `select`, which have been largely obsoleted 10 years ago  

# More advanced topic 1)
# it's possible to have code that can be executed in both async and serial way
# to do this we can define download as a template
template download(url) = 
   when AsyncMode: yeild downloadPromise(url)
   else: syncDownload(url)

# then we use a special "async" pragma that transforms a regular proc to async iterator 
# (that is, compiles both copies of the proc by setting AsyncMode in the body)
proc async: TBlob {.async.} =
   download(url)

# This is interesting, but it misses the point of async programming to some extent
# async programming is cool because you can do stuff in parallel:
iterator asyncMultiDownload: TPromise[..] =
   var promise1 = donwloadPromise(url1)
   var promise2 = downloadPromise(url2)
   yield (promise1 & promise2) # this creates a new promise that will be fulfilled when both downloads are complete
                               # (the execution of the async iterator will continue then)
   ...

# other useful references:
http://twistedmatrix.com/trac/wiki/DeferredGenerator

# in C# 5, Promises are called Tasks, which may be a nicer terminology (or AsyncTask)
# also, they use another slightly different await primitive
var contents = await download()

# await could be defined like this in nimrod:
template await(promise): expr =
   let p {.gensym.} = promise
   yield p
   p.value # await returns the async value after the async op completes

http://msdn.microsoft.com/en-us/library/vstudio/hh191443.aspx
   

How to implement a library for Promises?
https://github.com/kriskowal/q/blob/master/design/README.js

Another useful article from the author of the Q library:
http://domenic.me/2012/10/14/youre-missing-the-point-of-promises/