Derived project licence question

[bvella]

I have used this code as a basis for an async/await transformer. I have changed the api significantly, which is why I am not going to submit a pull request. I would not mind discussing the changes though, so we can make both projects better or possibly merge them at some point, but this is for another time.

I have retained the licence text in 2 source filed that I used from this project. Q1: Is it enough to retain the licence text for these files only or does the licence automatically apply to all the artifact?

I would like to publish the compiled artifact to maven central. Since the licence states:

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Q2: Do I need to add anything to the compiled artifact? or just deploying the source jar with the licence text in the source files be enough?

Thanks in advance

[JoeHegarty]

Hi @bvella I am not a lawyer but my take is this:

1. Retaining the license only on the top of the files which are EA licensed should be sufficient.
2. Given that maven central requires you to push the source I think the above should be all you need. It's not typical to bundle the license in a binary library jar on Maven as far as I am aware.

Given I'm the maintainer for this project I think you can just go ahead and do that without any issue.

I'd definitely be interested in seeing the work you have done and exploring whether the projects can be merged.

Hope that helps.

[bvella]

Thanks for the info @JoeHegarty. I will push the library soon following the above. I don't know if these comments are the appropriate place to discuss the changes I made. Here's a summary of the changes and rationale. Feel free to suggest an alternate place to continue the discussion.

API

Although your approach appears to be non-invasive (transforming the same method in-place), the abstraction becomes inconsistent when considering checked exceptions. Considering the method:

CompletionStage<Void> doSomething() throws SomeException;

It is unclear whether the method can throw the exception or whether the completion stage can be rejected with that exception. This led me to change the API such that async methods return type Async, which is a final class, instead of CompletionStage or any class implementing it. The methods are then transformed into their async counterparts without the exception in the signature:

Async<Void> doSomething() throws SomeException;

is transformed to

CompletionStage<Void> async$doSomething();
(synthetic) CompletionStage<Void> continuation$async$doSomething(...);

I tried to stick with the semantics of async/await in other languages, namely javascript and .net, where you can only await in async methods, and async method are methods that return Async<>, while keeping the existing java semantics like e.g. exception handling, intact.

Transformation I tried to simplify the transformation in the following ways:

• because async methods return Async<> which is a final class, I do not have to deal with detecting subclasses. However, I now need to generate 2 methods: for Async op() I generate CompletionStage async$op() and CompletionStage continuation$async$op(..., async$state, async$stage)
• I moved all the method's logic to the continuation method. Instead of transforming the original method across 2 methods (the original and continuation), I only transform it to the continuation. the async$ method calls the continuation$async$ method with state 0, and wraps the call in a try..catch block. the continuation$async$ method switch at index 0 is the first chunk of code before any await() calls, indices 1 onwards for code after each await(). I also call helper methods to compose the continuation instead of calling future.exceptionally(..).thenCompose(..), which allows me to do other tricks (e.g. joining asynchronous stack traces) without complicating the transformer.
  • Probably because of these simplifications, I built and ran the test suite with java 9 without problems (had to use asm 6.0 beta though, so I will wait for asm 6 to be stable first before supporting java 9)
• I hooked into the java compiler using an annotation processor and am transforming the code in as it gets compiled. This means:
  • in maven you only need to add an optional dependency for transformation to work (provided annotation processing is not turned off in the maven-compiler-plugin)
  • any ide that supports annotation processors works out of the box. In fact, this is working seamlessly in intellij without any changes except turning on annotation processing.
  • This approach uses internal javac api's so, although it works with the oracle and openjdk compiler, it will probably not work with the eclipse compiler.

Other stuff In addition to the above transformations, I have developed some async helpers namely:

• async tracing, which joins the stack traces of all the asynchronous bits so when an exception is thrown, the async process can be traced all the way to where it was triggered
• async locals - work like thread locals but for async processes
• async queue - queue tasks that require the same shared resource, effectively lets you replace locking with queueing