[u/mdw/catacomb] / mp-mem.c

/* -*-c-*-
 *
 * $Id: mp-mem.c,v 1.8 2004/04/08 16:17:32 mdw Exp $
 *
 * Memory management for multiprecision numbers
 *
 * (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.
 */

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

#include <mLib/sub.h>


#include "mp.h"

/*----- Main code ---------------------------------------------------------*/

/* --- @mp_new@ --- *
 *
 * Arguments:	@size_t sz@ = size of vector required
 *		@unsigned f@ = flags to set
 *
 * Returns:	Pointer to a new MP structure.
 *
 * Use:		Allocates a new multiprecision integer.  The data space is
 *		allocated from either the standard global or secret arena,
 *		depending on the initial flags requested.
 */

mp *mp_new(size_t sz, unsigned f)
{
  mp *m = CREATE(mp);
  m->a = (f & MP_BURN) ? MPARENA_SECURE : MPARENA_GLOBAL;
  m->v = mpalloc(m->a, sz);
  m->vl = m->v + sz;
  m->sz = sz;
  m->f = f & ~(MP_CONST | MP_DESTROYED);
  m->ref = 1;
  return (m);
}

/* --- @mp_create@ --- *
 *
 * Arguments:	@size_t sz@ = size of vector required
 *
 * Returns:	Pointer to pristine new MP structure with enough memory
 *		bolted onto it.
 *
 * Use:		Creates a new multiprecision integer, initially zero.  The
 *		integer has a single reference.
 */

mp *mp_create(size_t sz)
{
  mp *m = CREATE(mp);
  m->v = mpalloc(MPARENA_GLOBAL, sz);
  m->vl = m->v + sz;
  m->sz = sz;
  m->a = MPARENA_GLOBAL;
  m->f = MP_UNDEF;
  m->ref = 1;
  return (m);
}

/* --- @mp_createsecure@ --- *
 *
 * Arguments:	@size_t sz@ = size of vector required
 *
 * Returns:	Pointer to pristine new MP structure with enough memory
 *		bolted onto it.
 *
 * Use:		Creates a new multiprecision integer with indeterminate
 *		contents.  The integer has a single reference.  The integer's
 *		data space is allocated from the secure arena.  Its burn flag
 *		is set.
 */

mp *mp_createsecure(size_t sz)
{
  mp *m = CREATE(mp);  
  m->v = mpalloc(MPARENA_SECURE, sz);
  m->vl = m->v + sz;
  m->sz = sz;
  m->a = MPARENA_SECURE;
  m->f = MP_UNDEF | MP_BURN;
  m->ref = 1;
  return (m);
}

/* --- @mp_build@ --- *
 *
 * Arguments:	@mp *m@ = pointer to an MP block to fill in
 *		@mpw *v@ = pointer to a word array
 *		@mpw *vl@ = pointer just past end of array
 *
 * Returns:	---
 *
 * Use:		Creates a multiprecision integer representing some smallish
 *		number.  You must provide storage for the number and dispose
 *		of it when you've finished with it.  The number is marked as
 *		constant while it exists.
 */

void mp_build(mp *m, mpw *v, mpw *vl)
{
  m->v = v;
  m->vl = vl;
  m->sz = vl - v;
  m->f = MP_CONST;
  m->ref = 1;
}

/* --- @mp_destroy@ --- *
 *
 * Arguments:	@mp *m@ = pointer to a multiprecision integer
 *
 * Returns:	---
 *
 * Use:		Destroys a multiprecision integer. The reference count isn't
 *		checked.  Don't use this function if you don't know what
 *		you're doing: use @mp_drop@ instead.
 */

void mp_destroy(mp *m)
{
  assert(((void)"Destroying a free integer", !(m->f & MP_DESTROYED)));
  assert(((void)"Attempted to destroy a constant", !(m->f & MP_CONST)));
  if (m->f & MP_BURN)
    memset(m->v, 0, MPWS(m->sz));
  mpfree(m->a, m->v);
  m->f |= MP_DESTROYED;
  DESTROY(m);
}

/* --- @mp_copy@ --- *
 *
 * Arguments:	@mp *m@ = pointer to a multiprecision integer
 *
 * Returns:	A copy of the given multiprecision integer.
 *
 * Use:		Copies the given integer.  In fact you just get another
 *		reference to the same old one again.
 */

mp *mp_copy(mp *m) { return MP_COPY(m); }

