[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->a = MPARENA_GLOBAL;
  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
45c0fd36	10	/----- Licensing notice --------------------------------------------------
d3409d5e	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.
45c0fd36	18	*
d3409d5e	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.
45c0fd36	23	*
d3409d5e	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	{
45c0fd36	101	mp *m = CREATE(mp);
d34decd2	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;
78ec50fa	130	m->a = MPARENA_GLOBAL;
d3409d5e	131	m->f = MP_CONST;
	132	m->ref = 1;
	133	}
	134
	135	/* --- @mp_destroy@ --- *
	136	*
	137	* Arguments: @mp *m@ = pointer to a multiprecision integer
	138	*
	139	* Returns: ---
	140	*
	141	* Use: Destroys a multiprecision integer. The reference count isn't
	142	* checked. Don't use this function if you don't know what
	143	* you're doing: use @mp_drop@ instead.
	144	*/
	145
	146	void mp_destroy(mp *m)
	147	{
0e895689	148	assert(((void)"Destroying a free integer", !(m->f & MP_DESTROYED)));
0e895689	149	assert(((void)"Attempted to destroy a constant", !(m->f & MP_CONST)));
d3409d5e	150	if (m->f & MP_BURN)
d3409d5e	151	memset(m->v, 0, MPWS(m->sz));
d34decd2	152	mpfree(m->a, m->v);
0e895689	153	m->f \|= MP_DESTROYED;
d3409d5e	154	DESTROY(m);
	155	}
	156
	157	/* --- @mp_copy@ --- *
	158	*
	159	* Arguments: @mp *m@ = pointer to a multiprecision integer
	160	*
	161	* Returns: A copy of the given multiprecision integer.
	162	*
	163	* Use: Copies the given integer. In fact you just get another
	164	* reference to the same old one again.
	165	*/
	166
	167	mp mp_copy(mp m) { return MP_COPY(m); }
	168
	169	/* --- @mp_drop@ --- *
	170	*
	171	* Arguments: @mp *m@ = pointer to a multiprecision integer
	172	*
	173	* Returns: ---
	174	*
	175	* Use: Drops a reference to an integer which isn't wanted any more.
	176	* If there are no more references, the integer is destroyed.
	177	*/
	178
f1140c41	179	void mp_drop(mp *m) { if (m) MP_DROP(m); }
d3409d5e	180
	181	/* --- @mp_split@ --- *
	182	*
	183	* Arguments: @mp *m@ = pointer to a multiprecision integer
	184	*
	185	* Returns: A reference to the same integer, possibly with a different
	186	* address.
	187	*
	188	* Use: Splits off a modifiable version of the integer referred to.
	189	*/
	190
24521163	191	mp mp_split(mp m) { MP_SPLIT(m); return (m); }
d3409d5e	192
	193	/* --- @mp_resize@ --- *
	194	*
	195	* Arguments: @mp *m@ = pointer to a multiprecision integer
	196	* @size_t sz@ = new size
	197	*
	198	* Returns: ---
	199	*
d34decd2	200	* Use: Changes an integer's size. The length and value are not
45c0fd36	201	* changed. It is an error to
d3409d5e	202	*/
d3409d5e	203
24521163	204	void mp_resize(mp *m, size_t sz) { MP_RESIZE(m, sz); }
d3409d5e	205
	206	/* --- @mp_ensure@ --- *
	207	*
	208	* Arguments: @mp *m@ = pointer to a multiprecision integer
d34decd2	209	* @size_t sz@ = required length
d3409d5e	210	*
	211	* Returns: ---
	212	*
d34decd2	213	* Use: Changes an integer's length. If there is not enough space
d34decd2	214	* allocated for the new length then the size is increased. It
d3409d5e	215	*/
d3409d5e	216
24521163	217	void mp_ensure(mp *m, size_t sz) { MP_ENSURE(m, sz); }
d3409d5e	218
d34decd2	219	/* --- @mp_dest@ --- *
d3409d5e	220	*
d34decd2	221	* Arguments: @mp *m@ = a suggested destination integer
	222	* @size_t sz@ = size required for result, in digits
	223	* @unsigned f@ = various flags
	224	*
	225	* Returns: A pointer to an appropriate destination.
	226	*
	227	* Use: Converts a suggested destination into a real destination with
	228	* the required properties. If the real destination is @d@,
	229	* then the following properties will hold:
d3409d5e	230	*
d34decd2	231	* * @d@ will have exactly one reference.
d3409d5e	232	*
d34decd2	233	* * If @m@ is not @MP_NEW@, then the contents of @m@ will not
	234	* change, unless @f@ has the @MP_UNDEF@ flag set.
	235	*
	236	* * If @m@ is not @MP_NEW@, then he reference count of @m@ on
	237	* entry is equal to the sum of the counts of @d@ and @m@ on
	238	* exit.
	239	*
	240	* * The size of @d@ will be at least @sz@.
	241	*
	242	* * If @f@ has the @MP_BURN@ flag set, then @d@ will be
	243	* allocated from @MPARENA_SECURE@.
	244	*
	245	* Understanding this function is crucial to using Catacomb's
	246	* multiprecision integer library effectively.
d3409d5e	247	*/
d3409d5e	248
d34decd2	249	mp mp_dest(mp m, size_t sz, unsigned f)
	250	{
	251	/* --- If no destination, make one --- */
	252
	253	if (m == MP_NEWSEC)
	254	m = mp_new(sz, f \| MP_UNDEF \| MP_BURN);
	255	else if (m == MP_NEW)
	256	m = mp_new(sz, f \| MP_UNDEF);
	257	else {
	258	size_t len = MP_LEN(m);
	259	unsigned undef = (m->f \| f) & MP_UNDEF;
	260
	261	/* --- If the value must be preserved, the block can't shrink --- */
	262
	263	if (!undef && sz < len)
	264	sz = len;
	265
	266	/* --- Otherwise check whether the destination is suitable --- */
	267
	268	if (m->ref > 1 \|\| (m->f & MP_CONST) \|\|
53cbeae3	269	sz > m->sz \|\| ((f & ~m->f) & MP_BURN)) {
d34decd2	270
	271	/* --- No -- allocate a new buffer --- *
	272	*
	273	* The buffer must be secure if (a) the caller requested a secure
	274	* buffer, or (b) the old buffer is secure and I'm not allowed to
	275	* discard the old contents.
	276	*/
45c0fd36	277
d34decd2	278	mparena *a;
	279	mpw *v;
	280
	281	if ((f & MP_BURN) \|\| (!undef && (m->f & MP_BURN)))
	282	a = MPARENA_SECURE;
	283	else
	284	a = MPARENA_GLOBAL;
	285	v = mpalloc(a, sz);
	286
	287	/* --- Copy the data over --- */
	288
	289	if (!undef) {
	290	memcpy(v, m->v, MPWS(len));
	291	if (sz - len > 0)
	292	memset(v + len, 0, MPWS(sz - len));
	293	}
	294
	295	/* --- If @m@ has other references, make a new node --- *
	296	*
	297	* Otherwise dispose of the old buffer.
	298	*/
	299
	300	if (!(m->f & MP_CONST) && m->ref == 1) {
	301	if (m->f & MP_BURN)
	302	memset(m->v, 0, MPWS(m->sz));
	303	mpfree(m->a, m->v);
	304	} else {
	305	mp *mm = CREATE(mp);
	306	mm->ref = 1;
	307	mm->f = m->f;
	308	m->ref--;
	309	m = mm;
	310	}
	311
	312	/* --- Fix up the node --- */
	313
	314	m->v = v;
	315	m->vl = v + sz;
	316	m->sz = sz;
	317	m->f = ((m->f & ~(MP_CONST \| MP_BURN)) \|
	318	(f & (MP_BURN \| MP_UNDEF)));
	319	m->a = a;
	320	}
	321
	322	/* --- If the number is growing in its buffer, fix it up --- */
	323
	324	else if (sz > len) {
	325	if (!undef)
	326	memset(m->vl, 0, MPWS(sz - len));
	327	m->vl = m->v + sz;
	328	}
	329	}
	330
	331	/* --- Done --- */
	332
	333	return (m);
	334	}
d3409d5e	335
d3409d5e	336	/----- That's all, folks -------------------------------------------------/