changeset 342:50ec2fc74cd1

Clean up annotation API Javadoc.
author shade
date Thu, 19 Jan 2017 12:03:48 +0100
parents 0de8079ec104
children 008942d79b4a
files jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Actor.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Arbiter.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Description.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Expect.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressMeta.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressTest.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Mode.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Outcome.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Result.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Signal.java jcstress-core/src/main/java/org/openjdk/jcstress/annotations/State.java
diffstat 11 files changed, 111 insertions(+), 59 deletions(-) [+]
line wrap: on
line diff
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Actor.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Actor.java	Thu Jan 19 12:03:48 2017 +0100
@@ -30,20 +30,22 @@
 import java.lang.annotation.Target;
 
 /**
- * Actors actively mutate the states and may produce results.
- * <p/>
- * Actor-annotated methods can have only the {@link State} or {@link Result}-annotated
- * classes as the parameters.
- * <p/>
- * Actor methods may declare to throw the exceptions, but the behavior
- * after actually throwing an exception is undefined.
- * <p/>
- * A few important invariants are maintained:
- *   - the method is called only by single actor thread, once per {@link State} instance;
- *   - for any given {@link State}, the order vs another actors is deliberately unspecified;
- *   - any given {@link State} instance will be eventually visited by all actors;
+ * {@link Actor} is the central test annotation. It marks the methods that hold the
+ * actions done by the threads. The invariants that are maintained by the infrastructure
+ * are as follows:
  *
- * @author Aleksey Shipilev (aleksey.shipilev@oracle.com)
+ * <ol>
+ *     <li>Each method is called only by one particular thread.</li>
+ *     <li>Each method is called exactly once per {@link State} instance.</li>
+ * </ol>
+ *
+ * <p>Note that the invocation order against other {@link Actor} methods is deliberately
+ * not specified. Therefore, two or more {@link Actor} methods may be used to model
+ * the concurrent execution on data held by {@link State} instance.
+ *
+ * <p>Actor-annotated methods can have only the {@link State} or {@link Result}-annotated
+ * classes as the parameters. Actor methods may declare to throw the exceptions, but
+ * actually throwing the exception would fail the test.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Arbiter.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Arbiter.java	Thu Jan 19 12:03:48 2017 +0100
@@ -30,17 +30,15 @@
 import java.lang.annotation.Target;
 
 /**
- * Arbiters are similar {@link Actor}, but with a few important differences:
- *  - arbiter visits the {@link State} instance after all the actors have already visited that instance;
- *  - all memory effects from actors are visible in arbiter;
- * <p/>
- * Arbiter methods may declare to throw the exceptions, but the behavior
- * after actually throwing an exception is undefined.
- * <p/>
- * Arbiter-annotated methods can have only the {@link State} or {@link Result}-annotated
- * classes as the parameters.
- * <p/>
- * @author Aleksey Shipilev (aleksey.shipilev@oracle.com)
+ * {@link Arbiter} is similar to {@link Actor}, but there is one critical difference:
+ * Arbiter visits the {@link State} instance after all the {@link Actor}s
+ * have already visited that instance. All memory effects from {@link Actor}s are
+ * visible in Arbiter. This makes arbiter useful for reading the final state into
+ * results.
+ *
+ * <p>Arbiter-annotated methods can have only the {@link State} or {@link Result}-annotated
+ * classes as the parameters. Arbiter methods may declare to throw the exceptions, but
+ * actually throwing the exception would fail the test.
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Description.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Description.java	Thu Jan 19 12:03:48 2017 +0100
@@ -31,7 +31,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Test description.
+ * {@link Description} defines a human-readable test description.
  */
 @Inherited
 @Target(ElementType.TYPE)
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Expect.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Expect.java	Thu Jan 19 12:03:48 2017 +0100
@@ -25,32 +25,33 @@
 package org.openjdk.jcstress.annotations;
 
 /**
- * Provides the grading for the {@link Outcome}.
+ * {@link Expect} provides the grading for the {@link Outcome}.
  */
 public enum Expect {
 
     /**
-     * May be present as the valid result; may be absent if tests haven't been able to reach to that outcome.
+     * Acceptable result. Acceptable results are not required to be present.
      */
     ACCEPTABLE,
 
     /**
-     * Same as ACCEPTABLE, but this outcome will be highlighted in reports.
+     * Same as {@link #ACCEPTABLE}, but this result will be highlighted in reports.
      */
     ACCEPTABLE_INTERESTING,
 
     /**
-     * Same as ACCEPTABLE, but only for outcomes which are formally acceptable, but may be surprising to end users.
+     * Same as {@link #ACCEPTABLE}, but this result is only formally acceptable, and may be surprising to end users.
+     * TODO: Fold this with ACCEPTABLE_INTERESTING
      */
     ACCEPTABLE_SPEC,
 
     /**
-     * Should always be absent.
+     * Forbidden result. Should never be present.
      */
     FORBIDDEN,
 
     /**
-     * Internal: no grading.
+     * Internal expectation: no grading. Do not use.
      */
     UNKNOWN,
 }
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressMeta.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressMeta.java	Thu Jan 19 12:03:48 2017 +0100
@@ -30,7 +30,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Points to another class with test meta-information.
+ * {@link JCStressMeta} points to another class with test meta-information.
  *
  * <p>When placed over {@link JCStressTest} class, the {@link Description}, {@link Outcome},
  * {@link Ref}, and other annotations will be inherited from the pointed class. This allows
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressTest.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/JCStressTest.java	Thu Jan 19 12:03:48 2017 +0100
@@ -30,13 +30,12 @@
 import java.lang.annotation.Target;
 
 /**
- * Marks the class that should be treated as the concurrency stress test.
- * <p/>
- * {@link Actor} and {@link Arbiter} annotations are used to describe test
- * behavior. {@link State} and {@link Result} annotations are used to
- * describe the test state.
- * <p/>
- * The grading for test is done with {@link Outcome} annotations.
+ * {@link JCStressTest} marks the class that should be as the concurrency stress
+ * test. {@link Actor} and {@link Arbiter} annotations are used to describe test
+ * behavior. {@link State} and {@link Result} annotations are used to describe
+ * the test state and results.
+ *
+ * <p>The grading for test is done with {@link Outcome} annotations.
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Mode.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Mode.java	Thu Jan 19 12:03:48 2017 +0100
@@ -24,9 +24,21 @@
  */
 package org.openjdk.jcstress.annotations;
 
