p4est  1.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Typedefs | Functions | Variables
sc.h File Reference

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

#include <sc_config.h>
#include <math.h>
#include <ctype.h>
#include <float.h>
#include <libgen.h>
#include <limits.h>
#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sc_mpi.h>

Go to the source code of this file.

Macros

#define _sc_const   const
 
#define _sc_restrict   restrict
 
#define __STDC_LIMIT_MACROS
 
#define M_E   2.7182818284590452354 /* e */
 
#define M_LOG2E   1.4426950408889634074 /* log_2 e */
 
#define M_LOG10E   0.43429448190325182765 /* log_10 e */
 
#define M_LN2   0.69314718055994530942 /* log_e 2 */
 
#define M_LN10   2.30258509299404568402 /* log_e 10 */
 
#define M_PI   3.14159265358979323846 /* pi */
 
#define M_PI_2   1.57079632679489661923 /* pi/2 */
 
#define M_PI_4   0.78539816339744830962 /* pi/4 */
 
#define M_1_PI   0.31830988618379067154 /* 1/pi */
 
#define M_2_PI   0.63661977236758134308 /* 2/pi */
 
#define M_2_SQRTPI   1.12837916709551257390 /* 2/sqrt(pi) */
 
#define M_SQRT2   1.41421356237309504880 /* sqrt(2) */
 
#define M_SQRT1_2   0.70710678118654752440 /* 1/sqrt(2) */
 
#define SC_EPS   2.220446049250313e-16
 
#define SC_1000_EPS   (1000. * 2.220446049250313e-16)
 
#define SC_NOOP()   ((void) (0))
 
#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_CHECK_ZLIB(r)   SC_CHECK_ABORT ((r) == Z_OK, "zlib 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_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)
 this selects the SC default threshold
 
#define SC_LP_ALWAYS   0
 this will log everything
 
#define SC_LP_TRACE   1
 this will 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
 the main things a function is doing
 
#define SC_LP_STATISTICS   5
 important for consistency/performance
 
#define SC_LP_PRODUCTION   6
 a few lines for a major api function
 
#define SC_LP_ESSENTIAL   7
 this logs a few lines max per program
 
#define SC_LP_ERROR   8
 this logs errors only
 
#define SC_LP_SILENT   9
 this never logs anything
 
#define SC_LP_THRESHOLD   SC_LP_INFO
 The log priority for the sc package.
 
#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__)
 

Typedefs

typedef void(* sc_handler_t )(void *data)
 
typedef void(* sc_log_handler_t )(FILE *log_stream, const char *filename, int lineno, int package, int category, int priority, const char *msg)
 

Functions

