Support for process management (memory allocation, logging, etc.) More...

#include <sc_config.h>
#include <math.h>
#include <ctype.h>
#include <float.h>
#include <limits.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdio.h>
#include <sc_mpi.h>

Include dependency graph for sc.h:

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

Go to the source code of this file.

Macros
#define	_GNU_SOURCE

#define	_sc_const const
	Portable way to work with really old compilers without const.

#define	_sc_restrict restrict
	Portable way to work with really old compilers without restrict.

#define	SC_CALC_VERSION(major, minor, patchlevel) (((major) * 1000 + (minor)) * 1000 + (patchlevel))
	Test for gcc version without features.h.

#define	SC_GCC_VERSION SC_CALC_VERSION (0, 0, 0)
	Assemble GCC version using a 1000-per-digit scheme.

#define	SC_NOCOUNT_MALLOC

#define	SC_NOCOUNT_REFCOUNT

#define	SC_NOCOUNT_LOGINDENT

#define	SC_DLL_PUBLIC

#define	__STDC_LIMIT_MACROS
	Activate C99 limit macros for older C++ compilers.

#define	__STDC_CONSTANT_MACROS
	Activate C99 constant macros for older C++ compilers.

#define	_USE_MATH_DEFINES

#define	M_E 2.71828182845904523536

#define	M_LOG2E 1.44269504088896340736

#define	M_LOG10E 0.434294481903251827651

#define	M_LN2 0.693147180559945309417

#define	M_LN10 2.30258509299404568402

#define	M_PI 3.14159265358979323846

#define	M_PI_2 1.57079632679489661923

#define	M_PI_4 0.785398163397448309616

#define	M_1_PI 0.318309886183790671538

#define	M_2_PI 0.636619772367581343076

#define	M_2_SQRTPI 1.12837916709551257390

#define	M_SQRT2 1.41421356237309504880

#define	M_SQRT1_2 0.707106781186547524401

#define	SC_INIT_COMM_CLEAN
	Indicate that we do not modify the communicator in sc_init.

#define	SC_NOARGS
	For compatibility of varargs with C++.

#define	SC_EPS 2.220446049250313e-16
	Define machine epsilon for the double type.

#define	SC_1000_EPS (1000. * 2.220446049250313e-16)
	Define 1000 times the machine epsilon for the double type.

#define	SC_NOOP() ((void) (0))
	A macro to do and return nothing as an expression.

#define	SC_ABORT(s) sc_abort_verbose (__FILE__, __LINE__, (s))

#define	SC_ABORT_NOT_REACHED() SC_ABORT ("Unreachable code")

#define	SC_CHECK_ABORT(q, s) ((q) ? (void) 0 : SC_ABORT (s))

#define	SC_CHECK_MPI(r) SC_CHECK_ABORT ((r) == sc_MPI_SUCCESS, "MPI error")

#define	SC_ABORTF(fmt, ...) sc_abort_verbosef (__FILE__, __LINE__, (fmt), __VA_ARGS__)

#define	SC_CHECK_ABORTF(q, fmt, ...) ((q) ? (void) 0 : SC_ABORTF (fmt, __VA_ARGS__))

#define	SC_ABORT1(fmt, a) sc_abort_verbosef (__FILE__, __LINE__, (fmt), (a))

#define	SC_ABORT2(fmt, a, b) sc_abort_verbosef (__FILE__, __LINE__, (fmt), (a), (b))

#define	SC_ABORT3(fmt, a, b, c) sc_abort_verbosef (__FILE__, __LINE__, (fmt), (a), (b), (c))

#define	SC_ABORT4(fmt, a, b, c, d) sc_abort_verbosef (__FILE__, __LINE__, (fmt), (a), (b), (c), (d))

#define	SC_ABORT5(fmt, a, b, c, d, e) sc_abort_verbosef (__FILE__, __LINE__, (fmt), (a), (b), (c), (d), (e))

#define	SC_ABORT6(fmt, a, b, c, d, e, f) sc_abort_verbosef (__FILE__, __LINE__, (fmt), (a), (b), (c), (d), (e), (f))

#define	SC_CHECK_ABORT1(q, fmt, a) ((q) ? (void) 0 : SC_ABORT1 ((fmt), (a)))

#define	SC_CHECK_ABORT2(q, fmt, a, b) ((q) ? (void) 0 : SC_ABORT2 ((fmt), (a), (b)))

#define	SC_CHECK_ABORT3(q, fmt, a, b, c) ((q) ? (void) 0 : SC_ABORT3 ((fmt), (a), (b), (c)))