/* --- @mp_drop@ --- *
 *
 * Arguments:	@mp *m@ = pointer to a multiprecision integer
 *
 * Returns:	---
 *
 * Use:		Drops a reference to an integer which isn't wanted any more.
 *		If there are no more references, the integer is destroyed.
 */

void mp_drop(mp *m) { if (m) MP_DROP(m); }

/* --- @mp_split@ --- *
 *
 * Arguments:	@mp *m@ = pointer to a multiprecision integer
 *
 * Returns:	A reference to the same integer, possibly with a different
 *		address.
 *
 * Use:		Splits off a modifiable version of the integer referred to.
 */

mp *mp_split(mp *m) { MP_SPLIT(m); return (m); }

/* --- @mp_resize@ --- *
 *
 * Arguments:	@mp *m@ = pointer to a multiprecision integer
 *		@size_t sz@ = new size
 *
 * Returns:	---
 *
 * Use:		Changes an integer's size.  The length and value are not
 *		changed.  It is an error to 
 */

void mp_resize(mp *m, size_t sz) { MP_RESIZE(m, sz); }

/* --- @mp_ensure@ --- *
 *
 * Arguments:	@mp *m@ = pointer to a multiprecision integer
 *		@size_t sz@ = required length
 *
 * Returns:	---
 *
 * Use:		Changes an integer's length.  If there is not enough space
 *		allocated for the new length then the size is increased.  It
 */

void mp_ensure(mp *m, size_t sz) { MP_ENSURE(m, sz); }

/* --- @mp_dest@ --- *
 *
 * Arguments:	@mp *m@ = a suggested destination integer
 *		@size_t sz@ = size required for result, in digits
 *		@unsigned f@ = various flags
 *
 * Returns:	A pointer to an appropriate destination.
 *
 * Use:		Converts a suggested destination into a real destination with
 *		the required properties.  If the real destination is @d@,
 *		then the following properties will hold:
 *
 *		  * @d@ will have exactly one reference.
 *
 *		  * If @m@ is not @MP_NEW@, then the contents of @m@ will not
 *		    change, unless @f@ has the @MP_UNDEF@ flag set.
 *
 *		  * If @m@ is not @MP_NEW@, then he reference count of @m@ on
 *		    entry is equal to the sum of the counts of @d@ and @m@ on
 *		    exit.
 *
 *		  * The size of @d@ will be at least @sz@.
 *
 *		  * If @f@ has the @MP_BURN@ flag set, then @d@ will be
 *		    allocated from @MPARENA_SECURE@.
 *
 *		Understanding this function is crucial to using Catacomb's
 *		multiprecision integer library effectively.
 */

mp *mp_dest(mp *m, size_t sz, unsigned f)
{
  /* --- If no destination, make one --- */

  if (m == MP_NEWSEC)
    m = mp_new(sz, f | MP_UNDEF | MP_BURN);
  else if (m == MP_NEW)
    m = mp_new(sz, f | MP_UNDEF);
  else {
    size_t len = MP_LEN(m);
    unsigned undef = (m->f | f) & MP_UNDEF;

    /* --- If the value must be preserved, the block can't shrink --- */

    if (!undef && sz < len)
      sz = len;

    /* --- Otherwise check whether the destination is suitable --- */

    if (m->ref > 1 || (m->f & MP_CONST) ||
	sz > m->sz || ((f & ~m->f) & MP_BURN)) {

      /* --- No -- allocate a new buffer --- *
       *
       * The buffer must be secure if (a) the caller requested a secure
       * buffer, or (b) the old buffer is secure and I'm not allowed to
       * discard the old contents.
       */
      
      mparena *a;
      mpw *v;

      if ((f & MP_BURN) || (!undef && (m->f & MP_BURN)))
	a = MPARENA_SECURE;
      else
	a = MPARENA_GLOBAL;
      v = mpalloc(a, sz);

      /* --- Copy the data over --- */

      if (!undef) {
	memcpy(v, m->v, MPWS(len));
	if (sz - len > 0)
	  memset(v + len, 0, MPWS(sz - len));
      }

      /* --- If @m@ has other references, make a new node --- *
       *
       * Otherwise dispose of the old buffer.
       */

      if (!(m->f & MP_CONST) && m->ref == 1) {
	if (m->f & MP_BURN)
	  memset(m->v, 0, MPWS(m->sz));
	mpfree(m->a, m->v);
      } else {
	mp *mm = CREATE(mp);
	mm->ref = 1;
	mm->f = m->f;
	m->ref--;
	m = mm;
      }

      /* --- Fix up the node --- */

      m->v = v;
      m->vl = v + sz;
      m->sz = sz;
      m->f = ((m->f & ~(MP_CONST | MP_BURN)) |
	      (f & (MP_BURN | MP_UNDEF)));
      m->a = a;
    }

    /* --- If the number is growing in its buffer, fix it up --- */

    else if (sz > len) {
      if (!undef)
	memset(m->vl, 0, MPWS(sz - len));
      m->vl = m->v + sz;
    }
  }

  /* --- Done --- */

  return (m);
}

