_udestroy - Destroy a Heap

Syntax

#include <umalloc.h>
int _udestroy(Heap_t heap, int force);

Description

• udestroy destroys the heap you specify. It also returns the heap's memory to the system by calling the release_fn you supplied to _ucreate when you created the heap. If you did not supply a release_fn, _udestroy simply marks the heap as destroyed so no further operations can be performed. You must then return all the memory in the heap to the system.

  Note: Whether or not you provide a release_fn, you must always return the initial block of memory (that you provided to _ucreate) to the system.

  The force parameter controls the behavior of _udestroy if all allocated objects from the heap have not been freed. If you specify _FORCE for this parameter, _udestroy destroys the heap regardless of whether allocated objects remain in that process or in any other process that shares the heap. If you specify !_FORCE, the heap will not be destroyed if any objects are still allocated from it.

  Typically, you call _uclose to close the heap before you destroy it. After you have destroyed a heap, any attempt to access it will have undefined results.

  You cannot destroy The Developer's Toolkit run-time heap (_RUNTIME_HEAP).

Returns

• udestroy returns 0 whether the heap was destroyed or not. If the heap passed to it is not valid, _udestroy returns a nonzero value.
Example Code

The following example creates and opens a heap, performs operations on it, and then closes it. The program then calls _udestroy with the _FORCE parameter to force the destruction of the heap. _udestroy calls release_fn to return the memory to the system.

#define  INCL_DOSMEMMGR             /* Memory Manager values */
#include <os2.h>
#include <bsememf.h>                /* Get flags for memory management  */
#include <stdlib.h>
#include <stdio.h>
#include <umalloc.h>

static void *get_fn(Heap_t usrheap, size_t *length, int *clean)
{
   void *p;

   /* Round up to the next chunk size */
   *length = ((*length) / 65536) * 65536 + 65536;
   *clean = _BLOCK_CLEAN;
   DosAllocMem(&p, *length, PAG_COMMIT | PAG_READ | PAG_WRITE);
   return (p);
}

static void release_fn(Heap_t usrheap, void *p, size_t size)
{
   DosFreeMem(p);
   return;
}

int main(void)
{
   void    *initial_block;
   APIRET  rc;
   Heap_t  myheap;
   char    *ptr;

   /* Call DosAllocMem to get the initial block of memory */
   if (0 != (rc = DosAllocMem(&initial_block, 65536,
                              PAG_WRITE | PAG_READ | PAG_COMMIT))) {
      printf("DosAllocMem error: return code = %ld\n", rc);
      exit(EXIT_FAILURE);
   }
   /* Create an expandable heap starting with the block declared earlier */
   if (NULL == (myheap = _ucreate(initial_block, 65536, _BLOCK_CLEAN,
                                  _HEAP_REGULAR, get_fn, release_fn))) {
      puts("_ucreate failed.");
      exit(EXIT_FAILURE);
   }
   if (0 != _uopen(myheap)) {
      puts("_uopen failed.");
      exit(EXIT_FAILURE);
   }

   /* Force user heap to grow */
   ptr = _umalloc(myheap, 100000);

   _uclose(myheap);

   if (0 != _udestroy(myheap, _FORCE)) {
      puts("_udestroy failed.");
      exit(EXIT_FAILURE);
   }
   if (0 != (rc = DosFreeMem(initial_block))) {
      printf("DosFreeMem error: return code = %ld\n", rc);
      exit(EXIT_FAILURE);
   }
   return 0;
}

Related Information

• uaddmem
  
• ucreate
  
• uopen
  
• uclose
  
• Differentiating between Memory Management Functions
  
• Managing Memory" in the VisualAge C++ Programming Guide

---

[Back: _udefault - Change the Default Heap]
[Next: _uheapchk - Validate Memory Heap]