NAME

alloc_limit_set_peak, alloc_limit_set_total, alloc_limit_set_no_limit - simulated out-of-memory errors

SYNOPSIS

#include <ipd_alloc_limit.h>

void
alloc_limit_set_peak( size_t size );

void
alloc_limit_set_total( size_t size );

void
alloc_limit_set_no_limit( void );

DESCRIPTION

The purpose of these functions is to simulate out-of-memory errors, so that you can test how your code handles them. In particular, these functions let you place a (temporary) limit on heap allocation, which will cause malloc(3) to return NULL rather than exceed the limit.

This API supports setting two kinds of allocation limits:

A peak allocation limit caps the total size of the heap, which means that each allocated object counts against the limit only until it is deallocated.
A total allocation limit caps the total number of bytes allocated, which means that allocations are charged against the limit, but deallocations do not restore the limit.

To set a peak allocation limit of n bytes, call alloc_limit_set_peak(n); to set a total allocation limit of n bytes, call alloc_limit_set_total(n). To remove the current allocation limit, if any, and restore malloc(3)'s usual behavior, call alloc_limit_set_no_limit().

When an allocation limit is set, it applies only to future allocations. This means that when you call alloc_limit_set_peak or alloc_limit_set_total, earlier allocations are forgotten and will not count against the new allocation limit.

Note that the accounting required by the above functions happens only in files where <ipd.h> is #included. This means that you need

#include <ipd.h>

in every source file that performs allocation or deallocation in order to use these functions effectively.

ENVIRONMENT

The functions documented herein are suitable for unit-testing of individual functions, but not for testing a whole program's out-of-memory behavior. For testing a whole program you can set a peak or total allocation limit at program startup by defining an environment variable from outside your program.

In particular, these two environment variables may be defined in order to set a allocation limit:

RTIPD_ALLOC_LIMIT_PEAK - Sets a peak allocation limit.
RTIPD_ALLOC_LIMIT_TOTAL - Sets a total allocation limit.

The value of either variable may be a number to specify the limit in bytes, or a number followed by the letter K, M, or G to specify the limit in KiB, MiB, or GiB, respectively.

For example, to run the program ./count with a peak allocation limit of 500 bytes, you could run

% RTIPD_ALLOC_LIMIT_PEAK=500 ./count

If both of the above environment variables are set then RTIPD_ALLOC_LIMIT_TOTAL takes precedence.

BUGS

Limiting peak memory makes deallocation slow. The treatment of realloc(3) is confusing. And probably several others.

AUTHOR

Jesse Tov <jesse@cs.northwestern.edu>