/*----- That's all, folks -------------------------------------------------*/
Commit	Line	Data
d3409d5e	1	/* --c--
d3409d5e	2	*
53cbeae3	3	* $Id: mp-mem.c,v 1.8 2004/04/08 16:17:32 mdw Exp $
d3409d5e	4	*
	5	* Memory management for multiprecision numbers
	6	*
	7	* (c) 1999 Straylight/Edgeware
	8	*/
	9
	10	/----- Licensing notice --------------------------------------------------
	11	*
	12	* This file is part of Catacomb.
	13	*
	14	* Catacomb is free software; you can redistribute it and/or modify
	15	* it under the terms of the GNU Library General Public License as
	16	* published by the Free Software Foundation; either version 2 of the
	17	* License, or (at your option) any later version.
	18	*
	19	* Catacomb is distributed in the hope that it will be useful,
	20	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	21	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	22	* GNU Library General Public License for more details.
	23	*
	24	* You should have received a copy of the GNU Library General Public
	25	* License along with Catacomb; if not, write to the Free
	26	* Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
	27	* MA 02111-1307, USA.
	28	*/
	29
d3409d5e	30	/----- Header files ------------------------------------------------------/
d3409d5e	31
d34decd2	32	#include <mLib/sub.h>
	33
	34
d3409d5e	35	#include "mp.h"
	36
	37	/----- Main code ---------------------------------------------------------/
	38
d34decd2	39	/* --- @mp_new@ --- *
	40	*
	41	* Arguments: @size_t sz@ = size of vector required
	42	* @unsigned f@ = flags to set
	43	*
	44	* Returns: Pointer to a new MP structure.
	45	*
	46	* Use: Allocates a new multiprecision integer. The data space is
	47	* allocated from either the standard global or secret arena,
	48	* depending on the initial flags requested.
	49	*/
	50
	51	mp *mp_new(size_t sz, unsigned f)
	52	{
	53	mp *m = CREATE(mp);
	54	m->a = (f & MP_BURN) ? MPARENA_SECURE : MPARENA_GLOBAL;
	55	m->v = mpalloc(m->a, sz);
	56	m->vl = m->v + sz;
	57	m->sz = sz;
	58	m->f = f & ~(MP_CONST \| MP_DESTROYED);
	59	m->ref = 1;
	60	return (m);
	61	}
	62
d3409d5e	63	/* --- @mp_create@ --- *
	64	*
	65	* Arguments: @size_t sz@ = size of vector required
	66	*
	67	* Returns: Pointer to pristine new MP structure with enough memory
	68	* bolted onto it.
	69	*
	70	* Use: Creates a new multiprecision integer, initially zero. The
	71	* integer has a single reference.
	72	*/
	73
	74	mp *mp_create(size_t sz)
	75	{
	76	mp *m = CREATE(mp);
d34decd2	77	m->v = mpalloc(MPARENA_GLOBAL, sz);
d3409d5e	78	m->vl = m->v + sz;
d3409d5e	79	m->sz = sz;
d34decd2	80	m->a = MPARENA_GLOBAL;
d3409d5e	81	m->f = MP_UNDEF;
	82	m->ref = 1;
	83	return (m);
	84	}
	85
d34decd2	86	/* --- @mp_createsecure@ --- *
	87	*
	88	* Arguments: @size_t sz@ = size of vector required
	89	*
	90	* Returns: Pointer to pristine new MP structure with enough memory
	91	* bolted onto it.
	92	*
	93	* Use: Creates a new multiprecision integer with indeterminate
	94	* contents. The integer has a single reference. The integer's
	95	* data space is allocated from the secure arena. Its burn flag
	96	* is set.
	97	*/
	98
	99	mp *mp_createsecure(size_t sz)
	100	{
	101	mp *m = CREATE(mp);
	102	m->v = mpalloc(MPARENA_SECURE, sz);
	103	m->vl = m->v + sz;
	104	m->sz = sz;
	105	m->a = MPARENA_SECURE;
	106	m->f = MP_UNDEF \| MP_BURN;
	107	m->ref = 1;
	108	return (m);
	109	}
	110
