star-sp

commit e9916421a494772b1e5ec0746fcc950bbfa5b78c
parent 2b4c0853c79eb03365fbea98123dd70efd6f78d9
Author: Vincent Forest <vincent.forest@meso-star.com>
Date:   Wed,  2 Mar 2022 12:12:10 +0100

Rewrite and add comments in ssp_rng_proxy.c

Diffstat:
M
src/ssp_rng_proxy.c
 | 
41
++++++++++++++++++++++-------------------

1 file changed, 22 insertions(+), 19 deletions(-)
diff --git a/src/ssp_rng_proxy.c b/src/ssp_rng_proxy.c
@@ -40,6 +40,9 @@
 #include <limits.h>
 
 #define BUCKET_SIZE_DEFAULT 1000000 /* #RNs per bucket */
+
+/* Cache size to use. This is just a hint: the effective size of the cache is
+ * actually a multiple of the size of the RNG state it should store. */
 #if 1
   #define STATE_CACHE_HINT_MAX_SIZE (32*(1024*1024)) /* 32 MB */
 #else
@@ -95,17 +98,17 @@ struct ssp_rng_proxy {
 
   /* Index of the last queried sequence. This index is independent of the
    * original seed used by the proxy and is designed to identify the status of
-   * the proxy relative to its original seed. When the proxy is created, the
-   * sequence index is SSP_SEQUENCE_ID_NONE, that is, no sequence has been
-   * queried. At the first query of a random number, the first sequence is
-   * consumed and this sequence index is then 0. It is then incremented by one
-   * each time a new sequence is required.
+   * the proxy relative to that original seed. When the proxy is created, the
+   * sequence index is SSP_SEQUENCE_ID_NONE, i.e. no sequence was queried. At
+   * the first request for a random number, the first sequence is consumed and
+   * this sequence index is then 0. It is then incremented by one each time a
+   * new sequence is required.
    *
-   * Each bucket registers the sequence id of its local RNG. The sequence id of
-   * the proxy is the max between these per bucket sequence ids. Note that we
-   * also keep track of the sequence_id of the proxy RNG (main_sequence_id)
-   * that is equal to the sequence id of the proxy only when the cache
-   * mechanism is still in use. */
+   * Each bucket stores the sequence ID of its local RNG. The proxy sequence ID
+   * is the maximum between these local sequence indices. Note that we also
+   * keep track of the RNG proxy's sequence index (main_sequence_id); it is
+   * equal to the proxy sequence identifier only when the caching mechanism is
+   * still in use. */
   size_t* per_bucket_sequence_id;
   size_t main_sequence_id;
 
@@ -901,15 +904,15 @@ ssp_rng_proxy_flush_sequences
   res = ssp_rng_proxy_get_sequence_id(proxy, &iseq);
   if(res != RES_OK) goto error;
 
-  /* Compute the number of sequences to flush for the _main_ RNG, i.e. the one
-   * used when the cache is in use. One wants to flush the random numbers of
-   * 'nseqs' sequences from the current sequence id of the proxy. That's said,
-   * since the status of the RNGs are set to the state of the 1st random number
-   * of the _next_ sequence it is only necessary to discard (nseqs-1) sequences
-   * and to clear the cache. Anyway, note that the main sequence id can be
-   * behind the overall sequence id. This occurs when the cache mechanism is no
-   * more in use. In this case we have to flush additionnal sequences from the
-   * main sequence id to the current sequence id of the proxy. */
+  /* Calculate the number of sequences to flush for the main RNG, i.e. the one
+   * used when the cache is in use. We want to dump the 'nseqs' sequences. That
+   * said, since the status of the RNG is set to the status of the 1st random
+   * number of the next sequence, it is enough to 'nseqs-1' sequences and clear
+   * the cache. Anyway, note that the sequence identifier of the main RNG may
+   * be behind the global sequence identifier. This happens when the cache
+   * mechanism is no longer used. In this case, we need to dump the extra
+   * sequences from the main RNG to match the current sequence index of the
+   * proxy. */
   nseqs_proxy = (nseqs - 1) + (iseq - proxy->main_sequence_id);
 
   mutex_lock(proxy->mutex);