cantProceed.h File Reference

Routines for code that can't continue or return after an error. More...

#include <stdlib.h>
#include "compilerDependencies.h"
#include "libComAPI.h"

Include dependency graph for cantProceed.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
LIBCOM_API void	cantProceed (const char *errorMessage,...) EPICS_PRINTF_STYLE(1
	Suspend this thread, the caller cannot continue or return. More...
Memory Allocation Functions
These versions of calloc() and malloc() never fail, they suspend the thread if the OS is unable to allocate the requested memory at the current time. If the thread is resumed, they will re-try the memory allocation, and will only return after it succeeds. These routines should only be used while an IOC is starting up; code that runs after iocInit() should fail gracefully when memory runs out.
LIBCOM_API void *	callocMustSucceed (size_t count, size_t size, const char *errorMessage)
	A calloc() that never returns NULL. More...
LIBCOM_API void *	mallocMustSucceed (size_t size, const char *errorMessage)
	A malloc() that never returns NULL. More...

Detailed Description

Routines for code that can't continue or return after an error.

This is the EPICS equivalent of a Kernel Panic, except that the effect is to halt only the thread that detects the error.

Definition in file cantProceed.h.

Function Documentation

LIBCOM_API void* callocMustSucceed	(	size_t	count,
		size_t	size,
		const char *	errorMessage
	)

A calloc() that never returns NULL.

Parameters

count	Number of objects.
size	Size of each object.
errorMessage	What this memory is needed for.

Returns

Pointer to zeroed allocated memory.

Definition at line 22 of file cantProceed.c.

{
    void * mem = NULL;
    if (count > 0 && size > 0) {
        while ((mem = calloc(count, size)) == NULL) {
            errlogPrintf("%s: callocMustSucceed(%lu, %lu) - calloc failed\n",
                    msg, (unsigned long)count, (unsigned long)size);
            errlogPrintf("Thread %s (%p) suspending.\n",
                    epicsThreadGetNameSelf(), (void *)epicsThreadGetIdSelf());
            errlogFlush();
            epicsThreadSuspendSelf();
        }
    }
    return mem;
}

LIBCOM_API void cantProceed	(	const char *	errorMessage,
			...
	)

Suspend this thread, the caller cannot continue or return.

The effect of calling this is to print the error message followed by the name of the thread that is being suspended. A stack trace will also be shown if supported by the OS, and the thread is suspended inside an infinite loop.

Parameters

errorMessage	A printf-style error message describing the error.
...	Any parameters required for the error message.

LIBCOM_API void* mallocMustSucceed	(	size_t	size,
		const char *	errorMessage
	)

A malloc() that never returns NULL.

Parameters

size	Size of block to allocate.
errorMessage	What this memory is needed for.

Returns

Pointer to allocated memory.

Definition at line 38 of file cantProceed.c.

{
    void * mem = NULL;
    if (size > 0) {
        while ((mem = malloc(size)) == NULL) {
            errlogPrintf("%s: mallocMustSucceed(%lu) - malloc failed\n",
                msg, (unsigned long)size);
            errlogPrintf("Thread %s (%p) suspending.\n",
                    epicsThreadGetNameSelf(), (void *)epicsThreadGetIdSelf());
            errlogFlush();
            epicsThreadSuspendSelf();
        }
    }
    return mem;
}