globopt.c File Reference

(2023-08-28, commit: c9b21e6)

Implementation of global option storage. More...

#include "globopt.h"
#include <pthread.h>
#include <stdlib.h>
#include "common.h"
#include "logio.h"

Include dependency graph for globopt.c:

Macros
#define	crinitGlobOptSetErrPrint(keyStr)   crinitErrPrint("Could not set default value for global option '%s'.", (keyStr))
#define	crinitGlobOptCommonLock()
#define	crinitGlobOptCommonUnlock()

Functions
int	crinitGlobOptInitDefault (void)
int	crinitGlobOptSetString (size_t memberOffset, const char *val)
int	crinitGlobOptGetString (size_t memberOffset, char **val)
int	crinitGlobOptSetBoolean (size_t memberOffset, bool val)
int	crinitGlobOptGetBoolean (size_t memberOffset, bool *val)
int	crinitGlobOptSetInteger (size_t memberOffset, int val)
int	crinitGlobOptGetInteger (size_t memberOffset, int *val)
int	crinitGlobOptSetUnsignedLL (size_t memberOffset, unsigned long long val)
int	crinitGlobOptGetUnsignedLL (size_t memberOffset, unsigned long long *val)
int	crinitGlobOptSetEnvSet (size_t memberOffset, const crinitEnvSet_t *val)
int	crinitGlobOptGetEnvSet (size_t memberOffset, crinitEnvSet_t *val)
crinitGlobOptStore_t *	crinitGlobOptBorrow (void)
int	crinitGlobOptRemit (void)
void	crinitGlobOptDestroy (void)

Variables
static crinitGlobOptStore_t	crinitGlobOpts
static pthread_mutex_t	crinitOptLock = PTHREAD_MUTEX_INITIALIZER

Detailed Description

Implementation of global option storage.

Macro Definition Documentation

crinitGlobOptCommonLock

#define crinitGlobOptCommonLock

(

)

Value:

    if (crinitGlobOptBorrow() == NULL) {                                            \
        crinitErrPrint("Could not get exclusive access to global option storage."); \
        return -1;                                                                  \
    }

Common boilerplate to acquire a lock on the global option storage.

crinitGlobOptCommonUnlock

#define crinitGlobOptCommonUnlock

(

)

Value:

    if (crinitGlobOptRemit() == -1) {                                                   \
        crinitErrPrint("Could not release exclusive access to global option storage."); \
        return -1;                                                                      \
    }

Common boilerplate to release a lock on the global option storage.

crinitGlobOptSetErrPrint

#define crinitGlobOptSetErrPrint

(

keyStr

)

crinitErrPrint("Could not set default value for global option '%s'.", (keyStr))

Common error message for crinitGlobOptInitDefault().

Function Documentation

crinitGlobOptBorrow()

crinitGlobOptStore_t* crinitGlobOptBorrow

(

void

)

Provide direct thread-safe access to the central global option storage.

Calling thread will hold an exclusive lock on the central instance of crinitGlobOptStore_t. After the calling thread has finished its operations on the global option storage, it must release the lock using crinitGlobOptRemit().

Returns

A pointer to the central instance of crinitGlobOptStore_t on success, a NULL pointer if the lock could not be acquired.

crinitGlobOptDestroy()

void crinitGlobOptDestroy

(

void

)

Deletes all set global options from storage.

Any allocated memory is freed. The function uses mutexes internally and is thread-safe.

crinitGlobOptGetBoolean()

int crinitGlobOptGetBoolean	(	size_t	memberOffset,
		bool *	val
	)

Retrieves a boolean value from a global option.

Consider using the type-generic macro crinitGlobOptGet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The global option to set.
val	Return pointer for the retrieved boolean value.

Returns

0 on success, -1 on error

crinitGlobOptGetEnvSet()

int crinitGlobOptGetEnvSet	(	size_t	memberOffset,
		crinitEnvSet_t *	val
	)