#define	SC_CHECK_ABORT4(q, fmt, a, b, c, d) ((q) ? (void) 0 : SC_ABORT4 ((fmt), (a), (b), (c), (d)))

#define	SC_CHECK_ABORT5(q, fmt, a, b, c, d, e) ((q) ? (void) 0 : SC_ABORT5 ((fmt), (a), (b), (c), (d), (e)))

#define	SC_CHECK_ABORT6(q, fmt, a, b, c, d, e, f) ((q) ? (void) 0 : SC_ABORT6 ((fmt), (a), (b), (c), (d), (e), (f)))

#define	SC_ASSERT(c) SC_NOOP ()

#define	SC_EXECUTE_ASSERT_FALSE(expression) do { (void) (expression); } while (0)

#define	SC_EXECUTE_ASSERT_TRUE(expression) do { (void) (expression); } while (0)

#define	SC_ALLOC(t, n) (t ) sc_malloc (sc_package_id, (n) sizeof(t))

#define	SC_ALLOC_ZERO(t, n)

#define	SC_REALLOC(p, t, n)

#define	SC_STRDUP(s) sc_strdup (sc_package_id, (s))

#define	SC_FREE(p) sc_free (sc_package_id, (p))

#define	SC_ALIGN_UP(x, n) ( ((n) <= 0) ? (x) : ((x) + (n) - 1) / (n) * (n) )

#define	SC_ARG_ALIGN(p, t, n) SC_NOOP ()

#define	SC_ATTR_ALIGN(n)

#define	SC_BZERO(p, n) ((void) memset ((p), 0, (n) * sizeof (*(p))))
	Sets n elements of a memory range to zero. More...

#define	SC_MIN(a, b) (((a) < (b)) ? (a) : (b))

#define	SC_MAX(a, b) (((a) > (b)) ? (a) : (b))

#define	SC_SQR(a) ((a) * (a))

#define	SC_LOG2_8(x) (sc_log2_lookup_table[(x)])

#define	SC_LOG2_16(x)

#define	SC_LOG2_32(x)

#define	SC_LOG2_64(x)

#define	SC_ROUNDUP2_32(x) (((x) <= 0) ? 0 : (1 << (SC_LOG2_32 ((x) - 1) + 1)))

#define	SC_ROUNDUP2_64(x) (((x) <= 0) ? 0 : (1LL << (SC_LOG2_64 ((x) - 1LL) + 1)))

#define	SC_LC_GLOBAL 1
	log only for master process

#define	SC_LC_NORMAL 2
	log for every process

#define	SC_LP_DEFAULT (-1)
	Selects the SC default threshold.

#define	SC_LP_ALWAYS 0
	Log absolutely everything.

#define	SC_LP_TRACE 1
	Prefix file and line number.

#define	SC_LP_DEBUG 2
	Any information on the internal state.

#define	SC_LP_VERBOSE 3
	Information on conditions, decisions.

#define	SC_LP_INFO 4
	Most relevant things a function is doing.

#define	SC_LP_STATISTICS 5
	Important for consistency/performance.

#define	SC_LP_PRODUCTION 6
	A few lines at most for a major api function.

#define	SC_LP_ESSENTIAL 7
	Log a few lines max (version info) per program.

#define	SC_LP_ERROR 8
	Log errors only. More...

#define	SC_LP_SILENT 9
	Never log anything. More...

#define	SC_LP_THRESHOLD SC_LP_INFO
	The log threshold chosen by SC_LP_DEFAULT.

#define	SC_LP_APPLICATION SC_LP_STATISTICS
	This threshold is intended for applications with conservative logging.

#define	SC_GEN_LOG(package, category, priority, s)

#define	SC_GLOBAL_LOG(p, s) SC_GEN_LOG (sc_package_id, SC_LC_GLOBAL, (p), (s))

#define	SC_LOG(p, s) SC_GEN_LOG (sc_package_id, SC_LC_NORMAL, (p), (s))

#define	SC_GEN_LOGF(package, category, priority, fmt, ...)

#define	SC_GLOBAL_LOGF(p, fmt, ...) SC_GEN_LOGF (sc_package_id, SC_LC_GLOBAL, (p), (fmt), __VA_ARGS__)

#define	SC_LOGF(p, fmt, ...) SC_GEN_LOGF (sc_package_id, SC_LC_NORMAL, (p), (fmt), __VA_ARGS__)

