search

nealkumar / JBrew

The JBrew library collection is a set of of Java & JNI utility libraries featuring native facades that precisely tune elected garbage-collection sensitive operations for downstream consumers with use-cases hindered by the Java Memory Model. The library also seeks to abstract away syntax pitfalls in concurrency through its Task framework.
https://jbrew.org/
BSD 3-Clause Clear License
0 stars 0 forks source link
blocking-queue concurrency concurrent jni jni-api jni-java multithreading native race-conditions retrievable synchronization task-queue utility

readme

Maven Central Documentation Build Status Sonarcloud Status codecov CodeFactor Build Status DepShield Badge Gitter License GitHub commit activity OSS Lifecycle (branch) JDK 1.8+

JBrew Home

User Installation

Note that contributors or other users who wish to use the latest nightly build should follow the Upstream Installation guide.

GNU/Linux (Red Hat Enterprise, Fedora, CentOS, Ubuntu, Debian, Arch, Clear), FreeBSD (11.2+)

  1. Simply download the file "install.sh" above. FreeBSD users should use the file "install-freebsd.sh" instead.
  2. At your desired java.library.path, run "install.sh" in the terminal, like so:
    • ./install.sh will install to the current directory, OR
    • ./install.sh /path/to/java.library.path will install to the directory specified.
  3. You may be prompted to enter sudo password. Note that no text or cursor movement will appear on screen.
    • [sudo] password for user:  Enter your credentials, then hit [Enter].
  4. Your installation is complete! Important: Make sure you set your java.library.path to the location specied in part 2, appended with /bin (Ex: java.library.path=/path/in-part2/bin) before compiling your code, as these libraries have links to native libraries.
    • Essentially, whenever you run the java command, you will need to add -Djava.library.path=path/to/where-you-ran/install.sh/in-step-2/bin (Don't forget to append "/bin" to the end of the location!). More detailed istructions can be found here. Just remember to append "/bin"!
    • For Maven JUnit tests, it is reccomended you add the Apache Surefire plugin and provide the java.library.path as a compiler argument. Use these instructions if you are unsure how to do this.

      JBrew Maven Dependencies

      The following libraries are synchronixed with Maven Central, and can be inserted into your project's pom.xml as a dependency.

Concurrency Library

  <dependencies>
    <dependency>
      <groupId>org.jbrew</groupId>
      <artifactId>concurrent</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

CBrew JNI Library (See User Installation Guide before using)

  <dependencies>
    <dependency>
      <groupId>org.jbrew.cbrew</groupId>
      <artifactId>cbrew</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

CBrew Libary Validators (See User Installation Guide before using)

  <dependencies>
    <dependency>
      <groupId>org.jbrew.cbrew</groupId>
      <artifactId>cbrew-validators</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

Native Libary Validators (See User Installation Guide before using)

  <dependencies>
    <dependency>
      <groupId>org.jbrew.native</groupId>
      <artifactId>native-validators</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

Native Library Core (See User Installation Guide before using)

  <dependencies>
    <dependency>
      <groupId>org.jbrew.native</groupId>
      <artifactId>native</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

JBrew Core Annotations

  <dependencies>
    <dependency>
      <groupId>org.jbrew.core</groupId>
      <artifactId>annotations</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

JBrew Core

  <dependencies>
    <dependency>
      <groupId>org.jbrew.core</groupId>
      <artifactId>jbrew-core</artifactId>
      <version>0.1.0-beta.6</version>
    </dependency>
  </dependencies>

Upstream Installation

To install the JBrew library locally, simple clone this libary from the branch staged-for-release to get the latest nightly build. Next, run "mvn package" at the project's root directory. If you receive errors, please proceed to follow the installation steps below for your specific operating system.

GNU/Linux

The GNU/Linux is supported as the primary development for JBrew. As such, no additional configuration is needed for most Linux distros. JBrew is actively tested on the following Linux distrubtions:

Finally to return the value, one simple has to set the value for obj or this.obj, as such:

  public class ExampleTask extends RetrievableTask<String>{
      @Overide
      protected void execute(){
        //do work, execute business logic

        //then set the return value for ExampleTasks's object
        this.obj = "Example task successfully completed";
      }
  }

Non-Retrievable or Basic Tasks

Once NonRetrievableTask or BasicTask has been extended, this allows for simple concurrent execution where the business logic executed does not need to return back an object. As a result, calling the getVal() method for a NonRetrievableTask throws an java.lang.UnsupportedOperationException.

Example usages: initializers, message dispatchers, or any standalone time-consuming task which you would like to execute concurrently.

Client Usage Examples

Regardless on the type of Task needed, each respective Task should be wrapped within with a Thread and will begin execution upon calling of the start() or run() methods. The start() method executes the Task in a new thread, while the run() method executes the Task in the same thread.

Below is an example of a RetrievableTask and NonRetrievable executing business logic in new threads, and then printing out status messages - based on the designated Task type.

  public class Main{

    private Task retrievable, nonRetrievable;

    public static void main(String[] args){
      retrieveable = new RTask();
      nonRetrievable = new NRTask();

      //start the Retrievable Task
      Thread t = new Thread(retrievable);
      t.start();
      //start the Non-Retrievable Task using an anonymous Thread                   
      new Thread(nonRetrievable).start();

      //Print the results of each respective Task
      System.out.println(retrievable.getVal()); // Since this is a RetrievableTask, retrievable.getVal()
                                                // is blocked until its execute() method has completed.
    }

    private static class RTask extends RetrievableTask<String>{
      @Override
      protected void execute(){
        //do work, execute business logic
        //...    
        this.obj = "Finished with Retrievable task!";
      }
    }

    private static class NRTask extends NonRetrievableTask{
      @Override
      protected void execute(){
        //do work, execute business logic
        //...
        System.out.println("Finished with Non-Retrievable task!");
      }
    } 

  }

Console:

  Thread #2 started...
  Thread #1 started...
  Finished with Retrievable task!
  Finished with Non-Retrievable task!

CBrew

This library contains native facade implementations of the JBrew utility libraries with the Java Native Interface (JNI). This set of libraries features specific optimizations for Unix-based systems in terms of performance and memory. This is achieved through careful tuning using the C programming language to not only control for garbage collection, but also to ensure maximum performance for elected library features.