Initial implementation of ContinuationLocal

README.md

@@ -1,2 +1,46 @@
 # continuation-local-storage-jvm
-A common JVM implementation of continuation-local storage
+
+This is a common implementation of continuation-local storage for the JVM.
+It is based on Twitter's [`com.twitter.util.Local`](https://github.com/twitter/util/blob/master/util-core/src/main/scala/com/twitter/util/Local.scala), but this is a Java port
+without any external dependencies (notably; no dependency on Scala).
+
+The ContinuationLocal can be used for any data that should be persisted in
+a continuation scope, but is especially useful for various monitoring and tracing
+implementations.
+
+## Usage example
+
+```java
+import com.github.distributedtracing.ContinuationLocal;
+
+public final class MyProgram {
+    private static final ContinuationLocal<Integer> userId
+      = new ContinuationLocal<Integer>();
+
+    public static void main(String[] args) {
+        userId.set(123);
+        printUserId();
+    }
+
+    private static void printUserId() {
+        System.out.println(userId.get());
+    }
+}
+```
+
+## Design differences between com.twitter.util.Local and ContinuationLocal:
+
+- The value of `com.twitter.util.Local<T>` is of type `scala.Option<T>`,
+  where `Some(value)` holds the value, while `None` indicates that the
+  value is absent. In `com.github.distributedtracing.ContinuationLocal<T>`,
+  the value is not an Option, instead being a nullable of type `T`.
+- In `com.twitter.util.Local` the inner storage mechanism is a `ThreadLocal`,
+  while in `ContinuationLocal`, it is a `InheritableThreadLocal`. This means
+  that a value that would not be passed on in `com.twitter.util.Local` will be
+  in a `ContinuationLocal`, in case a new thread is started in the same
+  context as the `ContinuationLocal` was set.
+- `com.twitter.util.Local`'s `update` method is not included. The similar
+  method `set` should instead be used. `update` in `c.t.u.Local` uses `Option`
+  types, while `set` in `ContinuationLocal` deals with nullable values directly.
+- `com.twitter.util.Local`'s (static) `letClear` function has been renamed to
+  `letAllClear` to avoid a naming collision with the non-static method `letClear`.

pom.xml

@@ -0,0 +1,92 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.sonatype.oss</groupId>
+        <artifactId>oss-parent</artifactId>
+        <version>7</version>
+    </parent>
+
+    <properties>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <groupId>com.github.distributedtracing</groupId>
+    <artifactId>continuation-local-storage</artifactId>
+    <version>1.0-SNAPSHOT</version>
+    <packaging>jar</packaging>
+
+    <name>continuation-local-storage</name>
+    <url>https://github.com/DistributedTracing/continuation-local-storage-jvm</url>
+
+    <description>
+        This is a Java port of Twitter's com.twitter.util.Local. The purpose of
+        ContinuationLocal is to be able to pass state implicitly between continuations;
+        much like a ThreadLocal, but one that also works in thread pools and event loops.
+    </description>
+
+    <licenses>
+        <license>
+            <name>The Apache Software License, Version 2.0</name>
+            <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
+            <distribution>repo</distribution>
+        </license>
+    </licenses>
+
+    <developers>
+        <developer>
+            <id>eirslett</id>
+            <name>Eirik Sletteberg</name>
+            <email>[email protected]</email>
+        </developer>
+    </developers>
+
+    <dependencies>
+        <dependency>
+            <groupId>junit</groupId>
+            <artifactId>junit</artifactId>
+            <version>4.12</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>animal-sniffer-maven-plugin</artifactId>
+                <version>1.14</version>
+                <executions>
+                    <execution>
+                        <phase>test</phase>
+                        <goals>
+                            <goal>check</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <signature>
+                        <groupId>org.codehaus.mojo.signature</groupId>
+                        <artifactId>java16</artifactId>
+                        <version>1.1</version>
+                    </signature>
+                </configuration>
+            </plugin>
+        </plugins>
+
+        <pluginManagement>
+            <plugins>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-compiler-plugin</artifactId>
+                    <version>3.1</version>
+                    <configuration>
+                        <source>1.6</source>
+                        <target>1.6</target>
+                    </configuration>
+                </plugin>
+            </plugins>
+        </pluginManagement>
+    </build>
+</project>