#define	SC_GLOBAL_TRACE(s) SC_GLOBAL_LOG (SC_LP_TRACE, (s))

#define	SC_GLOBAL_LDEBUG(s) SC_GLOBAL_LOG (SC_LP_DEBUG, (s))

#define	SC_GLOBAL_VERBOSE(s) SC_GLOBAL_LOG (SC_LP_VERBOSE, (s))

#define	SC_GLOBAL_INFO(s) SC_GLOBAL_LOG (SC_LP_INFO, (s))

#define	SC_GLOBAL_STATISTICS(s) SC_GLOBAL_LOG (SC_LP_STATISTICS, (s))

#define	SC_GLOBAL_PRODUCTION(s) SC_GLOBAL_LOG (SC_LP_PRODUCTION, (s))

#define	SC_GLOBAL_ESSENTIAL(s) SC_GLOBAL_LOG (SC_LP_ESSENTIAL, (s))

#define	SC_GLOBAL_LERROR(s) SC_GLOBAL_LOG (SC_LP_ERROR, (s))

#define	SC_GLOBAL_TRACEF(fmt, ...) SC_GLOBAL_LOGF (SC_LP_TRACE, (fmt), __VA_ARGS__)

#define	SC_GLOBAL_LDEBUGF(fmt, ...) SC_GLOBAL_LOGF (SC_LP_DEBUG, (fmt), __VA_ARGS__)

#define	SC_GLOBAL_VERBOSEF(fmt, ...) SC_GLOBAL_LOGF (SC_LP_VERBOSE, (fmt), __VA_ARGS__)

#define	SC_GLOBAL_INFOF(fmt, ...) SC_GLOBAL_LOGF (SC_LP_INFO, (fmt), __VA_ARGS__)

#define	SC_GLOBAL_STATISTICSF(fmt, ...) SC_GLOBAL_LOGF (SC_LP_STATISTICS, (fmt), __VA_ARGS__)

#define	SC_GLOBAL_PRODUCTIONF(fmt, ...) SC_GLOBAL_LOGF (SC_LP_PRODUCTION, (fmt), __VA_ARGS__)

#define	SC_GLOBAL_ESSENTIALF(fmt, ...) SC_GLOBAL_LOGF (SC_LP_ESSENTIAL, (fmt), __VA_ARGS__)

#define	SC_GLOBAL_LERRORF(fmt, ...) SC_GLOBAL_LOGF (SC_LP_ERROR, (fmt), __VA_ARGS__)

#define	SC_TRACE(s) SC_LOG (SC_LP_TRACE, (s))

#define	SC_LDEBUG(s) SC_LOG (SC_LP_DEBUG, (s))

#define	SC_VERBOSE(s) SC_LOG (SC_LP_VERBOSE, (s))

#define	SC_INFO(s) SC_LOG (SC_LP_INFO, (s))

#define	SC_STATISTICS(s) SC_LOG (SC_LP_STATISTICS, (s))

#define	SC_PRODUCTION(s) SC_LOG (SC_LP_PRODUCTION, (s))

#define	SC_ESSENTIAL(s) SC_LOG (SC_LP_ESSENTIAL, (s))

#define	SC_LERROR(s) SC_LOG (SC_LP_ERROR, (s))

#define	SC_TRACEF(fmt, ...) SC_LOGF (SC_LP_TRACE, (fmt), __VA_ARGS__)

#define	SC_LDEBUGF(fmt, ...) SC_LOGF (SC_LP_DEBUG, (fmt), __VA_ARGS__)

#define	SC_VERBOSEF(fmt, ...) SC_LOGF (SC_LP_VERBOSE, (fmt), __VA_ARGS__)

#define	SC_INFOF(fmt, ...) SC_LOGF (SC_LP_INFO, (fmt), __VA_ARGS__)

#define	SC_STATISTICSF(fmt, ...) SC_LOGF (SC_LP_STATISTICS, (fmt), __VA_ARGS__)

#define	SC_PRODUCTIONF(fmt, ...) SC_LOGF (SC_LP_PRODUCTION, (fmt), __VA_ARGS__)

#define	SC_ESSENTIALF(fmt, ...) SC_LOGF (SC_LP_ESSENTIAL, (fmt), __VA_ARGS__)

#define	SC_LERRORF(fmt, ...) SC_LOGF (SC_LP_ERROR, (fmt), __VA_ARGS__)

#define	_SC_TOSTRING(x) #x
	Macros used to convert a macro definition such as the point version or some other numerical literal to a string.

