hppoolcreate

hppoolcreate

Allocate a Storage Pool from Heap

SYNOPSIS
DESCRIPTION
RETURN VALUE
ERRORS
DIAGNOSTICS
IMPLEMENTATION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <multheap.h>
int hppoolcreate(_heap_id heapid, POOL_t *p, 
                 unsigned eltsize, unsigned initial, 
                 unsigned extend)

DESCRIPTION

hppoolcreate creates a storage pool from which elements of a given size can be quickly allocated and freed. hppoolcreate differs from pool, in that it will allocate it's elements from a given heap. The arguments are as follows:

heapid is an ID returned from a call to hpcreate.

p is a pointer to a POOL_t structure.

eltsize is the size of the elements to be allocated.

initial is the number of elements the pool is to contain initially.

extend is the number by which the pool is extended if all elements are allocated.

If initial is 0, the hppoolcreate routine computes a convenient initial number of elements. If extend is 0, it is set equal to initial.

In a situation that requires allocation of many items of the same size, using a storage pool is more efficient than using malloc in terms of execution time. It also can be more efficient in terms of storage usage if the initial and extend values are reasonably chosen.

RETURN VALUE

The return value is 1 if a pool is successfully created, or 0 if it is not. If a pool is created, its address and other information is stored in the area addressed by the second argument to hppoolcreate.

ERRORS

User ABEND 1205 or 1206 may occur if memory management data areas are overlaid.

DIAGNOSTICS

The POOL_t pointer is set to 0 if there is no storage available for the new pool.

IMPLEMENTATION

See pool for a description of normal pool allocation. hppoolcreate is identical except for the fact that the heap can be chosen to be other than the current (default) heap.

EXAMPLE

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <multheap.h>

static POOL_t word_pool;

main()
{

   _heap_id id1;
   _heap_attr attr;
   int success;      

// create a user heap – shared and above
//  the bar

   hpattr(&attr);
   attr.flags = HPATTR_SHARED;     
   attr.amode = HPLOC_64;          
   attr.subpool = HPSUBPOOL_DEFAULT;              
   attr.initial = 1000000000;            
   attr.overflow = 0;            
   id1 = hpcreate(&attr, "Above The Bar1");  
   if (!id1)                       
   {                               
      WTP("error in hpcreate.\n"); 
      return -1;                   
   }                               
   WTP("id1 = %04hX\n", id1);

      /* Allocate a pool of binary tree elements */                 
      /* to hold some "words". */                                    
   success = hppoolcreate(id1, &word_pool, sizeof(word_t), 100, 100)
   if (!success) {                                                  
      puts("Can't allocate word pool.");                            
      exit(4);                                                      
   }                                                          
}

RELATED FUNCTIONS

malloc, pool, hppoolcreate

SEE ALSO

"Memory Allocation Functions" in Chapter 2, "Function Categories" of the SAS/C Library Reference, Volume 1.

Chapter Contents
Previous
Next
Top of Page

`heapid`	is an ID returned from a call to `hpcreate`.
`p`	is a pointer to a `POOL_t` structure.
`eltsize`	is the size of the elements to be allocated.
`initial`	is the number of elements the pool is to contain initially.
`extend`	is the number by which the pool is extended if all elements are allocated.