Add an internal-representation no-op function.

[u/mdw/catacomb] / limlee.h

/* -*-c-*-
 *
 * $Id: limlee.h,v 1.4 2001/02/03 11:59:07 mdw Exp $
 *
 * Generate Lim-Lee primes
 *
 * (c) 2000 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.
 */

/*----- Revision history --------------------------------------------------* 
 *
 * $Log: limlee.h,v $
 * Revision 1.4  2001/02/03 11:59:07  mdw
 * Don't use the @pgen@ random number generator for generating primes: it's
 * only for testing them.  Use a caller-supplied one instead.
 *
 * Revision 1.3  2000/12/06 20:33:27  mdw
 * Make flags be macros rather than enumerations, to ensure that they're
 * unsigned.
 *
 * Revision 1.2  2000/08/18 19:16:51  mdw
 * New stepper interface for constructing Lim-Lee primes.
 *
 * Revision 1.1  2000/07/09 21:30:58  mdw
 * Lim-Lee prime generation.
 *
 */

#ifndef CATACOMB_LIMLEE_H
#define CATACOMB_LIMLEE_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Header files ------------------------------------------------------*/

#ifndef CATACOMB_GRAND_H
#  include "grand.h"
#endif

#ifndef CATACOMB_MP_H
#  include "mp.h"
#endif

#ifndef CATACOMB_PGEN_H
#  include "pgen.h"
#endif

/*----- Data structures ---------------------------------------------------*/

typedef struct limlee_factor {
  mp *p;				/* The actual prime */
  unsigned tag;				/* A tag, usable by the generator */
  void *more;				/* Pointer to more data */
} limlee_factor;

typedef struct limlee_stepctx {

  /* --- To be initialized by the caller --- */

  unsigned f;				/* Various useful flags */
  mp *newp;				/* Initial valid for new primes */
  unsigned ql, pl;			/* Size of factors and result */
  const struct limlee_primeops *pops;	/* Pointer to generator ops */
  void *pc;				/* Context ptr for generator ops */
  pgen_proc *iev;			/* Event handler for inner @pgen@ */
  void *iec;				/* Context for inner @pgen@ */
  grand *r;				/* Random number generator */

  /* --- Output values --- */

  size_t nf;				/* Number of factors wanted */
  limlee_factor *v;			/* Vector of factors */

  /* --- Maintained internally --- */

  octet *c;				/* Combination byte-flag vector */
  unsigned long seq;			/* Sequence number for primes */
  size_t poolsz;			/* Size of the small-prime pool */
  dstr d;				/* String for subprime name */
  limlee_factor qq;			/* Big prime to pick up slack */

} limlee_stepctx;

typedef struct limlee_primeops {
  void (*pgen)(limlee_factor */*f*/, unsigned /*pl*/, limlee_stepctx */*l*/);
  void (*pfree)(limlee_factor */*f*/, limlee_stepctx */*l*/);
} limlee_primeops;

/* --- Flags --- */

#define LIMLEE_KEEPFACTORS 1u

/*----- The Lim-Lee stepper function --------------------------------------*/

extern int limlee_step(int /*rq*/, pgen_event */*ev*/, void */*p*/);

/*----- Functions provided ------------------------------------------------*/

/* --- @limlee@ --- *
 *
 * Arguments:	@const char *name@ = pointer to name root
 *		@mp *d@ = pointer to destination integer
 *		@mp *newp@ = how to generate factor primes
 *		@unsigned ql@ = size of individual factors
 *		@unsigned pl@ = size of large prime
 *		@grand *r@ = a random number source
 *		@unsigned on@ = number of outer attempts to make
 *		@pgen_proc *oev@ = outer event handler function
 *		@void *oec@ = argument for the outer event handler
 *		@pgen_proc *iev@ = inner event handler function
 *		@void *iec@ = argument for the inner event handler
 *		@size_t *nf@, @mp ***f@ = output array for factors
 *
 * Returns:	A Lim-Lee prime, or null if generation failed.
 *
 * Use:		Generates Lim-Lee primes.  A Lim-Lee prime %$p$% is one which
 *		satisfies %$p = 2 \prod_i q_i + 1$%, where all of the %$q_i$%
 *		are large enough to resist square-root discrete log
 *		algorithms.
 *
 *		If we succeed, and @f@ is non-null, we write the array of
 *		factors chosen to @f@ for the benefit of the caller.
 */

extern mp *limlee(const char */*name*/, mp */*d*/, mp */*newp*/,
		  unsigned /*ql*/, unsigned /*pl*/, grand */*r*/,
		  unsigned /*on*/, pgen_proc */*oev*/, void */*oec*/,
		  pgen_proc */*iev*/, void */*iec*/,
		  size_t */*nf*/, mp ***/*f*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif