Jacob

A lightweight library to provide coroutines in pure Java

License	BSD-3-Clause
GroupId	com.guujiang
ArtifactId	jacob
Last Version	0.0.1
Release Date	May 31, 2018
Type	pom
Description	Jacob A lightweight library to provide coroutines in pure Java
Project URL	https://github.com/GuuJiang/Jacob
Source Code Management	https://github.com/GuuJiang/Jacob

Download jacob

Filename	Size
jacob-0.0.1.pom	2 KB

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/com.guujiang/jacob/ -->
<dependency>
    <groupId>com.guujiang</groupId>
    <artifactId>jacob</artifactId>
    <version>0.0.1</version>
    <type>pom</type>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/com.guujiang/jacob/
implementation 'com.guujiang:jacob:0.0.1'

Gradle Kotlin

// https://jarcasting.com/artifacts/com.guujiang/jacob/
implementation ("com.guujiang:jacob:0.0.1")

Apache Buildr

'com.guujiang:jacob:pom:0.0.1'

Apache Ivy

<dependency org="com.guujiang" name="jacob" rev="0.0.1">
  <artifact name="jacob" type="pom" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='com.guujiang', module='jacob', version='0.0.1')
)

Scala SBT

libraryDependencies += "com.guujiang" % "jacob" % "0.0.1"

Leiningen

[com.guujiang/jacob "0.0.1"]

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

• jacob-core
• jacob-samples
• jacob-maven-plugin

Jacob

A lightweight library to provide coroutines in Java

Usage

add dependency for jacob-core

<dependency>
    <groupId>com.guujiang</groupId>
    <artifactId>jacob-core</artifactId>
    <version>0.0.1</version>
</dependency>

write a class contains one or more generator methods.

A generator method is a method which returns Iterable and generate some values in the middle with the yield method.
Here is a example.

// strongly recomended to import the yield method as static to make the syntax more natural
import static com.guujiang.jacob.Stub.yield;

import com.guujiang.jacob.annotation.Generator;
import com.guujiang.jacob.annotation.GeneratorMethod;

// add the @Generator annotation to class
@Generator
class Generator {

    // add the @GeneratorMethod to methods
    @GeneratorMethod
    public Iterator<Integer> someMethod() {
        for (int i = 0; i < 5; ++i) {
            // call the yield method whenever you want to "return" a value out
            yield(i);
        }

        // a return statement must be added in the end to make the compiler happy
        // the return value does not matter, offen use null
        return null;
    }
}

Enhance the bytecode

jacob convert your normal Java method into coroutine with bytecode manuplation, which can happen at two points. You only need to choose one of them.

1. Enhance at the compile time.(recommended)
   add the following plugin to your maven project's pom.xml.

<plugin>
    <groupId>com.guujiang</groupId>
    <artifactId>jacob-maven-plugin</artifactId>
    <version>0.0.1</version>
    <executions>
        <execution>
            <goals>
                <goal>enhance</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Package jar file with mvn package, the plugin will automatically convert all the classed with proper annotations into coroutine form. Then you just need to execute the generated jar file or use as dependency.

2. Enhance at runtime.
   If you cannot enhance the classes at compile time, you can also do it at classloading.
   First compile the jacob-core project with mvn package to get a file called jacob.jar. Then add the following parameters to your java command line when launch the program which used the generator code.

-javaagent:<path of jacob.jar>

For more information, refer to the jacob-samples project

Versions

Version
0.0.1 May 31, 2018