SHMALLOC(3P)

NAME
shmalloc, shrealloc, shfree - shared memory allocator

SYNOPSIS
C syntax:

char *shmalloc(size)
unsigned size;
shfree(ptr)
char *ptr;

char *shrealloc(ptr,size)
char *ptr;
unsigned size;

Pascal syntax

none

FORTRAN syntax

none

DESCRIPTION
shmalloc, shrealloc, and shfree provide a simple general-purpose shared memory allocation package for a set of processes executing a single application. To use these routines, the program must have been linked with the Parallel Programming Library. shmalloc returns a pointer to a block of at least size bytes beginning on a 4-byte word boundary.

The argument to shfree is a pointer to a block previously allocated by shmalloc; this space is made available for further allocation, but its contents are left undisturbed.

Clearly, grave disorder will result if the space assigned by shmalloc is overrun or if some random number is handed to shfree.

shmalloc maintains multiple lists of free blocks according to size, allocating space from the appropriate list. It calls shsbrk (see shbrk(3P)) to get more memory from the system when there is no suitable space already free. shmalloc and shfree coordinate the allocation of shared memory among the processes in the task. They maintain a consistent list of free blocks even when several processes are allocating shared memory concurrently. Concurrent requests for shared memory blocks always return unique blocks from the program's shared data segment.

shrealloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the (possibly moved) block. The contents will be unchanged up to the lesser of the new and old sizes. If ptr points to a freed block, shrealloc returns NULL.

When any of these allocation routines increases a program's address space, it also attempts to increase its allowable resident set size (see vm_ctl(2)).

DIAGNOSTICS
shmalloc returns a null pointer (0) if there is no available shared memory or if the region has been detectably corrupted by storing data outside the bounds of a block. shmalloc may be recompiled to check the arena very stringently on every transaction; those sites with a source code license may check the source code to see how this can be done.

SEE ALSO
shbrk(3P), vm_ctl(2), Guide to Parallel Programming