void SC_ABORTF (const char *fmt,...) __attribute__((format(printf
 
void __attribute__ ((noreturn))
 
void SC_CHECK_ABORTF (int success, const char *fmt,...) __attribute__((format(printf
 
void SC_GEN_LOGF (int package, int category, int priority, const char *fmt,...) __attribute__((format(printf
 
void void SC_GLOBAL_LOGF (int priority, const char *fmt,...) __attribute__((format(printf
 
void void void SC_LOGF (int priority, const char *fmt,...) __attribute__((format(printf
 
void SC_GLOBAL_TRACEF (const char *fmt,...) __attribute__((format(printf
 
void void SC_GLOBAL_LDEBUGF (const char *fmt,...) __attribute__((format(printf
 
void void void SC_GLOBAL_VERBOSEF (const char *fmt,...) __attribute__((format(printf
 
void void void void SC_GLOBAL_INFOF (const char *fmt,...) __attribute__((format(printf
 
void void void void void SC_GLOBAL_STATISTICSF (const char *fmt,...) __attribute__((format(printf
 
void void void void void void SC_GLOBAL_PRODUCTIONF (const char *fmt,...) __attribute__((format(printf
 
void void void void void void void SC_GLOBAL_ESSENTIALF (const char *fmt,...) __attribute__((format(printf
 
void void void void void void
void void 
SC_GLOBAL_LERRORF (const char *fmt,...) __attribute__((format(printf
 
void SC_TRACEF (const char *fmt,...) __attribute__((format(printf
 
void void SC_LDEBUGF (const char *fmt,...) __attribute__((format(printf
 
void void void SC_VERBOSEF (const char *fmt,...) __attribute__((format(printf
 
void void void void SC_INFOF (const char *fmt,...) __attribute__((format(printf
 
void void void void void SC_STATISTICSF (const char *fmt,...) __attribute__((format(printf
 
void void void void void void SC_PRODUCTIONF (const char *fmt,...) __attribute__((format(printf
 
void void void void void void void SC_ESSENTIALF (const char *fmt,...) __attribute__((format(printf
 
void void void void void void
void void 
SC_LERRORF (const char *fmt,...) __attribute__((format(printf
 
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_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)
 
void sc_set_log_defaults (FILE *log_stream, sc_log_handler_t log_handler, int log_thresold)
 Controls the default SC log 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,...) __attribute__((format(printf
 
void void sc_logv (const char *filename, int lineno, int package, int category, int priority, const char *fmt, va_list ap)
 
void sc_log_indent_push_count (int package, int count)
 Add spaces to the start of a package's default log format. More...
 
void sc_log_indent_pop_count (int package, int count)
 Remove spaces from the start of a package's default log format. More...
 
void sc_log_indent_push (void)
 Add one space to the start of sc's default log format. More...
 
void sc_log_indent_pop (void)
 Remove one space from the start of a sc's default log format. More...
 
void sc_abort (void) __attribute__((noreturn))
 Print a stack trace, call the abort handler and then call abort (). More...
 
void sc_abort_verbose (const char *filename, int lineno, const char *msg) __attribute__((noreturn))
 Print a message to stderr and then call sc_abort (). More...
 
void sc_abort_verbosef (const char *filename, int lineno, const char *fmt,...) __attribute__((format(printf
 Print a message to stderr and then call sc_abort (). More...
 
void sc_abort_verbosev (const char *filename, int lineno, const char *fmt, va_list ap) __attribute__((noreturn))
 Print a message to stderr and then call sc_abort (). More...
 
void sc_abort_collective (const char *msg) __attribute__((noreturn))
 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)
 
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...
 
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_is_root (void)
 Identify the root process. More...
 

Variables

const int sc_log2_lookup_table [256]
 
int sc_package_id
 
FILE * sc_trace_file
 
int sc_trace_prio
 

Detailed Description

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

Macro Definition Documentation

#define SC_ALLOC_ZERO (   t,
 
)
Value:
(t *) sc_calloc (sc_package_id, \
(size_t) (n), sizeof(t))
#define SC_BZERO (   p,
 
)    ((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.

#define SC_GEN_LOG (   package,
  category,
  priority,
 
)
Value:
((priority) < SC_LP_THRESHOLD ? (void) 0 : \
sc_log (__FILE__, __LINE__, (package), (category), (priority), (s)))
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.
#define SC_LP_THRESHOLD
The log priority for the sc package.
Definition: sc.h:305
#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__))
#define SC_LP_THRESHOLD
The log priority for the sc package.
Definition: sc.h:305
#define SC_LOG2_16 (   x)
Value:
(((x) > 0xff) ? \
(SC_LOG2_8 ((x) >> 8) + 8) : SC_LOG2_8 (x))
#define SC_LOG2_32 (   x)
Value:
(((x) > 0xffff) ? \
(SC_LOG2_16 ((x) >> 16)) + 16 : SC_LOG2_16 (x))
#define SC_LOG2_64 (   x)
Value:
(((x) > 0xffffffffLL) ? \
(SC_LOG2_32 ((x) >> 32)) + 32 : SC_LOG2_32 (x))
#define SC_REALLOC (   p,
  t,
 
)
Value:
(t *) sc_realloc (sc_package_id, \
(p), (n) * sizeof(t))

Function Documentation

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_finalize ( void  )

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

This function is optional. This function does not require sc_init to be called first.

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]mpicommMPI 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.
[in]catch_signalsIf true, signals INT SEGV USR2 are be caught.
[in]print_backtraceIf true, sc_abort prints a backtrace.
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.
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]packageMust be a registered package id or -1.
[in]categoryMust be SC_LC_NORMAL or SC_LC_GLOBAL.
[in]priorityMust be > SC_LP_ALWAYS and < SC_LP_SILENT.
void sc_log_indent_pop ( void  )

Remove one space from the start of a sc'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_push_count ( int  package,
int  count 
)

Add spaces to the start of a package's default log format.

void sc_package_print_summary ( int  log_priority)

Print a summary of all packages registered with SC.

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

Parameters
[in]log_priorityPriority passed to sc log functions.
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.
void sc_package_unregister ( int  package_id)

Unregister a software package with SC.

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

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

Controls the default SC log behavior.

Parameters
[in]log_streamSet stream to use by sc_logf (or NULL for stdout).
[in]log_handlerSet default SC log handler (NULL selects builtin).
[in]log_thresholdSet default SC log threshold (or SC_LP_DEFAULT). May be SC_LP_ALWAYS or SC_LP_SILENT.