+/**
+ * JCStress test mode.
+ */
 public enum Mode {
 
+    /**
+     * Continuous mode: run several {@link Actor}, {@link Arbiter} threads, and
+     * collect the histogram of {@link Result}s.
+     */
     Continuous,
+
+    /**
+     * Termination mode: run a single {@link Actor} with a blocking/looping operation,
+     * and see if it responds to a {@link Signal}.
+     */
     Termination,
 
 }
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Outcome.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Outcome.java	Thu Jan 19 12:03:48 2017 +0100
@@ -32,9 +32,24 @@
 import java.lang.annotation.Target;
 
 /**
- * Describes the test outcome.
+ * {@link Outcome} describes the test outcome, and how to deal with it.
+ * It is usually the case that a {@link JCStressTest} has multiple outcomes,
+ * each with its distinct {@link #id()}.
  *
- * <p>Multiple outcomes with distinct IDs can be provided.</p>
+ * <p>{@link #id()} is cross-matched with {@link Result}-class' {@link #toString()}
+ * value. {@link #id()} allows regular expressions. For example, this outcome
+ * captures all results where there is a trailing "1":
+ *
+ * <pre>{@code
+ *     \@Outcome(id = ".*, 1", ...)
+ * }</pre>
+ *
+ * <p>When there is no ambiguity in what outcome should match the result, the
+ * annotation order is irrelevant. When there is an ambiguity, the first outcome
+ * in the declaration order is matched.
+ *
+ * <p>There can be a default outcome, which captures any non-captured result.
+ * It is the one with the default {@link #id()}.
  */
 @Inherited
 @Target(ElementType.TYPE)
@@ -43,19 +58,19 @@
 public @interface Outcome {
 
     /**
-     * @return observed outcome; empty string or no parameter if the case is default.
-     * ID support regular expressions.
+     * @return Observed result. Empty string or no parameter if the case is default.
+     * Supports regular expressions.
      */
     String[] id() default { "" };
 
     /**
-     * @return expect type for the observed outcome
+     * @return Expectation for the observed result.
      * @see Expect
      */
     Expect expect();
 
     /**
-     * @return human-readable description for a given outcome
+     * @return Human-readable description for a given result.
      */
     String desc() default "";
 
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Result.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Result.java	Thu Jan 19 12:03:48 2017 +0100
@@ -30,14 +30,26 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotates the class that is treated as the result object.
- * <p/>
- * Important invariants:
- *   - Result classes usually mimic value types: they do not have identity, and harness
- *     may reuse the objects, and also auto-magically clear the fields;
- *   - All fields in Result classes should be public;
- *   - All fields in Result classes should be primitive, or String;
- *   - Result classes should be serializable;
+ * {@link Result} annotation marks the result object. This annotation is seldom
+ * useful for user code, because jcstress ships lots of pre-canned result classes,
+ * see {@link org.openjdk.jcstress.infra.results} package.
+ *
+ * <p/>Important invariants and properties:
+ * <ol>
+ *     <li>All fields in {@link Result} classes should be public.</li>
+ *     <li>All fields in {@link Result} classes shoudl be either primitive, or String.</li>
+ *     <li>{@link Result} classes should be serializable.</li>
+ *     <li>{@link Result} classes should have proper {@link #equals(Object)} and {@link #hashCode()}
+ *     methods to disambiguate one result from another.</li>
+ *     <li>{@link Result} classes should have unique {@link #toString()} representation,
+ *     because it is being matched with {@link Outcome#id()}, and also serves
+ *     as key to separate one result from another in the output log.
+ *     (This might be revisited in future releases of jcstress).</li>
+ *     <li>{@link Result} classes mimic value types. They do not have identity,
+ *     and jcstress may reuse the objects, auto-magically clear the result fields,
+ *     etc. It is not advisable to have auxiliary fields and methods in {@link Result}
+ *     class, because its state is managed by jcstress.</li>
+ * </ol>
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Signal.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/Signal.java	Thu Jan 19 12:03:48 2017 +0100
@@ -29,6 +29,11 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * {@link Signal} is useful for delivering a termination signal to {@link Actor}
+ * in {@link Mode#Termination} tests. It will run after {@link Actor} in question
+ * started executing.
+ */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Signal {
--- a/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/State.java	Wed Jan 04 12:24:51 2017 +0100
+++ b/jcstress-core/src/main/java/org/openjdk/jcstress/annotations/State.java	Thu Jan 19 12:03:48 2017 +0100
@@ -30,12 +30,20 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotates the class treated as test state.
- * <p/>
- * Important invariants:
- *   - State classes should have a default constructor;
- *   - All initializations in constructors and instance initializers are
- *     visible to all actors;
+ * {@link State} is the central annotation for handling test state.
+ * It annotates the class that holds the data mutated/read by the tests.
+ *
+ * <p>Important properties for the class are:
+ * <ol>
+ *     <li>State class should be public, non-inner class.</li>
+ *     <li>State class should have a default constructor.</li>
+ * </ol>
+ *
+ * <p>During the run, many {@link State} instances are created, and therefore
+ * the tests should try to minimize state instance footprint.
+ *
+ * <p>All actions in constructors and instance initializers are visible
+ * to all {@link Actor} and {@link Arbiter} threads.
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)