8000 orbit/async at v0.3.0 · dominicgunn/orbit · GitHub
[go: up one dir, main page]

Skip to content
  • Latest commit

     

    History

    History

    async

    Folders and files

    NameName
    Last commit message
    Last commit date

    parent directory

    ..
     
     
     
     
     
     
     
     

    README.md

    Orbit Async

    Orbit Async implements async-await methods in the JVM. It allows programmers to write asynchronous code in a sequential fashion. It was developed by BioWare, a division of Electronic Arts.

    If you're looking for async await on the .NET CLR, see Asynchronous Programming with Async and Await.

    Documentation

    Documentation is located here.

    License

    Orbit is licensed under the BSD 3-Clause License.

    Simple Examples

    With Orbit Tasks

    import com.ea.orbit.async.Await;
    import static com.ea.orbit.async.Await.await;
     
    public class Page
    {
        public Task<Integer> getPageLength(URL url)
        {
            Task<String> pageTask = getPage(url);
     
            // this will never block, it will return a promise
            String page = await(pageTask);
     
            return Task.fromValue(page.length());
        }
    }
    
    // do this once in the main class, or use the orbit-async-maven-plugin, or use -javaagent:orbit-async.jar
    Await.init();
    
    Task<Integer> lenTask = getPageLength(new URL("http://example.com"));
    System.out.println(lenTask.join());

    With CompletableFuture

    import com.ea.orbit.async.Async;
    import com.ea.orbit.async.Await;
    import static com.ea.orbit.async.Await.await;
    
    public class Page
    {
        // must mark CompletableFuture methods with @Async
        @Async
        public CompletableFuture<Integer> getPageLength(URL url)
        {
            CompletableFuture<String> pageTask = getPage(url);
            String page = await(pageTask);
            return CompletableFuture.completedFuture(page.length());
        }
     }
    
    // do this once in the main class, or use the orbit-async-maven-plugin, or use -javaagent:orbit-async.jar
    Await.init();
    
    CompletableFuture<Integer> lenTask = getPageLength(new URL("http://example.com"));
    System.out.println(lenTask.join());

    Getting started

    Orbit Async requires JVM 1.8.x as it relies on CompletableFuture, a new class.

    It can work with java and scala and with any JVM language that generates classes using methods with CompletableFuture, CompletionStage, or com.ea.orbit.concurrrent.Task return types.

    Using with maven

    <dependency>
        <groupId>com.ea.orbit</groupId>
        <artifactId>orbit-async</artifactId>
        <version>${orbit.version}</version>
    </dependency>

    Instumenting your code

    Option 1 - Runtime

    On your main class or as early as possible, call at least once:

    Await.init();
    

    Provided that your JVM has the capability enabled, this will start a runtime instrumentation agent.

    This is the prefered solution for testing and development, it has the least amount of configuration. If you forget to invoke this function, the first call to await will initialize the system (and print a warning).

    Option 2 - JVM parameter

    Start your application with an extra JVM parameter: -javaagent:orbit-async-VERSION.jar

     java -javaagent:orbit-async-VERSION.jar -cp your_claspath YourMainClass args...
    

    Option 3 - Compile time instrumentation, with Maven

    Use the orbit-async-maven-plugin. It will instrument your classes in compile time and remove all references to await.

    This is the best option for libraries.

    <build>
        <plugins>
            <plugin>
                <groupId>com.ea.orbit</groupId>
                <artifactId>orbit-async-maven-plugin</artifactId>
                <version>${orbit.version}</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>instrument</goal>
                            <goal>instrument-test</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
    
    0