The first problem is a few of the methods of an “awaiter” (what in C++ we’d call the awaiter concept) have been renamed, and there’s now a property called IsCompleted, and that’s fine and dandy.

But when I tried exercising the code I hit a more thorny problem, which is that my test program would terminate somewhat randomly when an exception was rethrown from a background thread. For a program that I thought was single threaded, that’s pretty bad!

I don’t have my install of the original CTP, so I’m not sure about this, but I think a fairly major change was made since then: there’s now a difference between an async method that returns void and an async method that returns Task (as opposed to Task<T>).

Contrary to what might be assumed, the relationship between Task and Task<T> is not the same as that between IEnumerable and IEnumerable<T>. That is, Task is not some old pre-generics version of the same idea. Instead, it was specially created to represent a task that doesn’t return any value at all; that is, something like void, but asynchronous.

I believe (though I’m not certain) that in the original CTP, a void async method would actually return a Task, so as to ensure that its lifetime could be managed externally even though it wouldn’t produce a value. But in the latest version that is not the case: the Task associated with an void async method is just not available, and the compiler generated version of the method really does return void. Which means in turn that you can’t use await on such methods.

You can still explicitly declare your async method to return Task, so nothing has been lost. And this certainly makes everything more clear and consistent to callers: methods really do return what they are declared to return, as usual. But it also changes the behaviour of exceptions.

In all case, if an exception tries to escape out of your async method, there is a catch-all handler in the compiler-generated state machine which will catch it, so it can be rethrown in an appropriate context. But the choice of context depends totally on whether the method returns void or Task. The policy is determined by AsyncVoidMethodBuilder or AsyncTaskMethodBuilder respectively. With the help of Resharper, we can see that the latter gives the caught exception to the Task, via task.TrySetException. So then the decision to rethrow (or not) is entirely up to whoever has a hold of the Task. They can check the Exception property whenever.

But in the void case, it’s totally different. The Task never gets passed the exception. What would be the point? We can’t get at the Task. The exception is unobservable; to avoid that loss of information, an arrangement is made to rethrow the exception at the next available opportunity, by creating a delegate that will rethrow it and then posting that delegate to the “context”.

The “context” is a somewhat vague concept; the architecture uses three different representations, depending on the scenario. But in the case of a simple console-based test program, the exception-rethrowing delegate is simply passed to the thread pool, and so it brings down the whole process at a random time (though reasonably soon). In a GUI program the exception would be thrown on the main GUI thread. You can supply your own context by setting a per-thread instance of SynchronizationContext, in which you can override the Post method. It doesn’t let you get at the exception, but it does give you a delegate that, if you executed it, would throw the exception, which you can then catch!

The upshot? An exception that leaves an async void is definitely a sign of a bug somewhere. Although of course this does not automatically mean you should add your own catch-all! Sometimes crashing the process is the least-worst option. There is no single correct way to deal with bugs – it’s a question of economics and so is not an exact science.

So in short, async void is a niche thing. In most situations you almost certainly want async Task with no type argument. And my example of implementing the equivalent of yield return definitely needs updating.

Firstly I stash the Task in a field. Second, after executing the continuation I check the Task.Exception property to see if anything bad happened that needs rethrowing:

if (_task.Exception != null)
{
    // Unpeel the AggregateException wrapping
    Exception inner = _task.Exception;
    while (inner is AggregateException)
        inner = inner.InnerException;

    throw inner;
}

Aside from that it works much the same way as before, though I’ve added a lot of comments and organised it a little differently to hopefully make the behaviour clearer. I’ve also had to add an implementation of the new awaiter property:

public bool IsCompleted
{
    get { return false; }
}

Well, that was easy. Returning true would be a very bad idea in this example, as we can discover with more Resharper digging. The compiler-generated state machine examines that property, and if it is true then it doesn’t bother to yield control back to the thread. So we don’t get the interleaved execution behaviour that we’re relying on.

Here’s the whole thing:

public delegate Task IteratorMethod(YieldEnumerator e);

public class YieldEnumerator : IEnumerator
{
    // Will be executed to get the next value
    private Action _continuation;

    // Will become the value of Current
    private TItem _nextValue;
    private bool _hasNextValue;

    // To be thrown inside the async method, as if by the await keyword
    private Exception _exception;

    // The task associated with our running async method
    private Task _task;

    public YieldEnumerator(IteratorMethod iteratorMethod)
    {
        _task = iteratorMethod(this);
    }

    private void Execute()
    {
        // If we already have a buffered value that hasn't been
        // retrieved, we shouldn't do anything yet. If we don't
        // and there's no continuation to run, we've finished.
        // And if _task is null, we've been disposed.
        if (_hasNextValue || _continuation == null || _task == null)
            return;

        // Be ultra-careful not to run same _continuation twice
        var t = _continuation;
        _continuation = null;
        t(); // may or may not have stored a new _continuation

        // And may also have hit a snag!
        if (_task.Exception != null)
        {
            // Unpeel the AggregateException wrapping
            Exception inner = _task.Exception;
            while (inner is AggregateException)
                inner = inner.InnerException;

            throw inner;
        }
    }

    public YieldEnumerator GetAwaiter()
    {
        return this;
    }

    // Performance optimisation added since original CTP. If we
    // returned true, the compiler-generated code would bypass the
    // OnCompleted/GetResult dance altogether, and the flow of the
    // async method would never be interrupted in the way that we
    // require.
    public bool IsCompleted
    {
        get { return false; }
    }

    // Was called BeginAwait in the original CTP
    public void OnCompleted(Action continuation)
    {
        Debug.Assert(_continuation == null);
        _continuation = continuation;
    }

    // Was called EndAwait
    public void GetResult()
    {
        // This is called by compiler-generated code caused by the
        // await keyword, so it's a chance to throw an exception to
        // be caught by the code in the async method
        if (_exception != null)
        {
            var t = _exception;
            _exception = null;
            throw t;
        }
    }

    // Our equivalent of yield return
    public YieldEnumerator YieldReturn(TItem value)
    {
        if (_hasNextValue)
        {
            // Shouldn't happen because MoveNext ought to have
            // been called and we should be inside the async
            // code at this point
            throw new InvalidOperationException();
        }

        _nextValue = value;
        _hasNextValue = true;
        return this;
    }

    public TItem Current { get; private set; }

    object System.Collections.IEnumerator.Current
    {
        get { return Current; }
    }

    public bool MoveNext()
    {
        Execute();

        if (_hasNextValue)
        {
            Current = _nextValue;
            _hasNextValue = false;
            return true;
        }

        return false;
    }

    private sealed class AbandonEnumeratorException : Exception {}

    public void Dispose()
    {
        // If async method is not yet complete, throw an exception
        // inside it to make it grind to a halt
        if (_continuation != null)
        {
            _exception = new AbandonEnumeratorException();
            try { Execute(); } catch (AbandonEnumeratorException) { }
        }

        _task.Dispose();
        _task = null;
    }

    public void Reset()
    {
        throw new NotImplementedException("Reset");
    }
}

// The usual obvious IEnumerable to go with our IEnumerator
public class YieldEnumerable : IEnumerable
{
    private readonly IteratorMethod _iteratorMethod;

    public YieldEnumerable(IteratorMethod iteratorMethod)
    {
        _iteratorMethod = iteratorMethod;
    }

    public IEnumerator GetEnumerator()
    {
        return new YieldEnumerator(_iteratorMethod);
    }

    System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator()
    {
        return GetEnumerator();
    }
}

class Program
{
    public static async Task MyIteratorMethod1(YieldEnumerator e)
    {
        Console.WriteLine("A");
        await e.YieldReturn(1);
        Console.WriteLine("B");
        await e.YieldReturn(2);
        Console.WriteLine("C");
        await e.YieldReturn(3);
        Console.WriteLine("D");
    }

    public static async Task MyIteratorMethod2(YieldEnumerator e)
    {
        try
        {
            Console.WriteLine("A");
            await e.YieldReturn(1);
            Console.WriteLine("B");
            await e.YieldReturn(2);
            Console.WriteLine("C");
            await e.YieldReturn(3);
            Console.WriteLine("D");
        }
        finally
        {
            Console.WriteLine("Running finally");
        }
    }