#define	SC_TOSTRING(x) _SC_TOSTRING(x)
	Macros used to convert a macro definition such as the point version or some other numerical literal to a string.

Typedefs
typedef void(*	sc_log_handler_t) (FILE log_stream, const char filename, int lineno, int package, int category, int priority, const char *msg)
	Type of the log handler function.

typedef void(*	sc_abort_handler_t) (void)
	Type of the abort handler function.

Functions
void	SC_ABORTF (const char *fmt,...)

void	SC_CHECK_ABORTF (int success, const char *fmt,...)

void	SC_GEN_LOGF (int package, int category, int priority, const char *fmt,...)

void	SC_GLOBAL_LOGF (int priority, const char *fmt,...)

void	SC_LOGF (int priority, const char *fmt,...)

void	SC_GLOBAL_TRACEF (const char *fmt,...)

void	SC_GLOBAL_LDEBUGF (const char *fmt,...)

void	SC_GLOBAL_VERBOSEF (const char *fmt,...)

void	SC_GLOBAL_INFOF (const char *fmt,...)

void	SC_GLOBAL_STATISTICSF (const char *fmt,...)

void	SC_GLOBAL_PRODUCTIONF (const char *fmt,...)

void	SC_GLOBAL_ESSENTIALF (const char *fmt,...)

void	SC_GLOBAL_LERRORF (const char *fmt,...)

void	SC_TRACEF (const char *fmt,...)

void	SC_LDEBUGF (const char *fmt,...)

void	SC_VERBOSEF (const char *fmt,...)

void	SC_INFOF (const char *fmt,...)

void	SC_STATISTICSF (const char *fmt,...)

void	SC_PRODUCTIONF (const char *fmt,...)

void	SC_ESSENTIALF (const char *fmt,...)

void	SC_LERRORF (const char *fmt,...)

void *	sc_malloc (int package, size_t size)

void *	sc_calloc (int package, size_t nmemb, size_t size)

void *	sc_realloc (int package, void *ptr, size_t size)

char *	sc_strdup (int package, const char *s)

void	sc_free (int package, void *ptr)

int	sc_memory_status (int package)

void	sc_memory_check (int package)

int	sc_memory_check_noerr (int package)
	Return error count or zero if all is ok.

int	sc_int_compare (const void v1, const void v2)

int	sc_int8_compare (const void v1, const void v2)

int	sc_int16_compare (const void v1, const void v2)

int	sc_int32_compare (const void v1, const void v2)

int	sc_int64_compare (const void v1, const void v2)

int	sc_double_compare (const void v1, const void v2)

int	sc_atoi (const char *nptr)
	Safe version of the standard library atoi (3) function. More...

long	sc_atol (const char *nptr)
	Safe version of the standard library atol (3) function. More...

void	sc_set_log_defaults (FILE *log_stream, sc_log_handler_t log_handler, int log_threshold)
	Controls the default SC log behavior. More...

void	sc_set_abort_handler (sc_abort_handler_t abort_handler)
	Set the default SC abort behavior. More...

void	sc_log (const char filename, int lineno, int package, int category, int priority, const char msg)
	The central log function to be called by all packages. More...

void	sc_logf (const char filename, int lineno, int package, int category, int priority, const char fmt,...)
	The printf-style log function to be called by all packages. More...

void	sc_logv (const char filename, int lineno, int package, int category, int priority, const char fmt, va_list ap)
	The vprintf-style log function to be called by all packages. More...

void	sc_log_indent_push_count (int package, int count)
	Add spaces to the start of a package's default log format.

void	sc_log_indent_pop_count (int package, int count)
	Remove spaces from the start of a package's default log format.

void	sc_log_indent_push (void)
	Add one space to the start of sc's default log format.

void	sc_log_indent_pop (void)
	Remove one space from the start of a sc's default log format.

void	sc_abort (void)
	Print a stack trace, call the abort handler and then call abort ().

void	sc_abort_verbose (const char filename, int lineno, const char msg)
	Print a message to stderr and then call sc_abort ().

void	sc_abort_verbosef (const char filename, int lineno, const char fmt,...)
	Print a message to stderr and then call sc_abort ().

void	sc_abort_verbosev (const char filename, int lineno, const char fmt, va_list ap)
	Print a message to stderr and then call sc_abort ().

void	sc_abort_collective (const char *msg)
	Collective abort where only root prints a message.

int	sc_package_register (sc_log_handler_t log_handler, int log_threshold, const char name, const char full)
	Register a software package with SC. More...

