liboom 1.0.1
Debugging helper library with Memory leak detection
oomfill.h File Reference

Library safely (rlimited) consumming RAM to trigger OOMs (only on POSIX systems) More...

#include <stddef.h>
Include dependency graph for oomfill.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations

enum  bool { false = (0==1) , true = (1==1) }
 

Functions

size_t oomfill_config (const size_t hardlimit)
 Sets the oomfill helpers hard rlimit and enables the oomfill helper features. More...
 
bool oomfill_enabled ()
 

Variables

size_t(* oomfill_enable )(const size_t softlimit)
 Starts a new oomfill environment or reconfigure the soft limit. More...
 
size_t(* oomfill_disable )()
 Stops the current oomfill. More...
 
size_t(* oomfill_fill )(const size_t minHeap, const size_t minStack)
 Starts an almost OOM single and simple test. More...
 
void(* oomfill_free )()
 Ends a single simple OOM test. More...
 

Detailed Description

Library safely (rlimited) consumming RAM to trigger OOMs (only on POSIX systems)

void myfunction() {
void* ptr = NULL;
// Keep at most 100 bytes available in heap, 4 in stack
oomfill_fill(100,4);
ptr=malloc(2000);
// Actual test outside of the constrained code to avoid failure
if (NULL == ptr)
fprintf(stderr,"malloc failed\n");
else
free(ptr);
}
size_t ramlimit;
ramlimit=64*1024*1024;
printf ("Limit memory usage to %uMB : ",ramlimit/1024/1024);
ramlimit = oomfill_config(ramlimit);
printf ("%uB (%uMB)\n",ramlimit,ramlimit/1024/1024);
// not constrained (only by the 64MB ramlimit)
myfunction();
// OOM activation to allow memory eating with a safeguard
oomfill_enable(16*1024*1024);
myfunction();
size_t(* oomfill_disable)()
Stops the current oomfill.
Definition: oomfill.c:210
size_t(* oomfill_enable)(const size_t softlimit)
Starts a new oomfill environment or reconfigure the soft limit.
Definition: oomfill.c:171
size_t(* oomfill_fill)(const size_t minHeap, const size_t minStack)
Starts an almost OOM single and simple test.
Definition: oomfill.c:96
void(* oomfill_free)()
Ends a single simple OOM test.
Definition: oomfill.c:125
size_t oomfill_config(const size_t hardlimit)
Sets the oomfill helpers hard rlimit and enables the oomfill helper features.
Definition: oomfill.c:457
void * malloc(size_t size)
stdc malloc stub function
Definition: oomstub.c:87
Author
François Cerbelle (Fanfan), franc.nosp@m.ois@.nosp@m.cerbe.nosp@m.lle..nosp@m.net

Definition in file oomfill.h.

Enumeration Type Documentation

◆ bool

enum bool
Enumerator
false 
true 

Definition at line 58 of file oomfill.h.

Function Documentation

◆ oomfill_config()

size_t oomfill_config ( const size_t  hardlimit)

Sets the oomfill helpers hard rlimit and enables the oomfill helper features.

This function needs to be invoqued BEFORE any other helper from the framework. It will configure an hard RAM limit for the current process and each of his children. Then, it will enable the other oomfill helper functions.

It refuses to set a limit over the actually installed physical RAM to limit pushing RAM pages to the swap. If the requested value is zero, it will default to the actually installed physical RAM.

If anything goes wrong or did not behaves as expected, it abort the process to avoid RAM bombing and swapping.

Despite it was designed to be invoked only once, from the main parent process, it can be invoked several times as long as the hardlimit parameter is always less than the previous call, otherwise it will fail and abort the process.

Parameters
[in]hardlimitthe size in bytes to limit the process to.
Returns
Returns the actual configured size. It should be the same value as the hardlimit parameter, otherwise something went wrong, it was not detected and the process was not aborted (which is a bug to report)
See also
oomfill_enable
oomfill_disable
oomfill_fill
oomfill_free

Definition at line 457 of file oomfill.c.

◆ oomfill_enabled()

bool oomfill_enabled ( )

Definition at line 511 of file oomfill.c.

Variable Documentation

◆ oomfill_disable

size_t(* oomfill_disable) () ( )
extern

Stops the current oomfill.

This function can be invoked any time after the oomfill_config initialized the environment. If invocated before, it will abort the current process to help detecting mistakes in the test code.

This function disables the fill/free oomfill functions and free the allocated RAM before reverting the soft limit to the hard limit value.

It is designed to be invoked t the end of a test case.

Despite it could be invoked twice or without a prior call to oomfill_enable, it is illegal and not allowed to help detecting mistakes in the test code.

Returns
Returns the applied soft limit, which should be the same as the hard limit.
See also
oomfill_enable
oomfill_disable
oomfill_fill
oomfill_free

Definition at line 210 of file oomfill.c.

◆ oomfill_enable

size_t(* oomfill_enable) (const size_t softlimit) ( const size_t  softlimit)
extern

Starts a new oomfill environment or reconfigure the soft limit.

This function can only be invoked after at least a first call to oomfill_config to initialize the oomfill helpers environment. If invocated before, it will abort the current process to help detecting mistakes in the test code.

It will (soft)limit the current process and his children to the provided value in bytes. Then, it will enable the fill/free oomfill helper functions which are disabled otherwise.

It is designed to be invoked at the begining of a test case to apply for all tests in this testcase.

In case of any unexpected behavior, it should abort the current process.

Parameters
[in]softlimitSoft limit to set in bytes. It has to be less than the hardlimit otherwise it will fail and abort. If set to 0, it will apply the same value as the hardlimit.
Returns
Returns the actually set value as a softlimit, either the requested value or the hardlimit in case of 0 requested.
See also
oomfill_enable
oomfill_disable
oomfill_fill
oomfill_free

Definition at line 171 of file oomfill.c.

◆ oomfill_fill

size_t(* oomfill_fill) (const size_t minHeap, const size_t minStack) ( const size_t  minHeap,
const size_t  minStack 
)
extern

Starts an almost OOM single and simple test.

This function is only enabled after a call to oomfill_enable and will have no effect otherwise. Its goal is to completely fill the RAM until the very last bytes, to keep only between minHeap and maxHeap bytes available in the heap and minStack bytes in the stack.

If oomfill_enable was not invoked beforehand, this function will simply return without any RAM consumption.

It should be called immediately before the test and should be reverted with oomfill_free immediately after. It can create so much pressure on the available memory that a simple printf could fail.

It is designed to fail if invoked twice as this is very probably a mistake in the test code. Should you need to change the RAM filling values, first call oomfill_free and reapply oomfill_fill. This ensure a really wanted behavior and not a mistake in your test code.

Parameters
[in]minHeap
[in]minStack
Returns
Returns the allocated size to fill the memory
See also
oomfill_enable
oomfill_disable
oomfill_fill
oomfill_free

Definition at line 96 of file oomfill.c.

◆ oomfill_free

void(* oomfill_free) () ( )
extern

Ends a single simple OOM test.

If this function is invoked between an oomfill_enable and an oomfill_disable invocations, it deallocates the RAM allocated by the oomfill_fill function. It should be called immediately after the single and simple test because the RAM pressure can even make a printf to fail.

If called without a prior oomfill_enable invocation, this function simply returns without any action.

This function is designed to fail and abort the process if invocated whereas there is no current RAM allocated, when called twice, for example. This helps to avoid mistakes in the test scenario.

Definition at line 125 of file oomfill.c.