X-Git-Url: https://git.distorted.org.uk/~mdw/catacomb/blobdiff_plain/0f00dc4c8eb47e67bc0f148c2dd109f73a451e0a..1519ef6617fd7351bd40026b9eeb47c7f7f42234:/rand/grand.h

diff --git a/rand/grand.h b/rand/grand.h
index ec11404d..b45f0451 100644
--- a/rand/grand.h
+++ b/rand/grand.h
@@ -51,7 +51,10 @@ typedef struct grand_ops {
 
   const char *name;			/* Generator's name */
   unsigned f;				/* Various flags */
-  uint32 max;				/* Maximum raw output */
+  uint32 max;				/* Maximum raw output, if nonzero;
+					 * must be either zero or at least
+					 * 256
+					 */
 
   /* --- Maintenance methods --- */
 
@@ -60,9 +63,10 @@ typedef struct grand_ops {
 
   /* --- Output methods --- *
    *
-   * Only one of these operations need actually be implemented.  All the
-   * other operations may be synthesized.  Of course, performance is improved
-   * if more are provided.
+   * Of these, only @raw@ need be implemented directly by the generator: the
+   * others can point to provided @grand_default...@ functions, which will
+   * synthesize the necessary behaviour.  Of course, this comes at an
+   * efficiency penalty.
    */
 
   uint32 (*raw)(grand */*r*/);		/* Uniform over %$[0, max)$% */
@@ -105,6 +109,67 @@ enum {
 
 #define GRAND_BADOP assert(((void)"bad grand_misc op", 0))
 
+/*----- Default operations ------------------------------------------------*/
+
+/* --- @grand_defaultbyte@ --- *
+ *
+ * Arguments:	@grand *r@ = pointet to generic generator
+ *
+ * Returns:	A uniformly-distributed pseudorandom integer in the interval
+ *		%$[0, 256)$%.
+ *
+ * Use:		Default @byte@ output method.  This calls the @range@ method
+ *		to return a uniform random value between 0 and 255.
+ */
+
+extern octet grand_defaultbyte(grand */*r*/);
+
+/* --- @grand_defaultword@ --- *
+ *
+ * Arguments:	@grand *r@ = pointet to generic generator
+ *
+ * Returns:	A uniformly-distributed pseudorandom integer in the interval
+ *		%$[0, 2^{32})$%.
+ *
+ * Use:		Default @word@ output method.  This calls the @fill@ method
+ *		to fill a 4-octet buffer with uniform random bytes, and then
+ *		converts them to an integer.
+ */
+
+extern uint32 grand_defaultword(grand */*r*/);
+
+/* --- @grand_defaultrange@ --- *
+ *
+ * Arguments:	@grand *r@ = pointet to generic generator
+ *		@uint32 l@ = limit for acceptable results
+ *
+ * Returns:	A uniformly-distributed pseudorandom integer in the interval
+ *		%$[0, l)$%.
+ *
+ * Use:		Default @range@ output method.  This falls back to either
+ *		@word@ (if the generator's @max@ is zero, or if @max < l@) or
+ *		@raw@ (otherwise).  This might recurse via @fill@ and @byte@,
+ *		but this is safe because of the constraint on the @raw@
+ *		method.
+ */
+
+extern uint32 grand_defaultrange(grand */*r*/, uint32 /*l*/);
+
+/* --- @grand_defaultfill@ --- *
+ *
+ * Arguments:	@grand *r@ = pointet to generic generator
+ *		@void *p@ = pointer to a buffer
+ *		@size_t sz@ = size of the buffer
+ *
+ * Returns:	---
+ *
+ * Use:		Fills a buffer with uniformly distributed pseudorandom bytes.
+ *		This calls the @byte@ method repeatedly to fill in the output
+ *		buffer.
+ */
+
+extern void grand_defaultfill(grand */*r*/, void */*p*/, size_t /*sz*/);
+
 /*----- Functions provided ------------------------------------------------*/
 
 /* --- @grand_byte@ --- *