_ucreate - Create a Memory Heap

Syntax

#include <umalloc.h>
Heap_t _ucreate(void *block, size_t initsz, int clean, int memtype,
                 void *(*getmore_fn)(Heap_t, size_t *, int *)
                 void  (*release_fn)(Heap_t, void *, size_t);

Description

• ucreate creates your own memory heap that you can allocate and free memory from, just like The Developer's Toolkit run-time heap.

  Before you call _ucreate, you must first get the initial block of memory for the heap. You can get this block by calling an OS/2 function (such as DosAllocMem or or DosAllocSharedMem) or by statically allocating it. (See the CP Programming Guide and Reference for more information on the OS/2 functions.)

  Note: You must also return this initial block of memory to the system after you destroy the heap.

  When you call _ucreate, you pass it the following parameters:

  block

  The pointer to the initial block you obtained.
  initsz
  The size of the initial block, which must be at least _HEAP_MIN_SIZE bytes (defined in <malloc.h>). If you are creating a fixed-size heap, the size must be large enough to satisfy all memory requests your program will make of it.
  clean
  The macro _BLOCK_CLEAN, if the memory in the block has been initialized to 0, or !_BLOCK_CLEAN, if the memory has not been touched. This improves the efficiency of _ucalloc; if the memory is already initialized to 0, _ucalloc does not need to initialize it.

  Note: DosAllocMem initializes memory to 0 for you. You can also use memset to initialize the memory; however, memset also commits all the memory at once, an action that could slow overall performance.

  memtype
  A macro indicating the type of memory in your heap: _HEAP_REGULAR (regular) or _HEAP_SHARED (shared). Shared memory can be shared between different processes. For more information on different types of memory, see the VisualAge C++ Programming Guide and the Control Program Guide and Reference.

  Note: Make sure that when you get the initial block, you request the same type of memory that you specify for memtype.

  getmore_fn
  A function you provide to get more memory from the system (typically using OS/2 functions or static allocation). To create a fixed-size heap, specify NULL for this parameter.
  release_fn
  A function you provide to return memory to the system (typically using DosFreeMem). To create a fixed-size heap, specify NULL for this parameter.

  If you create a fixed-size heap, the initial block of memory must be large enough to satisfy all allocation requests made to it. Once the block is fully allocated, further allocation requests to the heap will fail. If you create an expandable heap, the getmore_fn and release_fn allow your heap to expand and shrink dynamically.

  When you call _umalloc (or a similar function) for your heap, if not enough memory is available in the block, it calls the getmore_fn you provide. Your getmore_fn then gets more memory from the system and adds it to the heap, using any method you choose.

  Your getmore_fn must have the following prototype:

     void *(*getmore_fn)(Heap_t uh, size_t *size, int *clean);

  where: compact break=fit.

  uh

  Is the heap to get memory for.
  size
  Is the size of the allocation request passed by _umalloc. You probably want to return enough memory at a time to satisfy several allocations; otherwise, every subsequent allocation has to call getmore_fn. You should return multiples of 64K (the smallest size that DosAllocMem returns). Make sure you update the size parameter if you return more than the original request.
  clean
  Within getmore_fn, you must set this variable either to _BLOCK_CLEAN, to indicate that you initialized the memory to 0, or to !_BLOCK_CLEAN, to indicate that the memory is untouched.

  Note: Make sure your getmore_fn allocates the right type of memory for the heap.

  When you call _uheapmin to coalesce the heap or _udestroy to destroy it, these functions call the release_fn you provide to return the memory to the system. function.

  Your release_fn must have the following prototype:

     void (*release_fn)(Heap_t uh, void *block, size_t size);

  The heap uh the block is from, the block to be returned, and its size are passed to release_fn by _uheapmin or _udestroy.

  For more information about creating and using heaps, see the "Managing Memory" in the VisualAge C++ Programming Guide.

Returns

If successful, _ucreate returns a pointer to the heap created. If errors occur, _ucreate returns NULL.

Example Code

The following example uses _ucreate to create an expandable heap. The functions for expanding and shrinking the heap are get_fn and release_fn. The program then opens the heap and performs operations on it, and then closes and destroys the heap.

#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
  
• ucalloc
  
• uclose
  
• udestroy
  
• uheapmin
  
• umalloc
  
• uopen
  
• Differentiating between Memory Management Functions
  
• Managing Memory" in the VisualAge C++ Programming Guide

---

[Back: _uclose - Close Heap from Use]
[Next: _udefault - Change the Default Heap]