    public static async Task MyIteratorMethodInfinite(YieldEnumerator e)
    {
        for (var n = 0; ; n++)
            await e.YieldReturn(n);
    }

    public static async Task MyIteratorBroken1(YieldEnumerator e)
    {
        // always happens, but compiler doesn't know that
        if (DateTime.Now.Year < 10000)
            throw new IOException("Bad");

        await e.YieldReturn(1);
    }

    public static async Task MyIteratorBroken2(YieldEnumerator e)
    {
        await e.YieldReturn(1);

        if (DateTime.Now.Year < 10000)
            throw new IOException("Bad");
    }

    public static async Task MyIteratorBroken3(YieldEnumerator e)
    {
        await e.YieldReturn(1);

        if (DateTime.Now.Year < 10000)
            throw new IOException("Bad");

        await e.YieldReturn(2);
    }

    static void Main(string[] args)
    {
        foreach (var i in new YieldEnumerable(MyIteratorMethod1))
            Console.WriteLine("Yielded: " + i);

        foreach (var i in new YieldEnumerable(MyIteratorMethod2))
        {
            Console.WriteLine("Yielded: " + i);
            break; // finally should still run
        }

        foreach (var i in new YieldEnumerable(MyIteratorMethodInfinite))
        {
            if (i % 1000000 == 0) // every million times...
                Console.WriteLine("Yielded: " + i);

            if (i > 10000000)
                break;
        }

        try
        {
            foreach (var i in new YieldEnumerable(MyIteratorBroken1))
                Console.WriteLine("Yielded: " + i);
        }
        catch (IOException)
        {
            Console.WriteLine("Caught expected exception");
        }

        try
        {
            foreach (var i in new YieldEnumerable(MyIteratorBroken2))
                Console.WriteLine("Yielded: " + i);
        }
        catch (IOException)
        {
            Console.WriteLine("Caught expected exception");
        }

        try
        {
            foreach (var i in new YieldEnumerable(MyIteratorBroken3))
                Console.WriteLine("Yielded: " + i);
        }
        catch (IOException)
        {
            Console.WriteLine("Caught expected exception");
        }
    }
}

Of course it’s only worth doing this if the dictionary lookup is faster than simply re-executing the function itself, and if the same small set of arguments are highly likely to be passed repeatedly. Yawn!!

In a non-pure language like JavaScript many (most?) functions are not pure: they examine information from other sources besides their parameters. However, they often have contexts within which they are “pure enough”. e.g. the information the user can see on the screen is, naively speaking, a projection of the information stored in the database, but if that were really true then when the database changes, the screen would immediately change as well. But it doesn’t; instead it usually remains stale until the user presses Refresh. This corresponds to “emptying the cache”.

In a complex app, there may be several separate components that project the same information in different ways. If they all go back to the external source for that information, and it is changing in real time, you could end up with an inconsistent picture on the screen. This might even cause instability, if one component tries to talk to another and they assume they’ll both have identical snapshots of the external information.

So memoization actually has a purpose in JavaScript: it can simulate a “freeze frame” of your dependencies on external data. But we need to provide the ability to delete things from the cache at the time of our choosing, “unfreezing” the frame so we can take a new snapshot.

Another complicating factor in JavaScript is asynchrony. JavaScript programmers just have to get used to doing the following transformation into “continuation-passing style” by hand; starting with:

var add = function(a1, a2) {
  return a1 + a2;
};

We switch to:

var add = function(a1, a2, done) {
  done(a1 + a2);
};

So the caller of add can no longer say:

var sum = add(2, 2);
alert('The answer is ' + sum);

And must instead say:

add(2, 2, function(sum) {
  alert('The answer is ' + sum);
});

This allows the implementation of add to utilise other functions that need to be passed a continuation in the same manner. Yo!!

So, let’s memoize. To simplify matters we’ll start by assuming we’ll be dealing with functions that take no parameters (or always take exactly the same parameters, it’s the same thing). It means we can replace the map with a single variable. We’re displaying “prices” (whatever the hell they are) to the user, so if synchronous was a realistic option we’d start with:

var getPrices = function() { 
    /// Talk to server to get prices, p, somehow.
    return p; 
};

Sadly we have to be asynchronous, but it’s no biggie:

var getPrices = function(done) {
    /// Talk to server to get prices, p, somehow.
    done(p); 
};

Seems like memoizing something that will be easy!

var makeCache = function(getter) {

  var value = null, ready = false;

  return {

    reset: function() {
      value = null;
      ready = false;
    },

    get: function(done) {
      if (ready) {
        done(value);
      } else {
        getter(function(got) {
          value = got;
          ready = true;
          done(value);
        });
      }
    }
  };

};

You’d use it to “wrap” the getPrices function like this:

var pricesCache = makeCache(getPrices);

pricesCache.get(function(prices) {
  // we've got the prices!  
});

And when you want to reset the cache, just say:

pricesCache.reset();

But actually there’s a bug here: do you know what it is? Give yourself a playful slap on the thigh if you got it.

What if there’s more than one call to pricesCache.get before the first one comes back with the data? We only set the ready flag when we’ve got the answer, which might take a second. In the meantime, various parts of the UI might be grabbing the prices to make their own updates. Each such call will launch a separate (unnecessary) call to the backend. What’s worse is that the prices may actually change during this mess, and so the callers will end up with inconsistent price information, just like I was a-bellyachin’ about up yonder.

First reaction: oh, oh, I know, it’s a state machine! We thought there were two states, as indicated by the boolean ready flag. But actually there’s three:

1. No value.
2. Okay, I’m, getting the value, sheesh.
3. Got the value.

But hold on to your hose, little fireman. Think this one through for a second. It’s pretty clear that when the first caller tries to get, we need to transition to the middle state and make our call to the real getter function. And when the prices come back to us, we transition to the final state and call the callback function. But what about when a second caller tries to get and we’re already in the middle state? That’s the whole reason for doing this, to be able to handle that differently. Where do we put their callback function?

So, yes, it is a state machine, but not a three-state one. We need to keep a list of callback functions, so that when the prices come back, we can loop through those callback functions and give every single gosh darn one of them a calling they ain’t gonna forgit:

var makeCache = function(getter) {

  var value, ready, waiting = [];

  return {

    reset: function() {
      value = null;
      ready = false;
      waiting = [];
    },

    get: function(done) {
      if (ready) {
        done(value);
      } else {
        waiting.push(done);

        if (waiting.length === 1) {
          getter(function(got) {

            value = got;
            ready = true;

            waiting.forEach(function(w) { w(value); });
            waiting = null;
          });
        }
      }
    }
  };

};

Notice how I use waiting.forEach to loop through the callbacks. By definition here I’m calling some code that I don’t have control of. It might call back into pricesCache.get. That may seem intrinsically problematic, because it sounds like it could keep happening forever and cause a stack overflow. But it might be perfectly valid: there could be some separate code making the second call to get the prices, which supplies a different callback. Anyway, is it a problem for my cache implementation? No, because any calls to pricesCache.get during my callback loop will find that ready is already set, and so will not affect the waiting array. And even if pricesCache.reset were called, that would cause a fresh array to be created and stored in waiting.

And finally, nice piece of trivia for ya: even if there was some way for waiting to grow while we are still looping through it, according to the specification of Array.forEach the new item(s) won’t be included in the iteration.

Whenever I’m asked if this would make sense as a real library, I’ve replied that in the real world it would make much more sense to build on the stuff in Boost, especially the range library.

And guess what? At that very moment someone was already working on it (only with a far more elegant, extensible interface), and the following month a set of extensions to range were put up for review, and were accepted… then a long time passed (they’re very careful) until summer of 2010, when finally the new features were released in Boost 1.43.

I only discovered this just now. People still seem to be finding that old blog post, so it only seems proper to get up-to-date. My first stab looked like this:

