Static workspace control routines

SYNOPSIS

#include "matrix.h"
int  MEM_STAT_REG(void *var, int type)
int  mem_stat_reg_list(void **var, int type, int list_num)
int  mem_stat_reg_vars(int list_num, int type,
                       void **var1, void **var2, ..., NULL)
int  mem_stat_mark(int mark)
int  mem_stat_free(int mark)
void mem_stat_dump(FILE *fp)
int  mem_stat_show_mark()

DESCRIPTION

Older versions of Meschach (v.1.1b and previous) had a limitation in that it was essentially impossible to control the use of static workspace arrays used within Meschach functions. This can lead to problems where too much memory is taken up by these workspace arrays for memory intensive problems. The obvious alternative approach is to deallocate workspace at the end of every function, which can be quite expensive because of the time taken to deallocate and the reallocate the memory on every usage. These functions provide a way of avoiding these problems, by giving users control over the (selective) destruction of workspace vectors, matrices, etc. The simplest way to use this to deallocate workspace arrays in a routine hairy1(...) is as follows:

  ......
mem_stat_mark(1);  /* ``group 1'' of workspace arrays */
for ( i = 0; i < n; i++ )
    hairy1(...);   /* workspace registered as ``group 1'' */
mem_stat_free(1);  /* deallocate ``group 1'' workspace */

The call mem_stat_mark(num) sets the current workspace group number. This number must be a positive integer. Provided the appropriate workspace registration routines are used in hairy1(...) (see later), then the workspace arrays are registered as being in the current workspace group as determined by mem_stat_mark(). If mem_stat_mark() has not been called, then there is no current group number and the variables are not registered. The call mem_stat_free(num) deallocates all static workspace arrays allocated in workspace group num, and also unsets the current workspace group. So, to continue registering static workspace variables, mem_stat_mark(num), or \newlinemem_stat_mark(new_num) should follow. Keeping two groups of registered static workspace variables (one for hairy1() and another for hairy2()) can be done as follows:

  ......
for ( i = 0; i < n; i++ )
{
    mem_stat_mark(1);
    hairy1(...);
    mem_stat_mark(2);
    hairy2(...);
}
mem_stat_free(2);    /* don't want hairy2()'s workspace */
hairy1(...);         /* keep hairy1()'s workspace */

For the person writing routines to use workspace arrays, there are a number of rules that must be followed if these routines are to be used.

the workspace variables must be static pointers to Meschach data structures.
they must be initialised to be NULL vectors in the type declaration.
they are allocated using a .._resize() routine.
they are allocated before registering.
the pointer variable is passed to MEM_STAT_REG(), but \newlinemem_stat_reg_vars() and mem_stat_reg_vars() require the address\/ of the pointer to be passed.

The type parameter of MEM_STAT_REG() should be a macro of the form TYPE_... where the ``...'' is the name of the type used. An example of its use follows:

VEC *hairy1(x, y, out)
VEC *x, *y, *out;
{
    static VEC *wkspace = VNULL;
    int    new_dim;
      ......
    wkspace = v_resize(wkspace,new_dim);
    MEM_STAT_REG(wkspace,TYPE_VEC);
      ......
    mv_mlt(....,wkspace);  /* use of wkspace */
      ......
    /* no need to deallocate wkspace */
    return out;
}

MEM_STAT_REG() is a macro which calls mem_stat_reg_list() with \newlinelist_num set to zero. The call mem_stat_dump(fp) prints out a representation of the registered workspace variables onto the file or stream fp suitable for debugging purposes. It is not expected that this would be needed by most users of Meschach. The routine mem_stat_show_mark() returns the current workspace group, and zero if no group is active. A NULL terminated list of variables can be registered at once using \newlinemem_stat_reg_vars(). The call

mem_stat_reg_vars(list_num,type_num,&x1,&x2,...,&xN,NULL);

is equivalent to

mem_stat_reg_list(&x1,type_num,list_num);
mem_stat_reg_list(&x2,type_num,list_num);
  ......
mem_stat_reg_list(&xN,type_num,list_num);

Note that x1, x2,\dots, xN must be of the same type. For non-Meschach data structures, you can use mem_stat_reg_list() in conjunction with mem_attach_list(). For more information on the use of this function see chapter~8.