Rearrange the file tree.

[u/mdw/catacomb] / rand / grand.h

diff --git a/rand/grand.h b/rand/grand.h
new file mode 100644 (file)
index 0000000..ec11404
--- /dev/null
+++ b/rand/grand.h
@@ -0,0 +1,161 @@
+/* -*-c-*-
+ *
+ * Generic interface to random number generators
+ *
+ * (c) 1999 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------*
+ *
+ * This file is part of Catacomb.
+ *
+ * Catacomb is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Library General Public License as
+ * published by the Free Software Foundation; either version 2 of the
+ * License, or (at your option) any later version.
+ *
+ * Catacomb is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with Catacomb; if not, write to the Free
+ * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+#ifndef CATACOMB_GRAND_H
+#define CATACOMB_GRAND_H
+
+#ifdef __cplusplus
+  extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <assert.h>
+#include <stddef.h>
+
+#include <mLib/bits.h>
+
+/*----- Generic random number generator interface -------------------------*/
+
+typedef struct grand {
+  const struct grand_ops *ops;
+} grand;
+
+typedef struct grand_ops {
+
+  /* --- Various important properties --- */
+
+  const char *name;                    /* Generator's name */
+  unsigned f;                          /* Various flags */
+  uint32 max;                          /* Maximum raw output */
+
+  /* --- Maintenance methods --- */
+
+  int (*misc)(grand */*r*/, unsigned /*op*/, ...); /* Miscellaneous ops */
+  void (*destroy)(grand */*r*/);       /* Destroy generator context */
+
+  /* --- 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.
+   */
+
+  uint32 (*raw)(grand */*r*/);         /* Uniform over %$[0, max)$% */
+  octet (*byte)(grand */*r*/);         /* Uniform over %$[0, 256)$% */
+  uint32 (*word)(grand */*r*/);                /* Uniform over %$[0, 2^{32})$% */
+  uint32 (*range)(grand */*r*/, uint32 /*l*/); /* Uniform over %$[0, l)$% */
+  void (*fill)(grand */*r*/, void */*p*/, size_t /*sz*/); /* Fill buffer */
+} grand_ops;
+
+#define GR_DESTROY(r)          (r)->ops->destroy((r))
+#define GR_RAW(r)              (r)->ops->raw((r))
+#define GR_WORD(r)             (r)->ops->word((r))
+#define GR_RANGE(r, l)         (r)->ops->range((r), (l))
+#define GR_FILL(r, p, sz)      (r)->ops->fill((r), (p), (sz))
+
+/* --- Flag types --- */
+
+#define GRAND_CRYPTO 1u                        /* Cryptographically strong */
+
+/* --- Operation types --- */
+
+enum {
+
+  /* --- Required operations --- */
+
+  GRAND_CHECK,                         /* @unsigned op2@ */
+
+  /* --- Standard seeding operations --- */
+
+  GRAND_SEEDINT,                       /* @int i@ */
+  GRAND_SEEDUINT32,                    /* @uint32 i@ */
+  GRAND_SEEDBLOCK,                     /* @const void *p, size_t sz@ */
+  GRAND_SEEDMP,                                /* @mp *m@ */
+  GRAND_SEEDRAND                       /* @grand *g@ */
+
+  /* --- Generator-specific operations --- */
+
+#define GRAND_SPECIFIC(ch) ((unsigned)(ch) << 8)
+};
+
+#define GRAND_BADOP assert(((void)"bad grand_misc op", 0))
+
+/*----- Functions provided ------------------------------------------------*/
+
+/* --- @grand_byte@ --- *
+ *
+ * Arguments:  @grand *r@ = pointet to generic generator
+ *
+ * Returns:    A uniformly-distributed pseudorandom integer in the interval
+ *             %$[0, 256)$%.
+ */
+
+extern octet grand_byte(grand */*r*/);
+
+/* --- @grand_word@ --- *
+ *
+ * Arguments:  @grand *r@ = pointet to generic generator
+ *
+ * Returns:    A uniformly-distributed pseudorandom integer in the interval
+ *             %$[0, 2^{32})$%.
+ */
+
+extern uint32 grand_word(grand */*r*/);
+
+/* --- @grand_range@ --- *
+ *
+ * Arguments:  @grand *r@ = pointet to generic generator
+ *             @uint32 l@ = limit for acceptable results
+ *
+ * Returns:    A uniformly-distributed pseudorandom integer in the interval
+ *             %$[0, l)$%.
+ */
+
+extern uint32 grand_range(grand */*r*/, uint32 /*l*/);
+
+/* --- @grand_fill@ --- *
+ *
+ * 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
+ *             (see @grand_byte@).
+ */
+
+extern void grand_fill(grand */*r*/, void */*p*/, size_t /*sz*/);
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+  }
+#endif
+
+#endif