d3409d5e	111	/* --- @mp_build@ --- *
	112	*
	113	* Arguments: @mp *m@ = pointer to an MP block to fill in
	114	* @mpw *v@ = pointer to a word array
	115	* @mpw *vl@ = pointer just past end of array
	116	*
	117	* Returns: ---
	118	*
	119	* Use: Creates a multiprecision integer representing some smallish
	120	* number. You must provide storage for the number and dispose
	121	* of it when you've finished with it. The number is marked as
	122	* constant while it exists.
	123	*/
	124
	125	void mp_build(mp m, mpw v, mpw *vl)
	126	{
	127	m->v = v;
	128	m->vl = vl;
	129	m->sz = vl - v;
	130	m->f = MP_CONST;
	131	m->ref = 1;
	132	}
	133
	134	/* --- @mp_destroy@ --- *
	135	*
	136	* Arguments: @mp *m@ = pointer to a multiprecision integer
	137	*
	138	* Returns: ---
	139	*
	140	* Use: Destroys a multiprecision integer. The reference count isn't
	141	* checked. Don't use this function if you don't know what
	142	* you're doing: use @mp_drop@ instead.
	143	*/
	144
	145	void mp_destroy(mp *m)
	146	{
0e895689	147	assert(((void)"Destroying a free integer", !(m->f & MP_DESTROYED)));
0e895689	148	assert(((void)"Attempted to destroy a constant", !(m->f & MP_CONST)));
d3409d5e	149	if (m->f & MP_BURN)
d3409d5e	150	memset(m->v, 0, MPWS(m->sz));
d34decd2	151	mpfree(m->a, m->v);
0e895689	152	m->f \|= MP_DESTROYED;
d3409d5e	153	DESTROY(m);
	154	}
	155
	156	/* --- @mp_copy@ --- *
	157	*
	158	* Arguments: @mp *m@ = pointer to a multiprecision integer
	159	*
	160	* Returns: A copy of the given multiprecision integer.
	161	*
	162	* Use: Copies the given integer. In fact you just get another
	163	* reference to the same old one again.
	164	*/
	165
	166	mp mp_copy(mp m) { return MP_COPY(m); }
	167
	168	/* --- @mp_drop@ --- *
	169	*
	170	* Arguments: @mp *m@ = pointer to a multiprecision integer
	171	*
	172	* Returns: ---
	173	*
	174	* Use: Drops a reference to an integer which isn't wanted any more.
	175	* If there are no more references, the integer is destroyed.
	176	*/
	177
f1140c41	178	void mp_drop(mp *m) { if (m) MP_DROP(m); }
d3409d5e	179
	180	/* --- @mp_split@ --- *
	181	*
	182	* Arguments: @mp *m@ = pointer to a multiprecision integer
	183	*
	184	* Returns: A reference to the same integer, possibly with a different
	185	* address.
	186	*
	187	* Use: Splits off a modifiable version of the integer referred to.
	188	*/
	189
