commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From er...@apache.org
Subject [45/50] commons-rng git commit: Userguide.
Date Mon, 21 Nov 2016 17:04:35 GMT
Userguide.


Project: http://git-wip-us.apache.org/repos/asf/commons-rng/repo
Commit: http://git-wip-us.apache.org/repos/asf/commons-rng/commit/6b8bbc0a
Tree: http://git-wip-us.apache.org/repos/asf/commons-rng/tree/6b8bbc0a
Diff: http://git-wip-us.apache.org/repos/asf/commons-rng/diff/6b8bbc0a

Branch: refs/heads/master
Commit: 6b8bbc0a2ac8c40c570619e820d589c78021cfad
Parents: 5cd88b1
Author: Gilles <erans@apache.org>
Authored: Mon Nov 21 14:56:09 2016 +0100
Committer: Gilles <erans@apache.org>
Committed: Mon Nov 21 14:56:09 2016 +0100

----------------------------------------------------------------------
 src/site/apt/userguide/rng.apt                 | 21 +++--
 src/site/apt/userguide/why_not_java_random.apt | 96 ++++++++++++---------
 src/site/xdoc/userguide/index.xml              | 12 +--
 3 files changed, 74 insertions(+), 55 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/commons-rng/blob/6b8bbc0a/src/site/apt/userguide/rng.apt
----------------------------------------------------------------------
diff --git a/src/site/apt/userguide/rng.apt b/src/site/apt/userguide/rng.apt
index eb88e05..201e691 100644
--- a/src/site/apt/userguide/rng.apt
+++ b/src/site/apt/userguide/rng.apt
@@ -29,8 +29,10 @@
   The goal was to provide an API that is simple and unencumbered with old
   design decisions.
 
-  The design is clean and its rationale is explained extensively in the code
-  and Javadoc.
+  The design is clean and its rationale is explained in the code and Javadoc
+  (as well as in the extensive discussions on the "Apache Commons" project's
+  mailing list).
+
   The code evolved during several months in order to accommodate the
   requirements gathered from the design issues identified in the
   <<<org.apache.commons.math3.random>>> package and the explicit design
@@ -252,7 +254,8 @@ rngNew.restoreState(stateNew);
 +--------------------------+
 
 
-  * Generation of random deviates for various distributions.
+  * Generation of random deviates for various
+    {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/package-summary.html}distributions}}.
 
 +--------------------------+
 import org.apache.commons.rng.sampling.distribution.ContinuousSampler;
@@ -272,7 +275,9 @@ DiscreteSampler sampler = new RejectionInversionZipfSampler(RandomSource.create(
 int random = sampler.sample();
 +--------------------------+
 
-  * Permutation, sampling from a <<<Collection>>> and shuffling utilities.
+  * {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/PermutationSampler.html}Permutation}},
+    {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/CollectionSampler.html}sampling
from a <<<Collection>>>}}
+    and shuffling utilities.
 
 +--------------------------+
 import org.apache.commons.rng.sampling.PermutationSampler;
@@ -288,13 +293,13 @@ int[] random = sampler.sample();
 import java.util.ArrayList;
 import org.apache.commons.rng.sampling.CollectionSampler;
 
-ArrayList<String> list = new ArrayList<>();
-list.add("Apache")
+ArrayList<String> list = new ArrayList<String>();
+list.add("Apache");
 list.add("Commons");
 list.add("RNG");
 
-CollectionSampler sampler = new CollectionSampler(RandomSource.create(RandomSource.MWC_256),
-                                                  list, 1);
+CollectionSampler<String> sampler = new CollectionSampler<String>(RandomSource.create(RandomSource.MWC_256),
+                                                                  list, 1);
 String word = sampler.sample().get(0);
 +--------------------------+
 

http://git-wip-us.apache.org/repos/asf/commons-rng/blob/6b8bbc0a/src/site/apt/userguide/why_not_java_random.apt
----------------------------------------------------------------------
diff --git a/src/site/apt/userguide/why_not_java_random.apt b/src/site/apt/userguide/why_not_java_random.apt
index 5f2b190..5e82e34 100644
--- a/src/site/apt/userguide/why_not_java_random.apt
+++ b/src/site/apt/userguide/why_not_java_random.apt
@@ -19,68 +19,82 @@
   Why not <<<java.util.Random>>> ?
   -----------------------------
 
