next up previous contents index
Next: Wdevice Library and window Up: Miscellaneous Features Previous: Conversion between memory types   Contents   Index

Miscellaneous System Functions

The following is a description of some miscellaneous system functions which may be of interest for the user. The list is in alphabetical order.

The most usefull are mwerror and mwdebug. Please notice that you need to process any error (especially memory allocation failure) by displaying an error message using mwerror, and by doing appropriate statement.

Some other functions are about dynamic memory allocation. They are important, since you are discouraged to use static memory allocation (as double data[10000]), but you may skip their description if you are familiar with the standard C dynamic memory functions.

$ \bigcirc$Name


mwcalloc - Dynamic memory allocation




$ \bigcirc$Summary


void *mwcalloc (nelem, elsize)

unsigned nelem, elsize;




$ \bigcirc$Description


This function allocates space for an array of nelem elements, each of size elsize bytes, and initializes the space to zeros.

This function returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Do not forget to cast the return value to the right type of your variable (see example below). If not enough memory is available to allocate the array, the function returns NULL. Your code should check this return value to send an error message in the NULL case, and do appropriate statement.

Each space allocated by mwcalloc must be deallocated using mwcfree before exiting the module.

Notice that in the MegaWave2 modules, the standard C function calloc is redefined to be mwcalloc. Therefore, if you use calloc in your code you actually call mwcalloc.




$ \bigcirc$Example

float *data=NULL; /* Internal use: no Input neither Output of module */

/* Allocates space for 1000 samples of float values */
if  ( (data = (float *) mwcalloc (1000, sizeof(float))) == NULL )
    mwerror(FATAL,1,"Not enough memory.\n");

/* Set the sample #i to the value i */
for (i=0;i<1000;i++) data[i] = i;

$ \bigcirc$Name


mwcfree - Dynamic memory deallocation




$ \bigcirc$Summary


void mwcfree (ptr)

char *ptr;




$ \bigcirc$Description


This function deallocates the space pointed to by ptr and which has previously been allocated by mwcalloc. It does nothing if ptr = NULL.

You should set ptr to NULLafter this call since the address pointed to by ptr is no longer valid.

Notice that in the MegaWave2 modules, the standard C function cfree is redefined to be mwcfree. Therefore, if you use cfree in your code you actually call mwcfree.




$ \bigcirc$Example

float *data=NULL; /* Internal use: no Input neither Output of module */

/* Allocates space for 1000 samples of float values */
if  ( (data = (float *) mwcalloc (1000, sizeof(float))) == NULL )
    mwerror(FATAL,1,"Not enough memory.\n");
.
. (statement)
.
/* End of statement: deallocation of the array */
mwcfree((char *) data);

$ \bigcirc$Name


mwdebug - print if debug




$ \bigcirc$Summary


void mwdebug(format, ...);

char *format;




$ \bigcirc$Description


This function prints its arguments in ...under control of the format in format, exactly in the same manner that the standard C function printf does. The string <dbg> is added to the beginning of the line.

The print is active only when the module has been called with the debugging option on.




$ \bigcirc$Example

Fimage image; 
int x,y;

for (x=0;x<image->ncol;x++) for (y=0;y<image->nrow;y++)
{
  mwdebug("processing pixel (%d,%d)...\n",x,y);
  .
  . (statement)
  .
}

$ \bigcirc$Name


mwerror - print an error message




$ \bigcirc$Summary


void mwerror(type, exit_code, format, ...);

int type;

int exit_code;

char *format;




$ \bigcirc$Description


This function prints its arguments in ...under control of the format in format on the standard error output, in the same manner that the standard C function fprintf(stdout,format,...) does.

A message is added to the print, and an action may be performed, according to the value in type :




$ \bigcirc$Example

/* Compute some norm of any fimage */
static float fnorm(image) 
Fimage image; 

{ float norm;  /* result of the computation */
  .
  .  (statement)
  .
  if (norm < 0.0)
   mwerror(INTERNAL,1,"[fnorm] Negative norm value computed ! (norm=%f)",norm);
  else return(norm);
}

$ \bigcirc$Name


mwexit - Module termination




$ \bigcirc$Summary


void mwexit (status)

int status;




$ \bigcirc$Description


This function causes normal program termination of a MegaWave2 module. The variable status indicates the status of the module when the termination occurred; value 0 means successful termination, other values are user-dependent.