#include <boost/range/algorithm/for_each.hpp>
#include <boost/range/adaptor/filtered.hpp>
#include <boost/range/adaptor/transformed.hpp>

#include <boost/lexical_cast.hpp>

#include <vector>
#include <iostream>
#include <string>

int main()
{
	using namespace boost::adaptors;

	std::vector<int> numbers;
	numbers.push_back(0);
	numbers.push_back(-1);
	numbers.push_back(4);
	numbers.push_back(-3);
	numbers.push_back(5);
	numbers.push_back(8);
	numbers.push_back(-2);
	
	auto quoted_positives = numbers 
		| filtered([] (int n) { return n >= 0; })
		| transformed([] (int x) { 
                    return "\"" + boost::lexical_cast<std::string>(x) + "\""; 
                  });

	boost::for_each(quoted_positives, [] (std::string n) { 
            std::cout << n << std::endl; 
        });
	return 0;
}

As you can see, the key is the use of operator| to make a piping syntax, so that we can naturally read from left to right (you may have seen the same approach used in F#). So I start with a vector of plain integers called numbers, I then pipe that through the filtered adaptor so as to get just the positives (corresponding to Where in Linq), and finally through the transformed adaptor to turn each positive into a quoted string (corresponding to map in most functional frameworks and to Select in Linq).

Except… it doesn’t work.

The problem is that boost is not yet entirely C++11 lambda-friendly. It’s unfortunate that the boost documentation (and other online information) is peppered with the word lambda signifying something else, so I may just be missing something. But the gist of the problem appears to be that transformed wants a functor with a member type called result_type. So you are supposed to write something like this:

struct quote
{
    typedef std::string result_type;

    std::string operator()(int x) const 
    {
        return "\"" + boost::lexical_cast<std::string>(x) + "\""; 
    }
};

C++11 lambdas don’t have that result_type inside them, so they don’t directly fit. It goes without saying that we don’t like this, because the whole point of lambdas is to avoid writing a separate class somewhere else.

It is surely possible to extend boost’s function_traits so that they can reflect on lambdas. In the past they have not been written to work on general functors because a functor can have multiple overloads of operator(), so you are required to manually pick one of those members before you ask questions. But this position is no longer sensible (if indeed it ever was). The majority of functors will now be lambdas, with a single overload of operator(), and it is (as we can see from this example) perfectly reasonable to want to know the return type of that single overload. A lambda is an alternative to a plain function, and whatever is useful for a function will be useful for a lambda.

But in the meantime, it is interesting to see how many hoops we have to jump through to make the above sample code work as expected.

If you read my last update on this sordid subject you’ll know that I don’t want to have to state the type of something that can be inferred, so I’m not going to be satisfied by a wrapper template that just adds a manually specified result_type member to my lambda. Ugh! It must be inferred automatically.

Fortunately this is just a matter of using a few simple steps in metaprogramming. Firstly, a template designed to match a member function:

template <class T>
struct mem_fun_traits { };

Of course in this general form it will match anything. But we’ll only bother to specialise it for one case: a pointer to a const member function that accepts one argument:

template <class R, class C, class A>
struct mem_fun_traits<R (C::*)(A) const> 
{
    typedef R result_type;
    typedef A argument_type;
};

So if you pass mem_fun_traits the type of a pointer to the operator() within a lambda, you know what it accepts and returns. But how do you get that type argument? With decltype that’s easy-peasy:

template<typename T>
struct functor_member {
    typedef decltype(&T::operator()) type;
};

Armed with these tools, we can write a traits class for our simple one-argument, single-overload functors (and hence, by an extraordinary coincidence, also for C++11 lambdas):

template <class F>
struct functor_traits
{
    typedef typename functor_member<F>::type member_t;
    typedef mem_fun_traits<member_t> traits;

    typedef typename traits::result_type result_type;
    typedef typename traits::argument_type argument_type;
};

This is the thing that should be integrated into boost’s function_traits, to make lambdas work as true replacements for functions. I’m sure someone’s working on it.

In the event that this doesn’t happen, we can shoehorn it together anyway by making a function template that adds type metadata to any single-argument functor:

template <class F>
class functor_with_traits_t
{
    F f;

public:
    functor_with_traits_t(F f_) : f(f_) {}

    typedef typename functor_traits<F>::result_type result_type;
    typedef typename functor_traits<F>::argument_type argument_type;

    result_type operator()(argument_type a) const { return f(a); }
};

template <class F>
inline functor_with_traits_t<F> functor_with_traits(F f) { return functor_with_traits_t<F>(f); }

So if you have a plain old lambda like this:

auto l = [] (int x) { 
    return "\"" + boost::lexical_cast<std::string>(x) + "\""; 
};

You can “fix” it to have type metadata like so:

auto l2 = functor_with_traits(l);

This makes it compatible with boost’s transformed! Although manually putting in that wrapper each time is pretty tedious. We can work around that by defining our own adapter (let’s call it selected in slavish imitation of Linq) that just plugs together functor_with_traits and transformed. Sounds simple, though as always the difficulty is in figuring out the types:

template <class F>
inline um... selected(F f)
{
    return boost::adaptors::transformed(functor_with_traits(f)); 
}

The um... is “whatever type we’re returning”. Wouldn’t it be nice if we could put auto there? Well, we almost can: decltype to the rescue as usual:

decltype(
    boost::adaptors::transformed(
        functor_with_traits(make_ref<F>())
    )
)

That is: give me the type that would be returned if I called transformed, passing it the result of a call to functor_with_traits, passing it an F. Of course we can’t assume that F can be default constructed, hence the use of that funny make_ref function that always comes in handy with decltype.

So our completed adaptor is:

template <class F>
decltype(
    boost::adaptors::transformed(
        functor_with_traits(make_ref<F>())
    )
)
selected(F f)
{
    return boost::adaptors::transformed(functor_with_traits(f)); 
}

We can use selected in place of transformed and everything is hunky dory. Full example:

#include <boost/range/algorithm/for_each.hpp>
#include <boost/range/adaptor/filtered.hpp>
#include <boost/range/adaptor/transformed.hpp>

#include <boost/lexical_cast.hpp>

#include <vector>
#include <iostream>
#include <string>

template <class T>
T *make_ptr() { return (T *)0; }

template <class T>
const T &make_ref() { return *(make_ptr<T>()); }

template <class T>
struct mem_fun_traits { };

template <class R, class C, class A>
struct mem_fun_traits<R (C::*)(A) const> 
{
  typedef R result_type;
  typedef A argument_type;
};

template<typename T>
struct functor_member {
    typedef decltype(&T::operator()) type;
};

template <class F>
struct functor_traits
{
	typedef typename functor_member<F>::type member_t;
	typedef mem_fun_traits<member_t> traits;

	typedef typename traits::result_type result_type;
	typedef typename traits::argument_type argument_type;
};

template <class F>
class functor_with_traits_t
{
	F f;

public:
	functor_with_traits_t(F f_) : f(f_) {}

	typedef typename functor_traits<F>::result_type result_type;
	typedef typename functor_traits<F>::argument_type argument_type;

	result_type operator()(argument_type a) const { return f(a); }
};

template <class F>
functor_with_traits_t<F> functor_with_traits(F f) { return functor_with_traits_t<F>(f); }

template <class F>
decltype(boost::adaptors::transformed(functor_with_traits(make_ref<F>()))) selected(F f)
{
	return boost::adaptors::transformed(functor_with_traits(f)); 
}

int main()
{
	using namespace boost::adaptors;

	std::vector<int> numbers;
	numbers.push_back(0);
	numbers.push_back(-1);
	numbers.push_back(4);
	numbers.push_back(-3);
	numbers.push_back(5);
	numbers.push_back(8);
	numbers.push_back(-2);
	
	auto quoted_positives = numbers 
		| filtered([] (int n) { return n >= 0; })
		| selected([] (int x) { 
                    return "\"" + 
                      boost::lexical_cast<std::string>(x) +
                      "\"";
                  });

	boost::for_each(quoted_positives, [] (std::string n) {
            std::cout << n << std::endl; 
        });
	return 0;
}

(Tested on MSVC++ 16.00.40219.01 and GNU G++ 4.5.3.)

There would be a directory representing your whole project. (Everything else we discuss will be under that directory, so I’ll use full relative paths from now on.)

It would have a subdirectory containing some general-purpose makefiles that take care of all the messy work, which you usually never need to look at. Let’s call that subdirectory morkfiles, because mork sounds like make, only it’s funnier, and so is a good name for our fantasy makefile framework.

And there would be one actual makefile under the top level directory, acting as the entry point. It would contain only this:

include morkfiles/main.makefile

It’s just there to allow you to conveniently type make at the command line and kick off a build of all targets, or say make clean to wipe everything previously built.

Executables

So, how would you go about writing, say, an executable?

You’d start with a subdirectory called, say, myexe, where you’ll build your first executable (hence the boring example name).

You’ll need a main source file, myexe/myexe.cpp:

#include <iostream>

int main()
{
	std::cout << "Hello from myexe" << std::endl;
}

Not exactly world-changing, but good enough for now. If you typed make at this point, it would be weird and wrong if it went ahead and assumed anything. No, first we have to undertake the arduous task of writing a morkfile, which would be saved as myexe/morkfile and would contain this:

$(this)_type = exe

Now, there’s a lot of stuff to explain there, so I’ll go slowly… wait a second, no there isn’t. It’s literally one line long. It means, unsurprisingly, “This thing is going to be an executable”.

If you run make now, a mini-miracle occurs. Somehow mork figures out what to do. And you can run your new program:

myexe/bin/myexe

or on Windows:

myexe\bin\myexe.exe

Things to note:

• We haven’t told mork where to find the myexe directory. It automatically finds all files called morkfile. You can reorganise your source tree willy-nilly, add or remove modules, and never have to update any central configuration file.
• Neither did we have to add myexe/myexe.cpp to a list. An executable module is simply assumed to have source files directly inside it. All files with extension .cpp are automatically compiled and linked. We could add more source files under myexe if we wanted to, re-run make and they would be added to our executable.
• And of course, we only recompile what we need to. The second time you run make after changing nothing, it immediately reports it has nothing to do (even if you have dozens of modules, it says this very quickly, because only one instance of make is executing).

If you’ve used make before you may be wondering about the business of using the preprocessor to generate include file dependencies. Don’t worry about it; that stuff is taken care of automatically. No need to say make depends or anything like that. No stupid error messages when you delete a header. It just works.

Libraries

But real projects involve multiple targets – some are executables, some are static libraries, some are shared libraries (DLLs on Windows). These all have to depend on one another, which typically means that they have to be built in the right order, and include each other’s header files.

So let’s make a static library. Create another directory called myutil – you can put it absolutely anywhere beneath the top-level project directory (even inside myexe though that would be unnecessarily confusing, so don’t do that).

This time the source file, myutil/myutil.cpp, has no main function. Instead it exposes a function intended to be called from another module:

#include <myutil.hpp>

std::string myutil_says()
{
	return "world.";
}

We also need to write that header file. It goes in a subdirectory of the module, as myutil/include/myutil.hpp:

#ifndef MYUTIL_INCLUDED
#define MYUTIL_INCLUDED

#include <string>

std::string myutil_says();

#endif//MYUTIL_INCLUDED

That include subdirectory is where you put all headers that may need to be included by other modules – it’s the “public interface” of your module. Note that you don’t have to use the extension .hpp; the only significant thing here is the exact name and location of the include subdirectory.

Finally we have to confront that terrifying task of writing myutil/morkfile:

$(this)_type = static

Wait a second, that looks vaguely familiar! The only difference from last time is that we’re giving this module the type static instead of exe.

At this point we can run make and, no surprises, a library is built. It’s created under myutil/lib, but as we’ll see, you don’t even need to know that.

Now let’s make myexe use myutil. Back in myexe/myexe.cpp we adjust it to:

#include <iostream>

#include <myutil.hpp>

int main()
{
	std::cout << "Hello, " + myutil_says() << std::endl;
}

So myexe requires myutil. Now, mork is helpful, but not telepathic (or smart/stupid enough to try to scan your source files looking for implied dependencies between modules). You have to tell it that myexe requires myutil, by amending myexe/morkfile like so:

$(this)_type = exe
$(this)_requires = myutil


Couldn’t be simpler, could it? If your module requires another other modules, you list them in the $(this)_requires variable, separated by spaces, and mork takes care of adding myutil/include to the compiler options for myexe. It also (of course) deals with the linker options.

But it goes further – requirements are automatically transitive. That is, if module A requires module B (including some of its headers), and module B requires module C (so some of B’s headers include some of C’s headers), then it follows that A will not be able to compile successfully unless it can include headers from both B and C. But this is handled automatically: you only have to configure A to require B, and A will implicitly require C also, and so “it just works”.

Note that you only give the name, not the full path, to the required modules. Hence modules need to have unique names within the entire source tree, not just unique paths. This is a good idea anyway because when you distribute your software it’s usually convenient to put all the binaries (executables and shared libraries) in one directory, so they’ll need to have unique names.

But it has an additional nice advantage here, which is that even if you have dozens of modules that require one another in complex ways, you can still rearrange the modules under neat organisational subdirectories. It makes no difference to mork.

Dynamic Libraries

What about dynamic libraries (shared objects on Linux or DLLs on Windows)? It’s as easy as amending myutil/morkfile to:

$(this)_type = shared

That’s it. Run make again and everything is taken care of – mork even copies the built DLLs or shared objects to the bin directory of any executable that requires them, so it can be instantly executed.

Java

Oh yes, for good measure mork can build Java .jar files as well. You just have the morkfile look like this:

$(this)_type = jar

You put your Java source files in a subdirectory called src. The requires works exactly the same – it controls build order, as with native code modules, but also figures out the classpath settings.

This can be useful if you’re writing a mixed native/Java project with the emphasis on the native code. (If it was mostly Java, you’d presumably use Java build tools… by the way, I have something a little bit like mork but layered on ant, and integrating very nicely with Eclipse, so I’ll write that up sometime soon.).

Other stuff

There are more topics to consider, my favourite being code generation, which is a massively important technique, sadly underused in many projects, and many build tools don’t seem designed to support it, but mork is ready. And how do you integrate unit testing? Also very easy. But this post is long enough already.

ME WANT MORK!

I almost forgot… here’s where mork lives:

http://earwicker.com/mork

It has some examples with it that are very similar to the ones suggested here, but have more complex interdependencies. If you want to use it on Linux, it should just work, assuming you have the usual Gnu development tools.

Windows Quirks

On Windows, you need to install Cygwin with the development tools, and Visual Studio (for maximum interoperability with standard Windows libraries, mork uses Visual C++ as the compiler but relies on Cygwin for make, the bash shell and related commands – it even uses gcc, purely to get make-compatible dependencies).

So you need to have the Visual C++ tools and Cygwin accessible in your environment. The ordering of the PATH environment variable is important. Visual C++ paths need to be at the front of the PATH, so the correct (Microsoft) link.exe is used, then cygwin\bin so that the correct (Cygwin) find.exe is used, and finally the rest of your standard Windows PATH.

Next time: Part 3, in which we delve into how mork works, how to extend it, why the morkfile settings begin with $(this)_ and so on.

However, in that time I’ve cooked up a tiny framework of makefiles that I’m excited about. To put it another way, I’ve been driven partially insane by the experience – how else could someone get excited about something as old-fashioned as makefiles?

But if you’ve seen typical makefiles before, and then you see my beautiful new* alternative way of using them, I guarantee** you’ll get excited too. You’ll throw away*** your Visual Studio, Eclipse, NetBeans, Ant, Nant, Maven, and so on. They’ll seem so clunky in comparison to the elegance of my makefile framework. Oh yes.

(* Not really new)
(** Not an actual guarantee)
(*** Except for editing code and debugging and all that other stuff)

Note that throughout I’m talking about GNU make, not any of the many other incompatible makes.

The main cause of the excitement is my surprise when I actually starting R-ingTFM. Turns out that make is no less than a functional metaprogramming environment.

Like C++ templates, it uses recursively expanded definitions to generate a program. That generation process is “phase one”. Then the generated program actually runs, and has imperative/procedural elements to it: that’s “phase two”. Broadly speaking.

This is extremely powerful. Most of the things that people complain about being impossible in make are in fact perfectly possible, even easy, as long as you treat it as what it is: a functional metaprogramming environment.

Also, by the way, because it’s declarative and functional and so on, it’s amenable to automatic concurrency: make looks at what you’ve told it, and figures out which parts can run in parallel, and takes care of it (on Linux, anyway.)

It’s example time. If you want to play along, start a text editor, save the file as makefile. On Windows you’ll need to get Cygwin or MinGW, on Mac OS X you’ll need to install Xcode. Then you can type snippets in and save them, and from the same directory at the command line, run make. (Note that some of these early examples won’t do anything as we’re just defining variables.)

somevar = a b c d

I’ve created a variable called samovar, and stored a string containing four letters separated by spaces. Space separated lists are special – as well as being used wholesale as a simple string, there are handy built-in functions that treat them as lists.

This leads to Important Conclusion 1: spaces in filenames are bad. Just don’t put spaces in any of your directory or source files that you want make to deal with, and you’ll be fine. Probably seems a bit backward to you at first, but it turns out to be a fine trade-off.

To get the value of a variable:

othervar = before$(somevar)after

Now othervar contains beforea b c dafter because I referred to samovar in parentheses with a dollar sign in front, which tells make to substitute the value of the named variable.

Do those two definitions have to be in a particular order? What if I gave make the othervar definition at the top of the file and then the samevar definition after that? Can you guess?

The answer is due to the way make expands variables. My definition of othervar is stored exactly as I wrote it: the dollar sign, the parentheses, the somevar, are not expanded. Only when I actually refer to othervar in some context will make actually carry out the expansion, and by that stage it will know all the variable definitions.

Hence this is a problem:

a = $(b)
b = $(a)

Torturing make like that will just get you error messages.

You can in fact cause the expansion to happen at the point where you define the variable, by using := instead of plain =. For example, if you wanted to find all the png files in the images directory, you could say (using the built-in wildcard function):

all_pngs := $(wildcard images/*.png)

(Important Conclusion (IC)2: use forward slashes for file paths. On Windows, Cygwin will deal with it.)

The advantage of using := is that the directory gets scanned once and then all_pngs will contain a space-separated list of filenames. If you used plain = then the directory would get scanned every time you referred (directly or indirectly) to all_pngs.

And hence, IC3: variables defined with plain = are in fact functions. When you refer to them, you’re really calling them. They’re functions that don’t take any arguments, but they are still functions. They are in a simple sense closures: they close over the whole single variable namespace.

IC4: choose variable names carefully. One big namespace => danger of accidental clashes.

Actually you can pass arguments to variables when you refer to them. There’s a built-in function called call:

square_brackets = [ $(1) ]

example := hello $(call square_brackets,world)

Now example contains hello [ world ] – note how you can get the argument’s value in the definition by referring to its position (one-based).

Back to our list of pngs. I want to get a list of jpgs that would have the same base names as those pngs:

image_basenames = $(basename $(all_pngs))

Note how I don’t have to say “for each thing on the list, do something to it”. The built-in basename is list-aware. That is, it breaks up the input according to spaces, and then operates on each piece, and finally joins them back into a single string with space separators. To finish the example:

jpg_names = $(addsuffix .jpg,$(image_basenames))

Or to do both steps in one line:

jpg_names = $(addsuffix .jpg,$(basename $(all_pngs)))

There’s also a built-in foreach, which is like a general list operator, analogous to Select in Linq, or map in most other functional libraries. If you’re up on your monads, you’ll already have realised something semi-cool.

The core of a monad is the bind operator. For list monads this goes by various names depending on the language: in Linq it’s SelectMany, in Scala it’s flatMap. But it always does the same thing: for each item of the list, create a new list (somehow), and then join all the little lists together into one big list. The input is a list, the output is a list: that makes it composable.

In make the built-in list operators are all automatically monadically composable in that way, because a list is a string and a string is a list. (If the string has no spaces, it’s a list of one item, right?) So if you have a list-of-lists-of strings, then you already have a list-of strings. They’re indistinguishable. I said semi-cool because what if you don’t want the list to be flattened? But mostly you do.

IC5: This make stuff has all kinds of deep analogical relationships to interesting things!

Everything we’ve done so far is actually useless because it just defines string (or lists, same thing). With some shell incantations we can run make and print out the final value of a variable:

make -p | grep 'my_variable_name = '

But to actually cause make to do something we have to define a rule. The simplest kind of rule is:

files-to-build : required-files
	shell command
	shell command
	and so on

The shell commands are executed as normal operating system shell programs. The required-files and files-to-build are of course space separated. You can refer to variables anywhere. Note that each shell command has a tab indentation, and it must be a proper tab character, not spaces.

IC6: Make depends on a shell, so for portable makefiles, use UNIX-style shells on all systems (it’s the default on Windows with Cygwin anyway).

IC7: Use an editor that can make tab characters visible in some way.

The commands under a rule will only be executed if any of files-to-build has a timestamp that is earlier than any of required-files (or doesn’t exist at all). If any of required-files doesn’t exist, then make will complain, unless there is another rule in which that missing file appears in the files-to-build list, in which case make will run that other rule first, in the hope that it will cause the missing file to miraculously appear.

The upshot is that if you put a non-existent filename on the left, and nothing on the right, and then you make sure your shell commands don’t create the non-existent file, then you have something that will run every time you execute make:

run_every_time:
	@echo Hello, world!

When you run make, it will notice that run_every_time doesn’t exist, and go ahead with the commands in an attempt to make it. Note that it is not a terrible crime to fail to generate the target file of a rule, but most rules should be designed to do that. Most problems people get into with make involve trying to use phony rules to do imperative programming.

IC8: This is a tool for generating output files from input files, doing the minimum amount of work each time it is run. Each rule should take in some input files and write out some output files. Avoid writing rules that try to cheat the system; otherwise you’ll eventually get into a mess.

Now, what we’ve seen so far comprises the standard feature set of make as used in most makefiles. But I mentioned metaprogramming before; that’s not possible with these features along. Consider:

a = b = won't work
$(a)

That is, in variable a I store an expression that would (if it appeared on its own) assign the value won't work to b. And then on the next line I refer to that variable, hoping that this will cause b to be defined. But it’s a syntax error.

However, with another built-in, eval, we can do this:

$(eval $(a))

And that works! The variable b gets defined. So we can generate statements and then get them evaluated. But some things in make are inherently multi-line: rules especially. Can we define multi-line variables and so automate the declaring of rules? You’re darn tootin’ we can:

define my_recipe
cake: flour eggs sugar butter spices
	preheat oven
	mix sugar and butter
	stir in eggs
	stir in flour
	bake
	oh, forgot to add spices
endef

Note that my_recipe is just a variable. And by the way, did I mention that we can pass parameters to eval? I didn’t? Well, consider it duly mentioned.

This is where we can experience the true joy of metaprogramming, because we’re using the $(syntax) of variable references to generate code that must then go on to declare variable references that will only make sense later on. Some variables should be expanded before eval interprets its input. Others should go through eval unmolested so that they can be expanded later. To arrange this, we have to tell make to ignore some of our variable references by writing two dollars together: $$ is the escape sequence for a dollar. So eval ignores those variable references and “outputs” one dollar as a result, which can then be seen by make when it actually tries to evaluate things later on.

So, IC9: anything you’d declare in a makefile can be auto-generated within make from a multi-line template stored in a variable. There is never any need to repeat yourself. Say it once, say it loud: I’m metaprogramming and I’m proud.

It can get quite hair-raising when you’re trying understand snippets of metaprogramming, because two levels are intermingled. It is code talking about code. If you like that kind of thing, you’re a proper nerd like me. Hi!

Anyway, with these tools of functional metaprogramming in our back pocket, we can easily get make to solve a huge range of problems. Yes, easily. And we can make it so it runs fast. Yes, fast!

And yet so many blogs are full of people complaining about how make wouldn’t let them do this or that, or it took ten minutes to compile each file, so they came up with something else entirely. It’s a tragedy. Like the LISP programmers would say, every non-trivial C program contains an ad hoc implementation of LISP. Well, every new build-directing tool is basically the same as make, except that the author didn’t bother to RTF-make-M, so they didn’t realise they didn’t need to write their own version.

The number one cause of irritations with make is a technique called recursive make. When you have to build five static libraries, three dynamic libraries and four executables, plus some code generation, its often suggested that you should have a main makefile that visits each module’s directory and there runs another instance of make. But this turns out to be a very bad idea, as noted in this famous paper. I tried recursive make last week, and I’m not going to use it ever again. It runs counter to your nerd instincts to reject anything recursive, of course, because recursion is such an important, primal nerd totem. But this isn’t the same as abandoning recursion altogether! All the techniques described above are powerfully recursive – much more so than the specific technique known as “recursive make”, where you actually launch a separate instance. That technique sucks.

In Part 2: a quick tutorial of my fantasy make framework, where everything is easy and fast. And it’s not just a fantasy!

• reception
• accounts-dept
• meeting-rooms/1
• meeting-rooms/2
• bathroom

This is the ideal way to use the URL because it will fit perfectly with how the user expects the browser to work. The URL tells the application which room to display, and so the user can:

• Press the Back button to go back to the room they were in just now.
• Press the Forward button if they change their mind again.
• Bookmark (or “favourite”) the rooms they visit most frequently.
• Look at their History to see which rooms they’ve been in.
• Press the Refresh button to see an up-to-date view.
• Copy the URL from the address bar, paste it in an email and send it to a co-worker to say “Look at this!”
• Click a link (an underlined piece of text concealing a URL) to get to a different room.
• Right-click and choose Open in new tab to see a room on a different tab in their browser.

The above operations are the core features of the web browser. People expect them to work, and they are part of the reason why web applications have an advantage over custom thick client software. The mantra should always be:

If you want to know where you are, look at the URL

The interesting thing is that in many interactive web-based applications, including some of the most widely-used commercial sites on the Web, URLs are not used in this way, and they break much of that idealised functionality.

State

In the real world we learn to expect our environment to be stateful. Suppose you go up to your desk and arrange things to your liking, and then you turn away for a second. But it’s a magical desk: when you turn back to look at it again, it has “reset” itself! All the things you moved have somehow moved back to their original positions.

That would be usually very counter-intuitive and unhelpful (not to mention scary). So there’s nothing more annoying than an application that plays dumb and doesn’t remember what you were doing with it five minutes ago.

On the other hand, imagine checking into your hotel room only to find that the room is still in the state that the previous guest created: wet towels on the floor, bed not made, and so on. There should be a strict boundary between hotel guests so they don’t have visibility of another guest’s room state. So state has to have a well-defined and limited scope during which it is applicable.

So, can the URL store the state of a web application? Obviously there’s more to the state of a building than the name of the room you’re currently in. It is possible to encode various other pieces of information into plain text and then append that to the URL. But would that be a good idea?

The Accidental Time Machine

Consider an online store. Suppose when you visit the page that shows you what’s in your cart, the URL was:

shoppingCart?contents=12,8,442,23

That list of numbers contains the product codes of all the things you put in your cart. Each time you add a product to your cart, the URL changes, and the previous URL is added to your browsing history. And this in turn means that your browsing history contains previous versions of that list of purchases.

So that’s a crazy implementation! When you press the Back button to go back to your shopping cart, it won’t show you what it contains now. Instead it will show you what it contained at some previous time.

So instead of the Back button allowing you to retrace your steps, it allows you to move backwards through time! Or to put it less outrageously, it sort of works a bit like an Undo button.

You may have encountered this problem in real online stores; one example for many years was play.com, although it is fixed now.

The Receptionist Fired Twice

An even worse problem occurs when the URL in the address bar represents a command. Suppose you want to go into reception and fire the receptionist. If that was represented on the address bar:

reception?fireReceptionist=true

The page comes back telling you that you successfully fired the receptionist. You then visit a meeting room to tell them the news. While you’re in that room, a new receptionist is sent by the agency.

Then you hit the Back button to go back to reception, and… oh dear. You just fired the new receptionist as well! When you go back in the browser history, the URL is sent to the server exactly the same as the first time, and the server obeys it. This is even worse than the time machine bug. So applications have to employ all kinds of trickery to stop commands being obeyed more than once.

You may have seen some sites that plead with you not to press the Back button during some process – issuing a credit card payment, for example. It’s obviously not a great experience for the user, but for many years it was the best that could be done in some situations.

Another Page Expires

The most common problem of all is caused by POST. This is another way to send requests to the server, favoured because it allows a larger amount of data to be sent, even large files, but it has a very unfortunate side-effect. It puts an entry into the browser’s history that doesn’t work properly. When the user presses their Back button, they typically just get a confusing error message:

The page you requested was created using information you submitted in a form. This page is no longer available. As a security precaution, Internet Explorer does not automatically resubmit your information for you.

This still happens today on Amazon when you try to back out of buying whatever’s in your shopping cart. One workaround favoured by experienced users is to right-click on the Back button (click and hold on the Mac) to reveal a popup menu of recent history, so you can skip the problematic entry in your history and instead go to the page before that one. But you can’t do that on the iPad. In any case, instead of being a helpful UI, the browser has been transformed into a puzzle to be solved.

A large proportion of web applications have historically suffered from these and other issues. It’s only in the last five years or so that a pattern has emerged that allows us to build dynamic applications and yet still consistently deliver the original intended user experience of the web.

Some Modern Websites

Next time you look at a website, look closely at the URL in your browser’s address bar. Here’s what the Gmail address bar looks like:

And here’s Twitter (when you’re signed in):

The special ingredient these have in common is the hash symbol: #. That marks a division in a URL. Everything on the left, before the hash, is an instruction to the remote Web server, and so is interpreted on the server side. Everything on the right, starting with the hash, is never used by the server.

In normal Web development terminology (which can be confusingly overloaded) the part of URL starting at the hash symbol is also known as “the hash” of the URL. So in the Gmail example, the hash is:

#inbox

If the server is going to ignore this part of the URL, why is it there?

A Brief History of Hash

The original purpose of the hash (and still a perfectly good use for it) was to allow the creation of links to other places within the same document. For example, visit this page on Wikipedia:

http://en.wikipedia.org/wiki/Web_browser

It has a contents box (right) that just contains a few links to sections of the document. When you click the Features link, the browser’s address bar changes to:

http://en.wikipedia.org/wiki/Web_browser#Features

The key point is that the browser doesn’t contact the server when the hash changes or is added. That part of the URL is of no interest to the server, so there’s no need to contact it again. By default, all the browser does when the hash changes is scan through the HTML looking for an element that has an ID that is the same as the new hash, and scrolls the page so that the identified element is at the top of the window.

If there is no element in the document with that ID, it doesn’t do anything. So you can edit the hash to say anything you want, and your browser will just ignore you.

But otherwise, hash URLs are treated just like server URLs: they go into the browser history. You can press the Back button to revisit then, bookmark them, and so on.

This is the key to solving the various issues with the browser interactive applications. The hash part of a URL is for linking to things within the current document, instead of linking to other documents.

But now suppose you were to accept the following astonishing principle:

An interactive application is a single document.

Therefore it follows unavoidably that to support navigation within the application, you would use only hash URLs. That is, you would only vary the stuff after the hash symbol. Every navigation performed by the user within the application will not directly result in a round-trip to the server. Something else has to happen instead.

The default behaviour, scrolling to an element with the specified ID, isn’t much use generally speaking. But with JavaScript we can respond to a change in the URL in any way we like.

Detecting a Hash Change

Newer versions of many browsers have a built-in scripting event that is raised whenever the URL changes. In less capable browsers it is necessary to start a timer that will periodically check the URL to see if it has changed. Of course, it’s simple enough to hide this inside a jQuery plugin, and sure enough, here’s such a plugin.

For even greater convenience, you will want to bind different handlers to a specific URL pattern. You could do that by handling the hashchange event and then parsing the URL manually, or you could use a library to do this for you. For this I’ve found sammy.js to be excellent. For example, you can register a handler to render meeting rooms:

this.get('#/meeting-rooms/:roomNumber', function(context) {

Within the handler, you can access context.params.roomNumber to get the variable part of the URL, because any path segment prefixed with a colon denotes a parameter.

The remaining question is: now that we’ve utterly eliminated the server from this picture, how do we bring it back?

Ajax To the Max

The answer is that we call it when we want to. The browser doesn’t dictate anything. Calls to “the backend” are decoupled from the UI, and it’s entirely up to us how we re-couple them.

The short answer is simple and obvious: when you need some more data, or you need to update some data stored on the server, you make a call. You may even find it convenient to make multiple calls in sequence or in parallel, depending on how much control you have over the backend’s API “surface”.

If you sign into Twitter and use a logging proxy like the wondrous Fiddler, you will see that once the main page of the application has been downloaded, practically all subsequent calls back to the server are to api.twitter.com and they return very clean JSON data structures, rather than HTML formatted on the server. All the updates to the page are performed in the client-side JavaScript.

And this allows the user experience to take on a new slickness – it isn’t necessary to discard and rebuild the whole page. You can update some patch of it, and perform an animated transition. There are suddenly a lot more possibilities for making your application more modern, fresh and engaging, and they are easy to do, especially with jQuery and its army of plugins – the Web is full of examples, because jQuery is so widely used already.

What About Search Engines?

The scope of this kind of architecture is limited by a simple fact: search engines (which is to say: Google) will not execute JavaScript code during their indexing processes, and so will not follow your hash-links.

So if you want Google to index your site, you either cannot use this approach, or you’ll need to develop a basic old-school version of the site so that Google can index it. It doesn’t have to be as snazzy or helpful as the JavaScript version – it just has to serve up all the indexable text.

Of course, a great many web applications are behind an “authentication wall” – the user must sign in before they can see anything. Such applications don’t want Google to index their data, and so they don’t need to worry about this.

Another possibility is that you may want to support users who suffer from the same limitation as Google’s indexer – they don’t want to execute JavaScript and choose to disable it. It’s up to you whether you see that as a market you need to serve, of course. It’s a rapidly shrinking market – and in fact some newer browsers don’t even have an option to switch JavaScript off.

Much more important is the issue of accessibility: how does a blind person access your site? But this is not actually solved automatically by the classic web model – you have to design accessibility. And you can do this for a heavily JavaScript-based application too.

The unfortunate truth is that most companies neglected accessibility when working under the classic web model, and they’ll probably continue to neglect it in the future, but this is an underlying problem that probably cannot be solved by technology.

The Unnameable Way

The term AJAX was introduced to describe an early variant of this pattern: the X stood for XML, which has nothing to recommend it nowadays. And when most people say AJAX, they are probably still talking about a traditional web application that contains a few specific uses of scripted calls to the server, but otherwise suffers from the flaws we identified earlier.

By fully embracing the pattern, those flaws can be solved. And to be clear, the pattern is:

• A single static .html document establishes the permanent structural framework of the application, and pulls in the script that registers handlers for certain hash URL patterns.
• Those handlers update the UI to reflect the location specified in the current hash URL, probably by making calls back to a clean JSON-based API exposed at the server.
• State that is not related to navigational location never appears in the URL, and nor do commands that have side-effects on state, because URLs can be revisited via the browser’s history features.

Naturally there’s an ironic footnote to this story.

The Ironic Footnote

Back in the early 1990s, people wrote things that were grandly called “client-server applications”. In practise, this meant a Visual Basic UI with an RDBMS storing the data. Microsoft dominated the desktop, and it seemed only a matter of time before they would dislodge Oracle from the server side as well.

The web seemed to blow this model out of the water, because people were – quite rightly – impressed by the browser as a universal window to the information world and began to view it as something that applies to everything. The old model was derided as “thick client”, in contrast to the much-admired “thin client” represented by the browser.

In truth, the client server approach was evolving towards a “not-too-thick” client model, because the RDBMS was a fairly capable development platform itself. Business logic could be moved into stored procedures. Even so, that implied an unnecessary dependency on a highly proprietary platform, and was generally avoided for that reason.

One proposed alternative, prior to the Web, was the business logic server, embodied in products like Microsoft’s Transaction Server (MTS). There was much talk of tiered applications: the client (in Visual Basic, of course), the business logic in MTS, and the data layer in SQL Server. But again, it was obviously proprietary, and it was hard to see how it might fit into the all-conquering Web, so it was swept into the dustbin of history.

The LAMP stack was all-conquering! Or so it seemed.

The strange truth is that the built-in capabilities of the browser actually did not make it at all easy to support the browser’s navigation model in an interactive application. In fact it made it very easy to break it. If you wanted a nice browsable UI, it would have been easier to just add Back and Next buttons to your crummy Visual Basic application!

Where we have now arrived, the world doesn’t look too dissimilar to the proposed pre-Web model. The vital difference is that it is a victory for the vendor-neutral approach:

• There is now a great variety of ways to store data, not all of them SQL-based.
• The business logic API is exposed by any Web server, simply so it can be called directly in standard ways from any browser.
• And within the browser we can write “not-too-thick” clients that present an ideal user interface into the business logic.

We took quite a tortured route to get to the destination. But we’re there now. Phew.

This is the first one I’ve seen in a Mac product, where the Cancel button is normally placed first (the opposite arrangement to Windows), and I’m not sure, but that seems to make the problem slightly worse.

Pavtube Bytecopy for Mac OS X. http://www.pavtube.com

As usually described, it’s… (deep breath)… a function A that accepts a function B that will immediately be called by the language runtime, passing it a function C that when eventually (optionally) called will cause the previous call to A to return the argument previously passed to C and so take us back to where we started – but only if C was actually called. All clear?

No. Nobody ever learned what it’s for by reading a description like that. It’s the kind of description you can understand only if you’ve already had the thoughts that are expressed in it.

Well, my ambition in life is to explain it in a way that any reasonably experienced Java or C# programmer can understand, so I’ll put my current best effort here. Let me know if it helps, or hinders.

There are actually several ways to implement this feature, and any good Java programmer can invent one, once they have a description of it in Java (or OO C#) terms. In fact I suspect it’s easier to go the other way: understand a familiar practical problem in Java terms, and then see how it can be seen as an example of call-with-current-continuation. And then we’ll see why it’s not a great way to implement it, and eventually we’ll understand why the “call stack” concept (the basis for method calls, threads and local variables in Java and C#, as well as older machine-level languages) isn’t quite as fundamental as it may seem. And also why (thinking about C# 5.0), depending on how a runtime is implemented, it may not be necessary to have special keywords to support continuations.

(Although I’m talking in terms of Java, you can follow this just as well if you think of it as C#-without-delegates, which is much the same thing.)

Suppose you had an interface:

public interface AsyncResultReceiver<T> {
  void setResult(T result);
}

(C# programmers will be itching to put an I in front of that name. Let it go!) It looks like it’s part of some asynchronous programming library, a way to push a return value back to something that is waiting for it.

And suppose you had another interface:

public interface AsyncRunnable<T> {
  void doStuff(AsyncResultReceiver<T> receiver);
}

This represents some operation that you can start off by calling doStuff, and you pass it your implementation of AsyncResultReceiver so you can receive the result whenever it’s ready.

So for example you might write a class such as DownloadUrl that implement doStuff so it downloads in a background thread. When it finishes, it has a String of downloaded content, and internally it says:

notifyComplete.setResult(content);

Now, suppose the bit of application code you’re writing needs to block (wait) until the operation has finished. You’d prefer to be able to say:

String url = askUserForUrl();

byte[] html = downloadUrl(url); // much more helpful

displayHtml(html);

But you can’t, because of this pain-in-the-neck fancy asynchronous system. You need some kind of helper class to receive the result:

String url = askUserForUrl();

DownloadUrl downloader = new DownloadUrl(url);
BlockingReceiver<String> receiver = new BlockingReceiver<String>();
downloader.doStuff(receiver);
byte[] html = receiver.getResult();

displayHtml(html);

BlockingReceiver is a simple stock implementation of AsyncResultReceiver designed to solve your exact problem. I imagine, with my limited knowledge of Java concurrency primatives, it would look like this:

class BlockingReceiver<T> 
  implements AsyncResultReceiver<T> {

  CountDownLatch signal = new CountDownLatch(1);
  T result;

  public void setResult(T r) {
    result = r; // stash the result
    signal.countDown(); // wake up anyone waiting for it
  }
  
  public T getResult() {
    signal.await(); // sleep until there's a result
    return result;
  }
}

It seems simple enough, but we can make it even more easy to use by writing a static helper method, with a curiously familiar name:

public T callCC(AsyncRunnable<T> func) {
  BlockingReceiver<T> receiver = new BlockingReceiver<T>();
  func.doStuff(receiver);
  return receiver.getResult();
}

That captures the standard pattern so our example call shrinks to:

String url = askUserForUrl();

String html = callCC(new DownloadUrl(url));

displayHtml(html);

We could use that same callCC helper for any asynchronous operation, as long as it is encapsulated in a class that implements AsyncRunnable. It’s a general tool for bridging the mismatch that occurs when we have information being returned via a callback, and we would prefer to receive the information in a return value.

Let’s go back to that opaque abstract description we started with:

A function A that accepts a function B that will immediately be called by the language runtime, passing it a function C that when eventually (optionally) called will cause the previous call to A to return the argument previously passed to C and so take us back to where we started – but only if C was actually called.

We need to label some pieces of the Java example to see how it matches up. Function A is callCC. So it accepts a function B… wait a second, looking at our code we can see it actually accepts an object that implements AsyncRunnable. But that interface only has one method, doStuff. So that object is a “function”, in the sense that there is only one way you can interact with it: to call its single method. So logically speaking, it’s no more than a function.

Therefore function B must be that instance of our DownloadUrl class. According to the description, it is immediately called back and passed a function C. In our Java code we see:

BlockingReceiver<T> receiver = new BlockingReceiver<T>();
asyncRunnable.doStuff(receiver);

Sure enough, we immediately call asyncRunnable.doStuff, and we pass it a fresh instance of BlockingReceiver… which must therefore be function C!

So we’ve successfully labeled all the pieces. One of the functions is a static method, and the other two are really objects with one method, but they’re functions too, logically speaking. Fine.

The description then notes that C can optionally be called. This caveat refers to the fact that whoever writes the DownloadUrl class has a responsibility: they have to at some point call AsyncResultReceiver.setResult from the background thread, or we’ll never find out what was downloaded.

When they do call it, passing a string hopefully containing some downloaded HTML, the BlockingReceiver stashes it and wakes up the original thread, which then returns the string. Or as the description has it, it will “cause the previous call to A return the argument previously passed to C and so take us back to where we started.”

Okay, so we can be certain that callCC is call-with-current-continuation implemented in a certain way. But it’s not quite the way it gets implemented in interpreted languages. It has a particular disadvantage.

I’ve drawn attention to the fact that calling C (a.k.a. AsyncResultReceiver.setResult) is optional. If it isn’t called, then A (callCC) never returns. This is certainly true in our Java implementation – what happens is that the thread that called callCC stays locked up forever! It’s waiting for someone to call CountDownLatch.countDown.

So we’re interpreting the word “optional” very liberally here. It’s only optional if you don’t mind your program leaking locked threads. Can anything be done to avoid this? On the other hand, what would it mean to simply avoid the problem – would that be useful?

What we’re saying is that we could write a sequence of statements like:

String url = askUserForUrl();

String html = callCC(new DownloadUrl(url));

displayHtml(html);

… and if the download fails, we are quite happy if the callCC never returns (maybe the DownloadUrl class takes care of displaying an error?) and so the sequence of statements doesn’t continue executing. It somehow gets garbage collected away into nothing.

This is quite neat. It’s an alternative approach to exception handling. We don’t have to write code to say what the thread should do if there’s an error. The thread simply pops out of existence; it is absolved of all future responsibilities.

To achieve this, we’d need to modify how the JVM works. Right now it has threads, and every thread has a call stack containing the local variables (including parameters) for every currently incomplete method call in the thread. None of this is under the control of the garbage collector, so it can’t help clean up after us.

Instead, let’s make it work by allocating a garbage collectable object to represent each incomplete method call. These objects will contain the local variables and parameters as fields, and also an integer field indicating where they have reached inside the method’s bytecode. Finally, they hold a reference to another method call object, the one that called them and that they will eventually return to.

For example, given a Java method:

public int foo(int x, int y) {
  System.out.writeln("Going to add some numbers");
  int z = x + y;
  System.out.writeln("Answer was: " + z);
  return z;
}

That would need this class to store its local variables and parameter values:

public class FooCall extends MethodCall {
  public int x, y, z;
}

The base class would take care of the stuff common to all method calls:

public class MethodCall {
  public byte[] code;
  public int position;
  public MethodCall returnTo;
}

So the new model JVM would start by loading a class, looking for the main method, and allocating a suitable MethodCall to represent a call to it. It would put the method’s definition in the code field, and leave returnTo set to null and position at zero (pointing to the start of the method’s bytecode in the code array).

When it hits a call to another method, it sets the position to the right place to return to, and creates another MethodCall object for the called method, in which the returnTo field is set to point to the calling method. So at any given moment there is a chain of objects all the way back to main.

This means that the JVM itself only has to hold a reference to the top-most MethodCall object – the one it is executing. That alone will cause the garbage collector to keep the chain of objects alive. But it also means that if the JVM ever abandoned that top-most object, then the chain would automatically get collected by the GC. Nifty!

With these underpinnings, the JVM can implement callCC for us, in a different way, using some butt-ugly primitive operations:

public T callCC(AsyncRunnable<T> asyncRunnable) {

  BlockingReceiver<T> receiver = new BlockingReceiver<T>(CALLER);
  
  asyncRunnable.doStuff(receiver);
  return null; // we never get here!
}

And so it must implement BlockingReceiver a different way as well:

class BlockingReceiver<T> 
  implements AsyncResultReceiver<T> {

  MethodCall returnTo;
  
  public BlockingReceiver(MethodCall r) {
    returnTo = r;
  }

  public void setResult(T r) {
    GOTO(returnTo, r);
  }
}

Here I’m imagining that the JVM has two low-level instructions: CALLER is a pseudo-variable containing the MethodCall that called the currently executing method. GOTO is a pseudo-method that swaps in a different MethodCall to be the currently executing one (abandoning the existing one). It expects that method call to be stuck in a position where it is about to return from a method call, and so it needs to know the return value to pass back (if any).

So the statement return "A string"; really means:

GOTO(CALLER, "A string");

This is how call-with-current-continuation works in interpreted languages. In these ugly, technical terms, a “continuation” is literally just an object of a class derived from MethodCall, which has its position field pointing to the bytecode instruction that comes right after a call to a method and is expecting a return value (unless it called a void method, of course).

Sometimes people describe a continuation as a snapshot of the state of the program at some point in the past, but that is incorrect. It’s not a complete snapshot of all state. It’s just a reference to a MethodCall and hence the chain of other calls that led to its creation. But when we bring it back to life using GOTO, various other things might have changed; the values stored in the fields of various objects will have been modified. So the program is definitely not put back into exactly the state it was in previously.

This is enough for one blog post, but there are implications to deal with. Somewhere further down the line, I’ll tie this into my series of posts on exceptions (like, what the heck happens to try/finally in this alternative runtime model?)

In my next post I’ll address the first question that probably springs to mind: why is it customary to expose callCC as the primitive operation for public use, instead of exposing CALLER and GOTO directly? And if a method call can sometimes never return, is it okay for it return more than once?!