memory.h File Reference

Functions for controlling memory allocation during execution. More...

Go to the source code of this file.

Functions
STUMPLESS_PUBLIC_FUNCTION void	stumpless_free_all (void)
	Closes the default target if it has been opened, frees all memory allocated internally, and performs any other necessary cleanup.
STUMPLESS_PUBLIC_FUNCTION void	stumpless_free_thread (void)
	Frees all memory allocated internally to the calling thread, and performs any other thread-specific cleanup.

Variables
STUMPLESS_PUBLIC_FUNCTION void *(*)(size_t)	stumpless_set_malloc (void *(*malloc_func)(size_t))
	Sets the function used by the library to allocate memory.
STUMPLESS_PUBLIC_FUNCTION void(*)(void *)	stumpless_set_free (void(*free_func)(void *))
	Sets the function used by the library to free memory.
STUMPLESS_PUBLIC_FUNCTION void *(*)(void *, size_t)	stumpless_set_realloc (void *(*realloc_func)(void *, size_t))
	Sets the function used by the library to reallocate memory.

Detailed Description

Functions for controlling memory allocation during execution.

Some of these functions allow memory allcoation to use custom functions. This might be useful if you have your own memory allocation routines or want to lay down your own controls over memory used by the library. For example, this capability is used extensively to test for error handling in memory allocation failure scenarios, as well as to ensure that the same amount of memory is freed as is allocated.

Function Documentation

stumpless_free_all()

STUMPLESS_PUBLIC_FUNCTION void stumpless_free_all

(

void

)

Closes the default target if it has been opened, frees all memory allocated internally, and performs any other necessary cleanup.

This function serves as a final exit function, which should be called when an application using the library is preparing to exit or when the library is no longer needed. Before this function is called, all targets explicitly opened must be closed (with the exception of the default target, which is opened implicitly) and no pointers to any structs should be retained. Failing to do this will result in undefined behavior.

Calling other functions after a call to this function is acceptable, however execution times may be longer than usual as memory used to cache objects may need to be allocated. If other functions are called, this function should be called again before exit to ensure a memory leak does not exist.

Thread Safety: MT-Unsafe This function is not thread safe as it destroys resources that other threads might be using.

Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers due to the use of the memory deallocation function to release memory.

Async Cancel Safety: AC-Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, as the memory deallocation function may not be AC-Safe itself.

Examples

basic_example.c, chain_example.c, entry_example.c, file_example.c, filter_example.c, function_example.c, journald_example.c, severity_level_example.c, socket_example.c, sqlite3_example.c, stream_example.c, tcp_example.c, and udp_example.c.

stumpless_free_thread()

STUMPLESS_PUBLIC_FUNCTION void stumpless_free_thread

(

void

)

Frees all memory allocated internally to the calling thread, and performs any other thread-specific cleanup.

This function should be called in any thread that has used stumpless functions before it exits so that caches and other structures can be cleaned up. It is not a substitute for stumpless_free_all, but is called by it and can be left out if stumpless_free_all will be called later in the same thread.

Thread Safety: MT-Safe This function is thread safe as it only operates on thread-local resources.

Async Signal Safety: AS-Unsafe heap This function is not safe to call from signal handlers due to the use of the memory deallocation function to release memory.

Async Cancel Safety: AC-Unsafe heap This function is not safe to call from threads that may be asynchronously cancelled, as the memory deallocation function may not be AC-Safe itself.

Variable Documentation

stumpless_set_free

STUMPLESS_PUBLIC_FUNCTION void(*)(void *) stumpless_set_free(void(*free_func)(void *))

(

void(*

free_func )(void *)

)

Sets the function used by the library to free memory.

The provided free function must be able to handle a NULL pointer as the provided argument.

Thread Safety: MT-Unsafe This function is not thread safe as it changes the memory allocation scheme, which could cause an operation to use the old function for some allocation and the new function for others. If you need to set any of the memory management functions, it should be done before starting multiple threads with access to shared resources.

Async Signal Safety: AS-Unsafe This function is not safe to call from signal handlers for the same reason as it is not thread safe.

Async Cancel Safety: AC-Unsafe This function is not safe to call from threads that may be asynchronously cancelled, as the assignment is not guaranteed to be atomic.

Parameters

free_func

A pointer to the memory deallocation function that is desired. This function must have the same signature as the standard library free function (which is the default if this is not called).

Returns

The new deallocation function.

stumpless_set_malloc

STUMPLESS_PUBLIC_FUNCTION void *(*)(size_t) stumpless_set_malloc(void *(*malloc_func)(size_t))

(

void *(*

malloc_func )(size_t)

)

Sets the function used by the library to allocate memory.

Thread Safety: MT-Unsafe This function is not thread safe as it changes the memory allocation scheme, which could cause an operation to use the old function for some allocation and the new function for others. If you need to set any of the memory management functions, it should be done before starting multiple threads with access to shared resources.

Async Signal Safety: AS-Unsafe This function is not safe to call from signal handlers for the same reason as it is not thread safe.

Async Cancel Safety: AC-Unsafe This function is not safe to call from threads that may be asynchronously cancelled, as the assignment is not guaranteed to be atomic.

Parameters

malloc_func

A pointer to the allocation function that is desired. This function must have the same signature as the standard library malloc function (which is the default if this is not called).

Returns

The new allocation function.

stumpless_set_realloc

STUMPLESS_PUBLIC_FUNCTION void *(*)(void *, size_t) stumpless_set_realloc(void *(*realloc_func)(void *, size_t))

(

void *(*

realloc_func )(void *, size_t)

)

Sets the function used by the library to reallocate memory.

Thread Safety: MT-Unsafe This function is not thread safe as it changes the memory allocation scheme, which could cause an operation to use the old function for some allocation and the new function for others. If you need to set any of the memory management functions, it should be done before starting multiple threads with access to shared resources.

Async Signal Safety: AS-Unsafe This function is not safe to call from signal handlers for the same reason as it is not thread safe.

Async Cancel Safety: AC-Unsafe This function is not safe to call from threads that may be asynchronously cancelled, as the assignment is not guaranteed to be atomic.

Parameters

realloc_func

A pointer to the memory reallocation function that is desired. This function must have the same signature as the standard library realloc function (which is the default if this is not called).

Returns

The new reallocation function.