Notice that in the MegaWave2 modules, the standard C function exit is redefined to be mwexit. Therefore, if you use exit in your code you actually call mwexit.




$ \bigcirc$Example

Fimage image; /* Output of module */

/* Try several times an allocation of a fimage of size 256x256 */
while (mw_alloc_fimage(image,256,256) == NULL)
  {
     mwerror(ERROR,1,"Not enough memory !\n");
     if (mwerrcnt > 10) mwexit(-1);
     sleep(2);  /* Wait 2 seconds */
  }

$ \bigcirc$Name


mwfree - Dynamic memory deallocation




$ \bigcirc$Summary


void mwfree (ptr)

char *ptr;




$ \bigcirc$Description


This function deallocates the space pointed to by ptr and which has previously been allocated by mwmalloc. It does nothing if ptr = NULL.

You should set ptr to NULLafter this call since the address pointed to by ptr is no longer valid.

Notice that in the MegaWave2 modules, the standard C function free is redefined to be mwfree. Therefore, if you use free in your code you actually call mwfree.




$ \bigcirc$Example

float *data=NULL; /* Internal use: no Input neither Output of module */

/* Allocates space for 1000 samples of float values */
if  ( (data = (float *) mwmalloc (1000*sizeof(float))) == NULL )
    mwerror(FATAL,1,"Not enough memory.\n");
.
. (statement)
.
/* End of statement: deallocation of the array */
mwfree((char *) data);

$ \bigcirc$Name


mwmalloc - Dynamic memory allocation




$ \bigcirc$Summary


void *mwmalloc (size)

size_t size;




$ \bigcirc$Description


This function allocates space for a block of at least size bytes, but does not initialize the space.

This function returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object. Do not forget to cast the return value to the right type of your variable (see example below). If not enough memory is available to allocate the array, the function returns NULL. Your code should check this return value to send an error message in the NULL case, and do appropriate statement.

Each space allocated by mwmalloc must be deallocated using mwfree before exiting the module.

Notice that in the MegaWave2 modules, the standard C function malloc is redefined to be mwmalloc. Therefore, if you use malloc in your code you actually call mwmalloc.




$ \bigcirc$Example

long *data=NULL; /* Internal use: no Input neither Output of module */

/* Allocates space for 5000 samples of long values */
if  ( (data = (long *) mwmalloc (5000*sizeof(long))) == NULL )
    mwerror(FATAL,1,"Not enough memory.\n");

/* Set the sample #i to the value i */
for (i=0;i<5000;i++) data[i] = i;

$ \bigcirc$Name


mwrealloc - Dynamic memory re-allocation




$ \bigcirc$Summary


void *mwrealloc(ptr, size)

char *ptr; unsigned size;




$ \bigcirc$Description


This function changes the size of the block pointed to by ptr to size bytes and returns a pointer to the (possibly moved) block. Existing contents are unchanged up to the lesser of the new and old sizes. If ptr is a NULLpointer, mwrealloc behaves like mwmalloc for the specified size. If size is zero and ptr is not a NULLpointer, the object it points to is freed and NULLis returned.

If not enough memory is available to allocate the array, the function returns NULL. Your code should check this return value to send an error message in the NULL case, and do appropriate statement.

Do not forget to cast the return value to the right type of your variable, and to cast the type of the input pointer ptr to be char * (see example below).

Each space allocated by mwrealloc must be deallocated using mwfree before exiting the module.

Notice that in the MegaWave2 modules, the standard C function realloc is redefined to be mwrealloc. Therefore, if you use realloc in your code you actually call mwrealloc.




$ \bigcirc$Example

long *ldata=NULL;   /* Internal use: no Input neither Output of module */
double *ddata=NULL;

/* Allocates space for 5000 samples of long values */
if  ( (ldata = (long *) mwmalloc (5000*sizeof(long))) == NULL )
    mwerror(FATAL,1,"Not enough memory.\n");
.
.
.
/* Re-allocates space for 2000 samples of double values, using space allocated
   for ldata 
*/
if  ( (ddata = (double *) mwrealloc ((char *) ldata, 2000*sizeof(double))) == NULL )
    mwerror(FATAL,1,"Not enough memory.\n");

/* Warning : do not use anymore the array ldata ! */


next up previous contents index
Next: Wdevice Library and window Up: Miscellaneous Features Previous: Conversion between memory types   Contents   Index
mw 2004-05-05