src/main/java/com/github/distributedtracing/ContinuationLocal.java

@@ -0,0 +1,170 @@
+package com.github.distributedtracing;
+
+public final class ContinuationLocal<T> {
+    private static InheritableThreadLocal<Object[]> localCtx =
+            new InheritableThreadLocal<Object[]>();
+    private static volatile int size = 0;
+
+    /**
+     * Return a snapshot of the current ContinuationLocal state.
+     */
+    public static Object[] save() {
+        return localCtx.get();
+    }
+
+    /**
+     * Restore the ContinuationLocal state to a given set of values.
+     */
+    public static void restore(Object[] saved) {
+        localCtx.set(saved);
+    }
+
+    private static synchronized int add() {
+        size += 1;
+        return size - 1;
+    }
+
+    private static void set(int i, Object v) {
+        assert i < size;
+        Object[] ctx = localCtx.get();
+
+        if(ctx == null) {
+            ctx = new Object[size];
+        } else {
+            Object[] oldCtx = ctx;
+            ctx = new Object[size];
+            System.arraycopy(oldCtx, 0, ctx, 0, oldCtx.length);
+        }
+
+        ctx[i] = v;
+        localCtx.set(ctx);
+    }
+
+    private static Object get(int i) {
+        Object[] ctx = localCtx.get();
+        if(ctx == null || ctx.length <= i) {
+            return null;
+        }
+
+        return ctx[i];
+    }
+
+    private static void clear(int i) {
+        set(i, null);
+    }
+
+    /**
+     * Clear all locals in the current context.
+     */
+    private static void clearAll() {
+        localCtx.set(null);
+    }
+
+    /**
+     * Execute a block with the given ContinuationLocals,
+     * restoring current values upon completion.
+     */
+    public static <U> U let(Object[] ctx, Producer<U> f) {
+        Object[] saved = save();
+        restore(ctx);
+        U result;
+        try {
+            result = f.apply();
+        } finally {
+            restore(saved);
+        }
+        return result;
+    }
+
+    /**
+     * Execute a block with all ContinuationLocals clear, restoring
+     * current values upon completion.
+     */
+    public static <U> U letAllClear(Producer<U> f) {
+        return ContinuationLocal.let(null, f);
+    }
+
+    /**
+     * Convert a Producer&lt;R&gt; into another producer of the same
+     * type whose ContinuationLocal context is saved when calling `closed`
+     * and restored upon invocation.
+     */
+    public static <R> Producer<R> closed(final Producer<R> fn) {
+        final Object[] closure = ContinuationLocal.save();
+        return new Producer<R>() {
+            public R apply() {
+                Object[] save = ContinuationLocal.save();
+                ContinuationLocal.restore(closure);
+                R result;
+                try {
+                    result = fn.apply();
+                } finally {
+                    ContinuationLocal.restore(save);
+                }
+                return result;
+            }
+        };
+    }
+
+    private final int me = add();
+
+    /**
+     * Update the ContinuationLocal with the given value.
+     */
+    public void set(T value) {
+        set(me, value);
+    }
+
+    /**
+     * Get the ContinuationLocal's value.
+     */
+    public T get() {
+        return (T)get(me);
+    }
+
+    /**
+     * Alias for get()
+     */
+    public T apply() {
+        return get();
+    }
+
+    /**
+     * Execute a block with a specific ContinuationLocal value,
+     * restoring the current state upon completion.
+     */
+    public <U> U let(T value, Producer<U> f) {
+        T saved = get();
+        set(value);
+        U result;
+        try {
+            result = f.apply();
+        } finally {
+            set(saved);
+        }
+        return result;
+    }
+
+    /**
+     * Execute a block with the ContinuationLocal cleared, restoring
+     * the current state upon completion.
+     */
+    public <U> U letClear(Producer<U> f) {
+        T saved = get();
+        clear();
+        U result;
+        try {
+            result = f.apply();
+        } finally {
+            set(saved);
+        }
+        return result;
+    }
+
+    /**
+     * Clear the ContinuationLocal's value. Other ContinuationLocal's are not modified.
+     */
+    public void clear() {
+        ContinuationLocal.clear(me);
+    }
+}