Retrieves a crinitEnvSet_t value from a global option.

Consider using the type-generic macro crinitGlobOptGet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The global option to set.
val	Pointer to the crinitEnvSet_t instance to which the global one will be duplicated.

Returns

0 on success, -1 on error

crinitGlobOptGetInteger()

int crinitGlobOptGetInteger	(	size_t	memberOffset,
		int *	val
	)

Retrieves an integer value from a global option.

Consider using the type-generic macro crinitGlobOptGet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The global option to set.
val	Return pointer for the retrieved integer value.

Returns

0 on success, -1 on error

crinitGlobOptGetString()

int crinitGlobOptGetString	(	size_t	memberOffset,
		char **	val
	)

Retrieves a string value from a global option.

Consider using the type-generic macro crinitGlobOptGet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Will allocate memory for the returned string. When no longer in use, free() should be called on the returned pointer to free the memory.

Parameters

memberOffset	The offset of the member of the global option struct to set.
val	Return pointer for the retrieved string. Memory will be allocated.

Returns

0 on success, -1 on error

crinitGlobOptGetUnsignedLL()

int crinitGlobOptGetUnsignedLL	(	size_t	memberOffset,
		unsigned long long *	val
	)

Retrieves an unsigned long long value from a global option.

Consider using the type-generic macro crinitGlobOptGet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The global option to set.
val	Return pointer for the unsigned long long integer value.

Returns

0 on success, -1 on error

crinitGlobOptInitDefault()

int crinitGlobOptInitDefault

(

void

)

Sets global options to their default values.

Uses crinitGlobOptSet() and is therefore thread-safe.

Returns

0 on success, -1 otherwise

crinitGlobOptRemit()

int crinitGlobOptRemit

(

void

)

Release the lock on the global option storage acquired via crinitGlobOptBorrow().

Returns

0 on success, -1 if the lock could not be released.

crinitGlobOptSetBoolean()

int crinitGlobOptSetBoolean	(	size_t	memberOffset,
		bool	val
	)

Stores a boolean value for a global option.

Consider using the type-generic macro crinitGlobOptSet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The global option to set.
val	The boolean value to store.

Returns

0 on success, -1 on error

crinitGlobOptSetEnvSet()

int crinitGlobOptSetEnvSet	(	size_t	memberOffset,
		const crinitEnvSet_t *	val
	)

Stores a crinitEnvSet_t value for a global option.

Consider using the type-generic macro crinitGlobOptSet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The global option to set.
val	Pointer to the crinitEnvSet_t which shall be stored.

Returns

0 on success, -1 on error

crinitGlobOptSetInteger()

int crinitGlobOptSetInteger	(	size_t	memberOffset,
		int	val
	)

Stores an integer value for a global option.

Consider using the type-generic macro crinitGlobOptSet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The global option to set.
val	The boolean value to store.

Returns

0 on success, -1 on error

crinitGlobOptSetString()

int crinitGlobOptSetString	(	size_t	memberOffset,
		const char *	val
	)

Stores a string value for a global option.

Consider using the type-generic macro crinitGlobOptSet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The offset of the member of the global option struct to set.
val	The string value to store, must be null-terminated.

Returns

0 on success, -1 on error

crinitGlobOptSetUnsignedLL()

int crinitGlobOptSetUnsignedLL	(	size_t	memberOffset,
		unsigned long long	val
	)

Stores an unsigned long long value for a global option.

Consider using the type-generic macro crinitGlobOptSet() which can be used with member names instead of offsets. Will lock the global option storage as long as needed and is thread-safe.

Parameters

memberOffset	The global option to set.
val	The unsigned long long integer value to store.

Returns

0 on success, -1 on error

Variable Documentation

crinitGlobOpts

crinitGlobOptStore_t crinitGlobOpts

static

Central global option storage.

crinitOptLock

pthread_mutex_t crinitOptLock = PTHREAD_MUTEX_INITIALIZER

static

Mutex to synchronize access to globOptArr