int	sc_package_is_registered (int package_id)
	Query whether an identifier matches a registered package. More...

void	sc_package_lock (int package_id)
	Acquire a pthread mutex lock. More...

void	sc_package_unlock (int package_id)
	Release a pthread mutex lock. More...

void	sc_package_set_verbosity (int package_id, int log_priority)
	Set the logging verbosity of a registered package. More...

void	sc_package_set_abort_alloc_mismatch (int package_id, int set_abort)
	Set the unregister behavior of sc_package_unregister(). More...

void	sc_package_unregister (int package_id)
	Unregister a software package with SC. More...

void	sc_package_print_summary (int log_priority)
	Print a summary of all packages registered with SC. More...

void	sc_init (sc_MPI_Comm mpicomm, int catch_signals, int print_backtrace, sc_log_handler_t log_handler, int log_threshold)
	Sets the global program identifier (e.g. More...

int	sc_is_initialized (void)
	Return whether SC has been initialized or not. More...

int	sc_get_package_id (void)
	Query SC's own package identity. More...

void	sc_finalize (void)
	Unregisters all packages, runs the memory check, removes the signal handlers and resets sc_identifier and sc_root_*. More...

int	sc_finalize_noabort (void)
	Unregisters all packages, runs the memory check, removes the signal handlers and resets sc_identifier and sc_root_*. More...

int	sc_is_root (void)
	Identify the root process. More...

void	sc_strcopy (char dest, size_t size, const char src)
	Provide a string copy function. More...

void	sc_snprintf (char str, size_t size, const char format,...)
	Wrap the system snprintf function, allowing for truncation. More...

const char *	sc_version (void)
	Return the full version of libsc. More...

int	sc_version_major (void)
	Return the major version of libsc. More...

int	sc_version_minor (void)
	Return the minor version of libsc. More...

int	sc_is_littleendian (void)
	Perform a runtime check for the integer endian convention. More...

int	sc_have_zlib (void)
	Return a boolean indicating whether zlib has been configured. More...

int	sc_have_json (void)
	Return whether we have found a JSON library at configure time. More...

void	sc_sleep (unsigned milliseconds)
	Portable function to sleep a prescribed amount of milliseconds. More...

Variables
const int	sc_log2_lookup_table [256]
	Lookup table to provide fast base-2 logarithm of integers.

SC_DLL_PUBLIC int	sc_package_id
	libsc allows for multiple packages to use their own log priorities etc. More...

SC_DLL_PUBLIC FILE *	sc_trace_file
	Optional trace file for logging (see sc_init). More...

SC_DLL_PUBLIC int	sc_trace_prio
	Optional minimum log priority for messages that go into the trace file.

Detailed Description

Support for process management (memory allocation, logging, etc.)

Macro Definition Documentation

◆ SC_ALLOC_ZERO

#define SC_ALLOC_ZERO	(	t,
		n
	)

Value:

(t *) sc_calloc (sc_package_id, \

(size_t) (n), sizeof(t))

sc_package_id

SC_DLL_PUBLIC int sc_package_id

libsc allows for multiple packages to use their own log priorities etc.

◆ SC_BZERO

#define SC_BZERO	(	p,
		n
	)	((void) memset ((p), 0, (n) * sizeof (*(p))))

Sets n elements of a memory range to zero.

Assumes the pointer p is of the correct type.

◆ SC_GEN_LOG

#define SC_GEN_LOG	(	package,
		category,
		priority,
		s
	)

Value:

((priority) < SC_LP_THRESHOLD ? (void) 0 : \

sc_log (__FILE__, __LINE__, (package), (category), (priority), (s)))

SC_LP_THRESHOLD

#define SC_LP_THRESHOLD

The log threshold chosen by SC_LP_DEFAULT.

Definition: sc.h:468

◆ SC_GEN_LOGF

#define SC_GEN_LOGF	(	package,
		category,
		priority,
		fmt,
		...
	)

Value:

  ((priority) < SC_LP_THRESHOLD ? (void) 0 :                            \
   sc_logf (__FILE__, __LINE__, (package), (category), (priority),      \
            (fmt), __VA_ARGS__))

◆ SC_LOG2_16

#define SC_LOG2_16 ( x )

Value:

(((x) > 0xff) ? \

(SC_LOG2_8 ((x) >> 8) + 8) : SC_LOG2_8 (x))

◆ SC_LOG2_32

#define SC_LOG2_32 ( x )

Value:

