From e34c73631b43d5685fc462edb3cc138e11d0888a Mon Sep 17 00:00:00 2001 From: Doug Lawrie Date: Wed, 25 Nov 2020 14:59:17 +0000 Subject: [PATCH] Added JavaDoc to jctools-build code generators --- .../JavaParsingAtomicArrayQueueGenerator.java | 9 +++++-- ...JavaParsingAtomicLinkedQueueGenerator.java | 10 +++++--- .../JavaParsingAtomicQueueGenerator.java | 24 +++++++++++++++++-- 3 files changed, 36 insertions(+), 7 deletions(-) diff --git a/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicArrayQueueGenerator.java b/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicArrayQueueGenerator.java index 6a68e1627..7be04017c 100644 --- a/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicArrayQueueGenerator.java +++ b/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicArrayQueueGenerator.java @@ -25,9 +25,14 @@ import com.github.javaparser.ast.type.PrimitiveType; import com.github.javaparser.ast.type.Type; +/** + * This generator takes in an JCTools 'ArrayQueue' Java source file and patches {@link sun.misc.Unsafe} accesses into + * atomic {@link java.util.concurrent.atomic.AtomicLongFieldUpdater}. It outputs a Java source file with these patches. + *

+ * An 'ArrayQueue' is one that is backed by an circular + * array and use a producerLimit and a consumerLimit field to track the positions of each. + */ public final class JavaParsingAtomicArrayQueueGenerator extends JavaParsingAtomicQueueGenerator { - private static final String GEN_DIRECTIVE_CLASS_CONTAINS_ORDERED_FIELD_ACCESSORS = "$gen:ordered-fields"; - private static final String GEN_DIRECTIVE_METHOD_IGNORE = "$gen:ignore"; public static void main(String[] args) throws Exception { main(JavaParsingAtomicArrayQueueGenerator.class, args); diff --git a/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicLinkedQueueGenerator.java b/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicLinkedQueueGenerator.java index 0cae9e698..8842dab1d 100644 --- a/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicLinkedQueueGenerator.java +++ b/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicLinkedQueueGenerator.java @@ -17,7 +17,6 @@ import com.github.javaparser.ast.expr.CastExpr; import com.github.javaparser.ast.expr.ClassExpr; import com.github.javaparser.ast.expr.MethodCallExpr; -import com.github.javaparser.ast.expr.Name; import com.github.javaparser.ast.expr.NameExpr; import com.github.javaparser.ast.expr.ObjectCreationExpr; import com.github.javaparser.ast.expr.StringLiteralExpr; @@ -30,9 +29,14 @@ import com.github.javaparser.ast.type.PrimitiveType; import com.github.javaparser.ast.type.Type; +/** + * This generator takes in an JCTools 'LinkedQueue' Java source file and patches {@link sun.misc.Unsafe} accesses into + * atomic {@link java.util.concurrent.atomic.AtomicLongFieldUpdater}. It outputs a Java source file with these patches. + *

+ * An 'LinkedQueue' is one that is backed by a linked list and use a producerNode and a + * consumerNode field to track the positions of each. + */ public final class JavaParsingAtomicLinkedQueueGenerator extends JavaParsingAtomicQueueGenerator { - private static final String GEN_DIRECTIVE_CLASS_CONTAINS_ORDERED_FIELD_ACCESSORS = "$gen:ordered-fields"; - private static final String GEN_DIRECTIVE_METHOD_IGNORE = "$gen:ignore"; private static final String MPSC_LINKED_ATOMIC_QUEUE_NAME = "MpscLinkedAtomicQueue"; public static void main(String[] args) throws Exception { diff --git a/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicQueueGenerator.java b/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicQueueGenerator.java index 31824a6f2..7a232e471 100644 --- a/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicQueueGenerator.java +++ b/jctools-build/src/main/java/org/jctools/queues/atomic/JavaParsingAtomicQueueGenerator.java @@ -2,8 +2,6 @@ import java.io.File; import java.io.FileWriter; -import java.util.Arrays; -import java.util.EnumSet; import java.util.Optional; import com.github.javaparser.JavaParser; @@ -40,7 +38,29 @@ import com.github.javaparser.ast.type.Type; import com.github.javaparser.ast.visitor.VoidVisitorAdapter; +/** + * Base class of the atomic queue generators. These generators work by parsing a Java source file using + * {@link JavaParser}, and replacing idioms that use {@link sun.misc.Unsafe} to instead use atomic field updates, + * e.g.{@link java.util.concurrent.atomic.AtomicLongFieldUpdater}. They are coupled directly to the structure of the + * expected input Java source file and are used as a utility to maintain unsafe non-portable optimized code along side + * safe portable code for uses such as on Android, etc + *

+ * These generators are coupled with the structure and naming of fields, variables and methods and are not suitable for + * general purpose use. + */ abstract class JavaParsingAtomicQueueGenerator extends VoidVisitorAdapter { + + /** + * When set on a class using a single line comment, the class has fields that have unsafe 'ordered' reads and + * writes. These fields are candidates to be patched by the generator. Other classes the fields remain unadjusted. + */ + protected static final String GEN_DIRECTIVE_CLASS_CONTAINS_ORDERED_FIELD_ACCESSORS = "$gen:ordered-fields"; + + /** + * When set on a method using a single line comment, the method is not patched by the generator. + */ + protected static final String GEN_DIRECTIVE_METHOD_IGNORE = "$gen:ignore"; + protected static final String INDENT_LEVEL = " "; protected final String sourceFileName;