C Programming/MS Windows Reference/alloc.h

"alloc.h" is a non-standard header file. It is not part of the ANSI standard, and thus is not an ANSI C header file, but it exists in many C language dialects. It is available with Borland Turbo C and TIGCC. This header file provides operations regarding Dynamic Memory Allocation. This header file includes "memory management" functions.

Example usage

To use the functions in alloc.h , we must include alloc.h before we use them.

#include <stdio.h>
#include <alloc.h>

int main()
{
     int *ptr;
     
     ptr = (int *) alloca (sizeof(int));
     scanf("%d", ptr);
     printf("%d is stored dynamically.\n", *ptr);

     return 0;
}

Functions

Function Declaration	Function Purpose
`void *alloca (unsigned long Size);`	Allocates storage on stack memory.
`void *calloc (unsigned short NoOfItems, unsigned short SizeOfItems);`	Allocates memory storage for given number of elements, from the memory heap. The value at the space set for the variables is automatically initialized to zero.
`void *calloc_throw (unsigned short NoOfItems, unsigned short SizeOfItems);`	Calls `calloc` and throws an error if memory is not available. Otherwise it returns address returned by `calloc`.
`void *malloc (unsigned long Size);`	It allocates "Size" bytes memory in memory heap. It returns NULL on failure. This memory block can be deallocated by means of `free` function.
`void *malloc_throw (unsigned long Size);`	Calls `malloc` and throws an error if memory is not available. Otherwise it returns address returned by `malloc`.
`void realloc (void Ptr, unsigned long NewSize);`	Reallocates the memory block, previously allocated by `*Ptr`. It returns the address of newly reallocated memory block which may be different from `Ptr`. It returns NULL on failure.
`void realloc_throw (void Ptr, unsigned long NewSize);`	Calls `realloc` and throws an error if memory is not available. Otherwise it returns address returned by `realloc`.
`void free (void *Ptr);`	Deallocates memory allocated by `malloc` or `calloc` directly to the console.

Heap Memory Allocation Functions

Function Declaration	Function Purpose
`HANDLE HeapAlloc (unsigned long Size);`	It allocates Size bytes of heap of memory and returns handle. Size is taken as even. Odd sizes are rounded up. Allocated memory is kept in Singly linked list structure. Maximum size is 65520 bytes and minimum size is 6 bytes. It returns H_NULL on failure.
`HANDLE HeapAllocThrow (unsigned long Size);`	It calls `HeapAlloc` function and returns the corresponding handle. It throws an error on failure.
`HANDLE HeapAllocESTACK (unsigned long Size);`	If "Size" bytes memory is not available, it truncates expression stack. Even after reducing stack memory is not available it returns H_NULL.
`HANDLE HeapAllocHigh (unsigned long Size);`	It allocates the memory at the high end of memory heap and returns Handle. It moves all used blocks of memory down to heap. If memory is not available it returns H_NULL.
`HANDLE HeapAllocHighThrow (unsigned long Size);`	It calls `HeapAllocHigh` function and returns the handle. On failure it throws a memory error.
`void *HeapDeref (HANDLE Handle);`	It dereferences the handle and returns the memory address. To use the memory reserved by a handle, the handle must be dereferenced.
`void HeapFree (HANDLE Handle);`	It deallocates the memory allocated by the handle.
`void HeapFreeIndir (HANDLE *HandlePtr);`	It deallocates the block of memory associated with passed Handle and sets the Handle to NULL.
`void *HeapAllocPtr (unsigned long Size);`	It is very similar to `HeapAllocHigh`. It does the same job. But instead of returning a handle it returns pointer to an allocated block. It returns NULL on failure.
`void *HeapAllocPtrThrow (unsigned long Size);`	It calls `HeapAllocPtr` and returns the corresponding pointer. It throws an error on failure.
`void HeapFreePtr (void *Ptr);`	It deallocates the memory block allocated by `HeapAllocPtr`.

Miscellaneous Functions

Function Declaration	Function Purpose
`unsigned long HeapAvail (void);`	It returns the total number of available bytes in memory heap.
`void HeapCompress (void);`	It compresses all allocated heap memory blocks. If possible, it deletes free memory blocks. This function is generally called internally whenever necessary.
`void *HeapEnd (void);`	It returns the pointer to the end of memory heap.
`HANDLE HeapLock (HANDLE Handle);`	It locks the memory block allocated by the handle. It returns same handle on success otherwise `H_NULL`. Locking ensures the memory block is not moved or deleted during memory heap rearrangement.
`short HeapGetLock (HANDLE Handle);`	It determines whether the passed handle is locked. It returns 0 if block is not locked.
`void *HLock (HANDLE Handle);`	It locks as well as dereferences memory block reserved by the Handle.
`unsigned long HeapMax (void);`	It returns the maximum size of memory block that can be reserved.

Constants

Member Constants	Description
`H_NULL`	It is termed as null-handled. It is defined with zero value.
`NULL`	It is a null pointer. It points to address 0.

Predefined types

Bool

enum Bool {FALSE, TRUE};

It is an enumeration. It has defined two binary values false and true. Constant FALSE stands for logic 0 while constant TRUE stands for logic 1.

HANDLE

 typedef unsigned short HANDLE;

A handle represents an allocated, aligned block of memory. Its address can be retrieved by means of HeapDeref function in alloc.h. HANDLE is used for managing the memory allocated by the functions of alloc.h. Some functions from other header files use HANDLE as parameter.

Deviation from standards

The alloca function is different from the standard malloc function, in that malloc allocates memory in memory heap whereas alloca allocates it in stack memory. Hence, this storage is local. Within a function, if memory is allocated using alloca , it is deallocated automatically at the end of function. alloca is more preferred in applications which require local Dynamic Memory Allocation.

malloc allocates given byte-block in linear order. It requires continuous block of memory. HeapAlloc allocates memory which is stored in linked list structure. It is advantageous.

Many a times, memory blocks are reserved. The memory blocks which are locked for a long time should be moved high in the heap. This reduces interference of such blocks with rest of the system. This can be achieved by using HeapAllocHigh function. This rearranges the heap before requested memory allocation.

When we call malloc, memory manager assigns a pointer known as handle to allocated block. For each block Handles are assigned. So, when we want to use a large number of small size memory blocks, malloc is not quite efficient. Due to large number of Handles, handling becomes difficult. So, alloca is better option in such cases.

HeapRealloc function from "alloc.h" does the job similar to realloc. In case of, HeapRealloc if reallocation fails, it deallocates previously allocated memory. Usually, realloc keeps previously allocated memory block intact.

References