(((x) > 0xffff) ? \

(SC_LOG2_16 ((x) >> 16)) + 16 : SC_LOG2_16 (x))

◆ SC_LOG2_64

#define SC_LOG2_64 ( x )

Value:

(((x) > 0xffffffffLL) ? \

(SC_LOG2_32 ((x) >> 32)) + 32 : SC_LOG2_32 (x))

◆ SC_REALLOC

#define SC_REALLOC	(	p,
		t,
		n
	)

Value:

(t *) sc_realloc (sc_package_id, \

(p), (n) * sizeof(t))

Function Documentation

◆ sc_atoi()

int sc_atoi ( const char * nptr )

Safe version of the standard library atoi (3) function.

Parameters

[in] nptr NUL-terminated string.

Returns: Converted integer value. 0 if no valid number. INT_MAX on overflow, INT_MIN on underflow.

◆ sc_atol()

long sc_atol ( const char * nptr )

Safe version of the standard library atol (3) function.

Parameters

[in] nptr NUL-terminated string.

Returns: Converted long value. 0 if no valid number. LONG_MAX on overflow, LONG_MIN on underflow.

◆ sc_finalize()

void sc_finalize ( void )

Unregisters all packages, runs the memory check, removes the signal handlers and resets sc_identifier and sc_root_*.

This function aborts on any inconsistency found unless the global variable default_abort_mismatch is false. Function is optional if memory cleanliness is no concern. This function does not require sc_init to be called first. In any case it makes sc_is_initialized return false.

Examples: options.c.

◆ sc_finalize_noabort()

int sc_finalize_noabort ( void )

Unregisters all packages, runs the memory check, removes the signal handlers and resets sc_identifier and sc_root_*.

This function never aborts but returns the number of errors encountered. Function is optional if memory cleanliness is no concern. This function does not require sc_init to be called first. In any case it makes sc_is_initialized return false.

Returns: 0 when everything is consistent, nonzero otherwise.

◆ sc_get_package_id()

int sc_get_package_id ( void )

Query SC's own package identity.

Returns: This is -1 before sc_init has been called and a proper package identifier (>= 0) afterwards. After sc_finalize the identifier resets to -1.

Note: This routine is not thread-safe.

◆ sc_have_json()

int sc_have_json ( void )

Return whether we have found a JSON library at configure time.

Returns: True if and only if SC_HAVE_JSON is defined.

◆ sc_have_zlib()

int sc_have_zlib ( void )

Return a boolean indicating whether zlib has been configured.

Returns: True if zlib including adler32_combine (3) has been found on running configure or respectively on calling cmake.

◆ sc_init()

void sc_init	(	sc_MPI_Comm	mpicomm,
		int	catch_signals,
		int	print_backtrace,
		sc_log_handler_t	log_handler,
		int	log_threshold
	)

Sets the global program identifier (e.g.

the MPI rank) and some flags. This function is optional. This function must only be called before additional threads are created. If this function is not called or called with log_handler == NULL, the default SC log handler will be used. If this function is not called or called with log_threshold == SC_LP_DEFAULT, the default SC log threshold will be used. The default SC log settings can be changed with sc_set_log_defaults ().

Parameters

[in]	mpicomm	MPI communicator, can be sc_MPI_COMM_NULL. If sc_MPI_COMM_NULL, the identifier is set to -1. Otherwise, sc_MPI_Init must have been called. Effectively, we just query size and rank.
[in]	catch_signals	If true, signals INT and SEGV are caught.
[in]	print_backtrace	If true, sc_abort prints a backtrace.

Examples: options.c.

◆ sc_is_initialized()

int sc_is_initialized ( void )

Return whether SC has been initialized or not.

Returns: True if libsc has been initialized with a call to sc_init and false otherwise. After sc_finalize the result resets to false.

Note: This routine is not thread-safe.

◆ sc_is_littleendian()

int sc_is_littleendian ( void )

Perform a runtime check for the integer endian convention.

Returns: True if byte order is little endian, false otherwise.

◆ sc_is_root()

int sc_is_root ( void )

Identify the root process.

Only meaningful between sc_init and sc_finalize and with a communicator that is not sc_MPI_COMM_NULL (otherwise always true).

Returns: Return true for the root process and false otherwise.

◆ sc_log()

void sc_log	(	const char *	filename,
		int	lineno,
		int	package,
		int	category,
		int	priority,
		const char *	msg
	)

The central log function to be called by all packages.

Dispatches the log calls by package and filters by category and priority.

Parameters

