<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC
    "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
    "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
<html xml:lang='en' xmlns:svg='http://www.w3.org/2000/svg' xmlns='http://www.w3.org/1999/xhtml'>
<head><meta content='application/xhtml+xml;charset=utf-8' http-equiv='Content-type' /><title>std::rand replacement, revision 1</title></head>
<body><!-- maruku -o randint.html randint.md --><style type='text/css'>
pre code { display: block; margin-left: 2em; }
div { display: block; margin-left: 2em; }
ins { text-decoration: none; font-weight: bold; background-color: #A0FFA0 }
del { text-decoration: line-through; background-color: #FFA0A0 }
</style><table><tbody>
<tr><th>Doc. no.:</th>	<td>N4217</td></tr>
<tr><th>Date:</th>	<td>2014-10-08</td></tr>
<tr><th>Project:</th>	<td>Programming Language C++, SG6: Numerics</td></tr>
<tr><th>Reply-to:</th>	<td>Zhihao Yuan &lt;zy at miator dot net&gt;</td></tr>
</tbody></table>
<h1 id='stdrand_replacement_revision_1'>std::rand replacement, revision 1</h1>

<h2 id='changes_since_n3796'>Changes since N3796</h2>

<ul>
<li>Seeding utility <code>seed_init</code> based on SG6&#8217;s preference.</li>

<li>Variants for <code>std::shuffle</code> and <code>std::experimental::sample</code>.</li>

<li>Naming candidate <code>rand_int</code>.</li>

<li>Some outdated discussions are removed.</li>
</ul>

<h2 id='motivation'>Motivation</h2>

<p>We want to deprecate the <code>std::rand</code> friends, while &#8220;deprecation without a replacement&#8221; is a valid concern. This paper</p>

<ol>
<li>
<p>Proposes replacement to the <code>std::rand</code> friends. Despite of the security issues, <code>std::rand</code> is considered both handy and useful as a global uniform random number generator.</p>
</li>

<li>
<p>Exposes the most widely-used combo in C++11 <code>&lt;random&gt;</code> without pushing the users to learn the whole design. Smoothing the learning curve can usually optimize the acceptance.</p>
</li>
</ol>

<h2 id='design_decisions'>Design Decisions</h2>

<p><code>std::rand</code> is a self-contained interface, so its replacement should be independent as well. In addition, I expect the interface to correctly expose the functionalities of <code>&lt;random&gt;</code> and lead to more robust and secure programs. The proposed replacement is</p>

<ul>
<li>
<p>Distribution based. RNG must be used with a distribution; <code>std::rand</code> is a wrong design.</p>
</li>

<li>
<p>Randomly seeded before being used. Improper seeding, <code>rand(time(0))</code> for instance, results in vulnerabilities.</p>
</li>

<li>
<p>Per-thread engine. Minimal interface should minimize astonishment, wrt. thread-safety and performance.</p>
</li>

<li>
<p>Manually seedable. User can observe repeatability in a given thread, which is a typical demand for debugging.</p>
</li>

<li>
<p>Type-safe. No integral promotion. For a given invocation, the inputs and the result have the same type.</p>
</li>
</ul>

<p>Two variants for the shuffling and sampling algorithms without the explicit <code>URNG</code> parameter are also proposed.</p>

<h2 id='example'>Example</h2>

<pre><code>std::randint(0, 6);  // randomly seeded

// in another thread
std::seed_init();    // default_seed
std::shuffle(begin(v), end(v));</code></pre>

<h2 id='wording'>Wording</h2>

<p>Change 26.5.2 rand.synopsis:</p>

<pre><code>namespace std {</code></pre>

<blockquote>
<p>&#8230;</p>
</blockquote>

<pre><code> // 26.5.7.2, function template generate_canonical
 template&lt;class RealType, size_t bits, class URNG&gt;
   RealType generate_canonical(URNG&amp; g);</code></pre>
<div><ins>
<tt>// 26.5.7.3, function template randint</tt><br />
<tt>template&lt;class IntType&gt;</tt><br />
<tt>&nbsp;&nbsp;IntType randint(IntType a, IntType b);</tt><br />
</ins></div><br /><div><ins>
<tt>// 26.5.7.4, seeding the per-thread engine</tt><br />
<tt>void seed_init();</tt><br />
<tt>void seed_init(default_random_engine::result_type value);</tt><br />
</ins></div>
<pre><code> // 26.5.8.2.1, class template uniform_int_distribution
 template&lt;class IntType = int&gt;
   class uniform_int_distribution;</code></pre>

<blockquote>
<p>&#8230;</p>
</blockquote>

<pre><code>} // namespace std</code></pre>

<p>New section 26.5.7.3 rand.util.randint:</p>

<blockquote>
<h4 id='26573_function_template_'>26.5.7.3 function template <code>randint</code></h4>
</blockquote>

<blockquote>
<p>All functions instantiated from the template described in this section share the same <code>default_random_engine</code> for a given execution of a thread; the random engine is non-deterministically seeded during the initialization if no call to any function described in section 26.5.7.4 in the same thread is sequenced before the random engine generating the first result. Such a random engine shall be maintained separately for each thread. <em>[Note: The call expressions from different threads shall not be able to observe the same pseudo random number sequence in a deterministic way. &#8211;end note]</em></p>
</blockquote>

<pre><code>template&lt;class IntType&gt;
  IntType randint(IntType a, IntType b);</code></pre>

<blockquote>
<p><em>Requires:</em> <code>a</code> <em>&#8804;</em> <code>b</code></p>

<p><em>Effects:</em> Produce a random integer <em>i</em>, <em>a &#8804; i &#8804; b</em>, from a <code>uniform_int_distribution&lt;IntType&gt;</code> (26.5.8.2.1).</p>

<p><em>Returns:</em> <em>i</em>.</p>
</blockquote>

<p>New section 26.5.7.4 rand.util.seed_init:</p>

<blockquote>
<h4 id='26574_seeding_the_perthread_engine'>26.5.7.4 seeding the per-thread engine</h4>
</blockquote>

<pre><code>void seed_init();
void seed_init(default_random_engine::result_type value);</code></pre>

<blockquote>
<p><em>Requires:</em> The random engine defined in section 26.5.7.3 in the same thread has not been seeded.</p>

<p><em>Effects:</em> The first form seeds the engine with <code>default_random_engine::default_seed</code>. The second form seeds the engine with <code>value</code>.</p>
</blockquote>

<p>Change 25.1 algorithms.general:</p>

<blockquote>
<h3 id='header__synopsis'>Header <code>&lt;algorithm&gt;</code> synopsis</h3>

<p>&#8230;</p>
</blockquote>

<pre><code> // 25.3.12, shuffle:</code></pre>
<div><ins>
<tt>template&lt;class RandomAccessIterator&gt;</tt><br />
<tt>&nbsp;&nbsp;void shuffle(RandomAccessIterator first,
RandomAccessIterator last);</tt>
</ins></div>
<pre><code> template&lt;class RandomAccessIterator, class UniformRandomNumberGenerator&gt;
   void shuffle(RandomAccessIterator first,
                RandomAccessIterator last,
                UniformRandomNumberGenerator&amp;&amp; g);</code></pre>

<p>Change 25.3.12 alg.random.shuffle:</p>
<div><ins>
<tt>template&lt;class RandomAccessIterator&gt;</tt><br />
<tt>&nbsp;&nbsp;void shuffle(RandomAccessIterator first,
RandomAccessIterator last);</tt>
</ins></div>
<pre><code> template&lt;class RandomAccessIterator, class UniformRandomNumberGenerator&gt;
   void shuffle(RandomAccessIterator first,
                RandomAccessIterator last,
                UniformRandomNumberGenerator&amp;&amp; g);</code></pre>

<blockquote>
<p>&#8230;</p>

<p><em>Remarks:</em> To the extent that the implementation of this function makes use of random numbers, the object <code>g</code> shall serve as the implementation&#8217;s source of randomness<ins> in the second form, so does the random engine
defined in section 26.5.7.3 in the same thread for the first form</ins>.</p>
</blockquote>

<p>The following wording is relative to N4082 fund.ts.</p>

<p>Change 10.3 alg.random.sample:</p>
<div><ins>
<tt>template&lt;class PopulationIterator, class SampleIterator,
class Distance&gt;</tt><br />
<tt>SampleIterator sample(PopulationIterator first, PopulationIterator
last,</tt><br />
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SampleIterator
out, Distance n);</tt>
</ins></div>
<pre><code> template&lt;class PopulationIterator, class SampleIterator,
          class Distance, class UniformRandomNumberGenerator&gt;
 SampleIterator sample(PopulationIterator first, PopulationIterator last,
                       SampleIterator out, Distance n,
                       UniformRandomNumberGenerator&amp;&amp; g);</code></pre>

<blockquote>
<p>&#8230;</p>

<p><em>Remarks:</em></p>

<ul>
<li>Stable if and only if <code>PopulationIterator</code> meets the requirements of a <code>ForwardIterator</code> type.</li>

<li>To the extent that the implementation of this function makes use of random numbers, the object <code>g</code> shall serve as the implementation&#8217;s source of randomness<ins> in the second form, so does the random engine
defined in section 26.5.7.3 in the same thread for the first form</ins>.</li>
</ul>
</blockquote>

<h2 id='sample_implementation'>Sample Implementation</h2>

<p>A sample implementation is available at <a href='https://github.com/lichray/randint'>https://github.com/lichray/randint</a>.</p>

<h2 id='bikeshedding'>Bikeshedding</h2>

<p>First of all, overloading <code>std::rand</code> is not an option. User may deem <code>std::rand()</code> as a &#8220;safe&#8221; variant to the new interface.</p>

<p>Collected so far:</p>

<ul>
<li><code>randint</code>, from Python<code>[2]</code></li>

<li><code>rand_int</code>, by Nicolai and Andy Sawyer</li>

<li><code>random_int</code>, by STL</li>

<li><code>pick_int</code>, by me, inspired by WEB<code>[1]</code></li>

<li><code>randi</code>, by Howard</li>
</ul>

<h2 id='acknowledgments'>Acknowledgments</h2>

<p>Hans Boehm, who emphasized the importance of enforcing the per-thread random engine more than once.</p>

<p>Stephan T. Lavavej, who carefully reviewed this paper and provided many corrections.</p>

<p>Walter E. Brown, who drafted the paper<code>[1]</code> which contains basically the same thought.</p>

<p>And many others who joined the <code>std::rand</code> related discussions on <em>c++std-lib</em> and <em>c++std-lib-ext</em> mailing lists.</p>

<h2 id='references'>References</h2>

<p><code>[1]</code> Brown, Walter E. N3742 <em>Three <code>&lt;random&gt;</code>-related Proposals, v2</em>. <a href='http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3742.pdf'>http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3742.pdf</a></p>

<p><code>[2]</code> <em><code>random</code> &#8211; Generate pseudo-random numbers</em>. &#8220;The Python Standard Library&#8221;. <a href='http://docs.python.org/2/library/random.html'>http://docs.python.org/2/library/random.html</a></p>
</body></html>
