https://github.com/guujiang/jacob
A lightweight library to provide coroutines in Java
https://github.com/guujiang/jacob
bytecode coroutine coroutines generator java
Last synced: 5 months ago
JSON representation
A lightweight library to provide coroutines in Java
- Host: GitHub
- URL: https://github.com/guujiang/jacob
- Owner: GuuJiang
- License: bsd-3-clause
- Created: 2018-05-08T19:01:00.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2018-05-31T13:34:06.000Z (about 8 years ago)
- Last Synced: 2025-07-12T18:30:27.734Z (11 months ago)
- Topics: bytecode, coroutine, coroutines, generator, java
- Language: Java
- Homepage:
- Size: 37.1 KB
- Stars: 16
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Jacob
A lightweight library to provide coroutines in Java
# Usage
## add dependency for jacob-core
```xml
com.guujiang
jacob-core
0.0.1
```
## 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.
```java
// 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 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.
```xml
com.guujiang
jacob-maven-plugin
0.0.1
enhance
```
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:
```
## For more information, refer to the [jacob-samples](https://github.com/GuuJiang/Jacob/tree/master/jacob-samples) project