Interoperability Details

As mentioned in the README, streamline interoperates seamlessly with standard node.js code: you can call node.js APIs from streamline code, and you can call functions written with streamline from normal node.js code.

There is just one area that deserves a bit of attention: exception handling. Streamline gives you two options:

• a safe option for those who don't want to worry about the details and are ready to pay a slight performance hit.
• a fast option for those who care about details and want optimal code.

The safe option

The safe option is enabled by adding a line like the following in your streamline source module: // pragma streamline.extraTryCatch

With this option, streamline will add try/catch logic in the generated code to guarantee the following:

• The generated function never throws an exception to its caller. It transforms all exceptions into callback(err) calls.
• If an exception occurs during a callback, it will be properly caught and propagated.

The fast option

The fast option is the default one. With this option, streamline does not add try/catch logic to the generated code. So you get optimal performance. You can still do rigorous exception handling but you need a bit of extra care. To explain it I'll start with a small diagram of the code flows inside a chain of asynchronous functions: f1 begin --> f2 begin --> f3 begin --> f4 begin f1 callback <-- f2 callback <-- f3 callback <-- f4 callback And we have to deal with two types of exceptions:

• exceptions that are thrown explictly by a throw statement.
• exceptions that are thrown implicitly by a bug (dereferencing null for example).

Let us assume that f1 is a hand-written function, that f2 and f3 have been generated by streamline and that f4 is a low level node.js API.

Inside f2 and f3, all the throw statements (in the begin flow and callback flows) are converted into _(err) calls. So, they will reach f1's callback as you would expect them to. But that's all. All other exceptions (thrown by f1 or f4, or caused by bugs in f2 or f3) will propagate as exceptions. In the begin flow, they will bubble up to f1 and in the callback flow they will bubble up to f4. So, we need a bit of extra care at both ends to properly deal with this situation.

more later....