[in]	filename	Usually used with a FILE argument.
[in]	lineno	Usually used with a LINE argument.
[in]	package	Must be a registered package id or -1.
[in]	category	Must be SC_LC_NORMAL or SC_LC_GLOBAL.
[in]	priority	Must be > SC_LP_ALWAYS and < SC_LP_SILENT.
[in]	msg	Nul-terminated string to print.

◆ sc_logf()

void sc_logf	(	const char *	filename,
		int	lineno,
		int	package,
		int	category,
		int	priority,
		const char *	fmt,
			...
	)

The printf-style log function to be called by all packages.

Dispatches the log calls by package and filters by category and priority.

Parameters

[in]	filename	Usually used with a FILE argument.
[in]	lineno	Usually used with a LINE argument.
[in]	package	Must be a registered package id or -1.
[in]	category	Must be SC_LC_NORMAL or SC_LC_GLOBAL.
[in]	priority	Must be > SC_LP_ALWAYS and < SC_LP_SILENT.
[in]	fmt	String of printf convention to log.

◆ sc_logv()

void sc_logv	(	const char *	filename,
		int	lineno,
		int	package,
		int	category,
		int	priority,
		const char *	fmt,
		va_list	ap
	)

The vprintf-style log function to be called by all packages.

Dispatches the log calls by package and filters by category and priority.

Parameters

[in]	filename	Usually used with a FILE argument.
[in]	lineno	Usually used with a LINE argument.
[in]	package	Must be a registered package id or -1.
[in]	category	Must be SC_LC_NORMAL or SC_LC_GLOBAL.
[in]	priority	Must be > SC_LP_ALWAYS and < SC_LP_SILENT.
[in]	fmt	String of vprintf convention to log.
[in]	ap	Must be initialized by va_start.

◆ sc_package_is_registered()

int sc_package_is_registered ( int package_id )

Query whether an identifier matches a registered package.

Parameters

[in] package_id Only a non-negative id can be registered.

Returns: True if and only if the package id is non-negative and package is registered.

◆ sc_package_lock()

void sc_package_lock ( int package_id )

Acquire a pthread mutex lock.

If configured without –enable-pthread, this function does nothing. This function must be followed with a matching sc_package_unlock.

Parameters

[in] package_id Either -1 for an undefined package or an id returned from sc_package_register. Depending on the value, the appropriate mutex is chosen. Thus, we may overlap locking calls with distinct package_id.

◆ sc_package_print_summary()

void sc_package_print_summary ( int log_priority )

Print a summary of all packages registered with SC.

Uses the SC_LC_GLOBAL log category which by default only prints on rank 0.

Parameters

[in] log_priority Priority passed to sc log functions.

◆ sc_package_register()

int sc_package_register	(	sc_log_handler_t	log_handler,
		int	log_threshold,
		const char *	name,
		const char *	full
	)

Register a software package with SC.

This function must only be called before additional threads are created. The logging parameters are as in sc_set_log_defaults.

Returns: Returns a unique package id.

◆ sc_package_set_abort_alloc_mismatch()

void sc_package_set_abort_alloc_mismatch	(	int	package_id,
		int	set_abort
	)

Set the unregister behavior of sc_package_unregister().

Parameters

[in]	package_id	Must be -1 for the default package or the identifier of a registered package.
[in]	set_abort	True if sc_package_unregister() should abort if the number of allocs does not match the number of frees; false otherwise.

◆ sc_package_set_verbosity()

void sc_package_set_verbosity	(	int	package_id,
		int	log_priority
	)

Set the logging verbosity of a registered package.

This can be called at any point in the program, any number of times. It can only lower the verbosity at and below the value of SC_LP_THRESHOLD.

Parameters

[in]	package_id	Must be a registered package identifier.
[in]	log_priority	The minimum priority required to output.

◆ sc_package_unlock()

void sc_package_unlock ( int package_id )

Release a pthread mutex lock.

If configured without –enable-pthread, this function does nothing. This function must be follow a matching sc_package_lock.

Parameters

[in] package_id Either -1 for an undefined package or an id returned from sc_package_register. Depending on the value, the appropriate mutex is chosen. Thus, we may overlap locking calls with distinct package_id.

◆ sc_package_unregister()

void sc_package_unregister ( int package_id )

Unregister a software package with SC.

This function must only be called after additional threads are finished.

◆ sc_set_abort_handler()

void sc_set_abort_handler ( sc_abort_handler_t abort_handler )

Set the default SC abort behavior.

Parameters