24521163	190	mp mp_split(mp m) { MP_SPLIT(m); return (m); }
d3409d5e	191
	192	/* --- @mp_resize@ --- *
	193	*
	194	* Arguments: @mp *m@ = pointer to a multiprecision integer
	195	* @size_t sz@ = new size
	196	*
	197	* Returns: ---
	198	*
d34decd2	199	* Use: Changes an integer's size. The length and value are not
d34decd2	200	* changed. It is an error to
d3409d5e	201	*/
d3409d5e	202
24521163	203	void mp_resize(mp *m, size_t sz) { MP_RESIZE(m, sz); }
d3409d5e	204
	205	/* --- @mp_ensure@ --- *
	206	*
	207	* Arguments: @mp *m@ = pointer to a multiprecision integer
d34decd2	208	* @size_t sz@ = required length
d3409d5e	209	*
	210	* Returns: ---
	211	*
d34decd2	212	* Use: Changes an integer's length. If there is not enough space
d34decd2	213	* allocated for the new length then the size is increased. It
d3409d5e	214	*/
d3409d5e	215
24521163	216	void mp_ensure(mp *m, size_t sz) { MP_ENSURE(m, sz); }
d3409d5e	217
d34decd2	218	/* --- @mp_dest@ --- *
d3409d5e	219	*
d34decd2	220	* Arguments: @mp *m@ = a suggested destination integer
	221	* @size_t sz@ = size required for result, in digits
	222	* @unsigned f@ = various flags
	223	*
	224	* Returns: A pointer to an appropriate destination.
	225	*
	226	* Use: Converts a suggested destination into a real destination with
	227	* the required properties. If the real destination is @d@,
	228	* then the following properties will hold:
d3409d5e	229	*
d34decd2	230	* * @d@ will have exactly one reference.
d3409d5e	231	*
d34decd2	232	* * If @m@ is not @MP_NEW@, then the contents of @m@ will not
	233	* change, unless @f@ has the @MP_UNDEF@ flag set.
	234	*
	235	* * If @m@ is not @MP_NEW@, then he reference count of @m@ on
	236	* entry is equal to the sum of the counts of @d@ and @m@ on
	237	* exit.
	238	*
	239	* * The size of @d@ will be at least @sz@.
	240	*
	241	* * If @f@ has the @MP_BURN@ flag set, then @d@ will be
	242	* allocated from @MPARENA_SECURE@.
	243	*
	244	* Understanding this function is crucial to using Catacomb's
	245	* multiprecision integer library effectively.
d3409d5e	246	*/
d3409d5e	247
d34decd2	248	mp mp_dest(mp m, size_t sz, unsigned f)
	249	{
	250	/* --- If no destination, make one --- */
	251
	252	if (m == MP_NEWSEC)
	253	m = mp_new(sz, f \| MP_UNDEF \| MP_BURN);
	254	else if (m == MP_NEW)
	255	m = mp_new(sz, f \| MP_UNDEF);
	256	else {
	257	size_t len = MP_LEN(m);
	258	unsigned undef = (m->f \| f) & MP_UNDEF;
	259
	260	/* --- If the value must be preserved, the block can't shrink --- */
	261
	262	if (!undef && sz < len)
	263	sz = len;
	264
	265	/* --- Otherwise check whether the destination is suitable --- */
	266
	267	if (m->ref > 1 \|\| (m->f & MP_CONST) \|\|
53cbeae3	268	sz > m->sz \|\| ((f & ~m->f) & MP_BURN)) {
d34decd2	269
	270	/* --- No -- allocate a new buffer --- *
	271	*
	272	* The buffer must be secure if (a) the caller requested a secure
	273	* buffer, or (b) the old buffer is secure and I'm not allowed to
	274	* discard the old contents.
	275	*/
	276
	277	mparena *a;
	278	mpw *v;
	279
	280	if ((f & MP_BURN) \|\| (!undef && (m->f & MP_BURN)))
	281	a = MPARENA_SECURE;
	282	else
	283	a = MPARENA_GLOBAL;
	284	v = mpalloc(a, sz);
	285
	286	/* --- Copy the data over --- */
	287
	288	if (!undef) {
	289	memcpy(v, m->v, MPWS(len));
	290	if (sz - len > 0)
	291	memset(v + len, 0, MPWS(sz - len));
	292	}
	293
	294	/* --- If @m@ has other references, make a new node --- *
	295	*
	296	* Otherwise dispose of the old buffer.
	297	*/
	298
	299	if (!(m->f & MP_CONST) && m->ref == 1) {
	300	if (m->f & MP_BURN)
	301	memset(m->v, 0, MPWS(m->sz));
	302	mpfree(m->a, m->v);
	303	} else {
	304	mp *mm = CREATE(mp);
	305	mm->ref = 1;
	306	mm->f = m->f;
	307	m->ref--;
	308	m = mm;
	309	}
	310
	311	/* --- Fix up the node --- */
	312
	313	m->v = v;
	314	m->vl = v + sz;
	315	m->sz = sz;
	316	m->f = ((m->f & ~(MP_CONST \| MP_BURN)) \|
	317	(f & (MP_BURN \| MP_UNDEF)));
	318	m->a = a;
	319	}
	320
	321	/* --- If the number is growing in its buffer, fix it up --- */
	322
	323	else if (sz > len) {
	324	if (!undef)
	325	memset(m->vl, 0, MPWS(sz - len));
	326	m->vl = m->v + sz;
	327	}
	328	}
	329
	330	/* --- Done --- */
	331
	332	return (m);
333	}
d3409d5e	334
d3409d5e	335	/----- That's all, folks -------------------------------------------------/