-The "Apache Commons RNG" project started off from code originally in the
-"Apache Commons Math" project; there, the code in package
-{{{http://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/random/package-summary.html}org.apache.commons.math3.random}}
-had its design prominently based on the JDK's
-{{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html}Random}}
-class.
+  The "Apache Commons RNG" project started off from code originally in the
+  "Apache Commons Math" project; there, the code in package
+  {{{http://commons.apache.org/proper/commons-math/javadocs/api-3.6.1/org/apache/commons/math3/random/package-summary.html}org.apache.commons.math3.random}}
+  had its design prominently based on the JDK's
+  {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html}Random}}
+  class.
 
-Although it is often a good idea to rely on the language's standard library,
-sometimes it is not.
-And, in this case, there are numerous reasons for avoiding <<<java.util.Random>>>.
+  Although it is often a good idea to rely on the language's standard library,
+  sometimes it is not.
 
-1. The {{{https://en.wikipedia.org/wiki/Linear_congruential_generator}LCG}}
-   algorithm used by <<<java.util.Random>>>
+  * The {{{https://en.wikipedia.org/wiki/Linear_congruential_generator}LCG}}
+    algorithm used by <<<java.util.Random>>>
 
-   * has a serious {{{http://www.ics.uci.edu/~fowlkes/class/cs177/marsaglia.pdf}defect}},
and
+      ** has a serious {{{http://www.ics.uci.edu/~fowlkes/class/cs177/marsaglia.pdf}defect}},
and
 
-   * is not as efficient as some of the alternatives that do not suffer from this problem.
+      ** is not as efficient as some of the alternatives that do not suffer from this problem.
 
-   []
+      []
 
 
-2. Although the {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#next(int)}next}}
-   method seems to imply that it is designed for inheritance, it is not quite so:
+  * Although the {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#next(int)}next}}
+    method seems to imply that it is designed for inheritance, it is not quite so:
 
-   * {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#setSeed(long)}setSeed}}
-     is tied to the assumption that the state of the generator is entirely
-     defined by a single <<<long>>> value.
+      ** {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#setSeed(long)}setSeed}}
+         is tied to the assumption that the state of the generator is entirely
+         defined by a single <<<long>>> value.
 
-   * {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#next(int)}next}}
-     implies that an implementation must produce a 32-bits value.
+      ** {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#next(int)}next}}
+         implies that an implementation must produce a 32-bits value.
 
-   * <<<Random>>> is {{{http://docs.oracle.com/javase/7/docs/api/java/io/Serializable.html}Serializable}}
-     and thus imposes it on subclasses even though the issue of persistent
-     storage is application-dependent.
+      ** <<<Random>>> is {{{http://docs.oracle.com/javase/7/docs/api/java/io/Serializable.html}Serializable}}
+         and thus imposes it on subclasses even though the issue of persistent
+         storage is application-dependent.
 
-   []
+      []
 
 
    As a side note, the newer
    {{{https://docs.oracle.com/javase/8/docs/api/java/util/SplittableRandom.html}SplittableRandom}}
 
-   * is <<<final>>> (hence, there is no temptation to mistake it as an
interface), and
+     ** is <<<final>>> (hence, there is no temptation to mistake it as
an interface), and
 
-   * does not inherit from <<<Random>>> (which is a clear hint that the
-     JDK's developers themselves do not consider <<<Random>>> as the
-     best option for new code).
+     ** does not inherit from <<<Random>>> (which is a clear hint that
the
+        JDK's developers themselves do not consider <<<Random>>> as the
+        best option for new code).
 
-   []
+     []
 
 
-3. Thus, <<<java.util.Random>>> _should_ have been an implementation of
a
-   more general interface (without a <<<setSeed>>> method that is bound
to
-   be implementation-specific, or a {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#nextGaussian()}nextGaussian}}
-   that singles out just one of many types of random deviates).
+  * Thus, <<<java.util.Random>>> _should_ have been an implementation of
a
+    more general interface (without a <<<setSeed>>> method that is bound
to
+    be implementation-specific, or a {{{https://docs.oracle.com/javase/7/docs/api/java/util/Random.html#nextGaussian()}nextGaussian}}
+    that singles out just one of many types of random deviates).
 
 
-4. As a concrete class, <<<java.util.Random>>> contains code tied to
-   "implementation details"; it is hard to modify it without changing
-   long-established behaviour, even if it would be to fix a
-   {{{https://bugs.openjdk.java.net/browse/JDK-8154225}bug}}.
+  * As a concrete class, <<<java.util.Random>>> contains code tied to
+    "implementation details"; it is hard to modify it without changing
+    long-established behaviour, even if it would be to fix a
+    {{{https://bugs.openjdk.java.net/browse/JDK-8154225}bug}}.
 
 
-5. Methods are <<<synchronized>>>, incurring an unnecessary  performance
-   impact for single-threaded applications, while multi-threaded ones will
-   be subject to contention.
+  * Methods are <<<synchronized>>>, incurring an unnecessary  performance
+    impact for single-threaded applications, while multi-threaded ones will
+    be subject to contention.
+
+  []
+
+
+  Unless unfazed by the above, it is clear that application developers should
+  avoid <<<java.util.Random>>>, as a generator, and as a base class.
+
+  For new applications, it is recommended to switch to any of the better
+  alternatives provided in "Commons RNG".
+
+  For legacy applications where the <<<java.util.Random>>> type is part
of
+  an API that cannot be changed, developers can wrap any of the generators
+  implemented in this library within an instance of the
+  {{{../commons-rng-simple/apidocs/org/apache/commons/rng/simple/JDKRandomBridge.html}JDKRandomBridge}}
+  adapter class.

http://git-wip-us.apache.org/repos/asf/commons-rng/blob/6b8bbc0a/src/site/xdoc/userguide/index.xml
----------------------------------------------------------------------
diff --git a/src/site/xdoc/userguide/index.xml b/src/site/xdoc/userguide/index.xml
index 027abbb..ef0f9be 100644
--- a/src/site/xdoc/userguide/index.xml
+++ b/src/site/xdoc/userguide/index.xml
@@ -30,27 +30,27 @@
 
         <li>
           <a href="rng.html#a1._Purpose">
-          1. Usage overview (for users)</a>
+          1. Purpose of the library</a>
         </li>
         <li>
           <a href="rng.html#a2._Usage_overview">
-          1. Usage overview (for users)</a>
+          2. Usage overview (for users)</a>
         </li>
         <li>
           <a href="rng.html#a3._Library_layout">
-          2. Library layout (for developers)</a>
+          3. Library layout (for developers)</a>
         </li>
         <li>
           <a href="rng.html#a4._Performance">
-          3. Performance</a>
+          4. Performance</a>
         </li>
         <li>
           <a href="rng.html#a5._Quality">
-          4. Quality</a>
+          5. Quality</a>
         </li>
         <li>
           <a href="rng.html#a6._Dependencies">
-          5. Dependencies</a>
+          6. Dependencies</a>
         </li>
       </ul>
 


Mime
View raw message