[in] abort_handler Set default SC above handler (NULL selects builtin). If it returns, we abort (2) then.

◆ sc_set_log_defaults()

void sc_set_log_defaults	(	FILE *	log_stream,
		sc_log_handler_t	log_handler,
		int	log_threshold
	)

Controls the default SC log behavior.

Parameters

[in]	log_stream	Set stream to use by sc_logf (or NULL for stdout).
[in]	log_handler	Set default SC log handler (NULL selects builtin).
[in]	log_threshold	Set default SC log threshold (or SC_LP_DEFAULT). May be SC_LP_ALWAYS or SC_LP_SILENT.

◆ sc_sleep()

void sc_sleep ( unsigned milliseconds )

Portable function to sleep a prescribed amount of milliseconds.

Parameters

[in] milliseconds The number of milliseconds to sleep.

◆ sc_snprintf()

void sc_snprintf	(	char *	str,
		size_t	size,
		const char *	format,
			...
	)

Wrap the system snprintf function, allowing for truncation.

The snprintf function may truncate the string written to the specified length. In some cases, compilers warn when this may occur. Here this is permitted behavior and we avoid the warning.

Parameters

[out]	str	Buffer of length at least size. On output, not touched if NULL or size == 0. Otherwise, "" on snprintf error or the proper result. The proper result is padded on the right with '\0' if the allocation length of the string that is defined by format is shorter than size.
[in]	size	Allocation length of str.
[in]	format	Format string as in man (3) snprintf.

◆ sc_strcopy()

void sc_strcopy	(	char *	dest,
		size_t	size,
		const char *	src
	)

Provide a string copy function.

Parameters

[out]	dest	Buffer of length at least size. On output, not touched if NULL or size == 0. Otherwise, src is copied to dest and dest is padded with '\0' from the right if strlen (src) < size - 1.
[in]	size	Allocation length of dest.
[in]	src	Null-terminated string.

Returns: Equivalent to sc_snprintf (dest, size, "%s", src).

◆ sc_version()

const char* sc_version ( void )

Return the full version of libsc.

Returns: Return the version of libsc using the format VERSION_MAJOR.VERSION_MINOR.VERSION_POINT, where VERSION_POINT can contain dots and characters, e.g. to indicate the additional number of commits and a git commit hash.

◆ sc_version_major()

int sc_version_major ( void )

Return the major version of libsc.

Returns: Return the major version of libsc.

◆ sc_version_minor()

int sc_version_minor ( void )

Return the minor version of libsc.

Returns: Return the minor version of libsc.

Variable Documentation

◆ sc_package_id

SC_DLL_PUBLIC int sc_package_id

extern

libsc allows for multiple packages to use their own log priorities etc.

Logging priorities, callbacks, and memory balance counters go by package. This is the package id for core sc functions and is meant to be read only. The variable starts out with a value of -1, which is fine by itself. It is set to a non-negative value by the (optional) sc_init. Calling the (also optional) sc_finalize resets it to -1. There is no need to access this variable directly; use sc_get_package_id.

Examples: options.c.

◆ sc_trace_file

SC_DLL_PUBLIC FILE* sc_trace_file

extern

Optional trace file for logging (see sc_init).

Initialized to NULL.

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SC_ALLOC_ZERO

◆ SC_BZERO

◆ SC_GEN_LOG

◆ SC_GEN_LOGF

◆ SC_LOG2_16

◆ SC_LOG2_32

◆ SC_LOG2_64

◆ SC_REALLOC

Function Documentation

◆ sc_atoi()

◆ sc_atol()

◆ sc_finalize()

◆ sc_finalize_noabort()

◆ sc_get_package_id()

◆ sc_have_json()

◆ sc_have_zlib()

◆ sc_init()

◆ sc_is_initialized()

◆ sc_is_littleendian()

◆ sc_is_root()

◆ sc_log()

◆ sc_logf()

◆ sc_logv()

◆ sc_package_is_registered()

◆ sc_package_lock()

◆ sc_package_print_summary()

◆ sc_package_register()

◆ sc_package_set_abort_alloc_mismatch()

◆ sc_package_set_verbosity()

◆ sc_package_unlock()

◆ sc_package_unregister()

◆ sc_set_abort_handler()

◆ sc_set_log_defaults()

◆ sc_sleep()

◆ sc_snprintf()

◆ sc_strcopy()

◆ sc_version()

◆ sc_version_major()

◆ sc_version_minor()

Variable Documentation

◆ sc_package_id

◆ sc_trace_file