system.h

#include <sif/core/system.h>

SIF_CORE_SYSTEM_H

Library lifetime: initialization, configuration and teardown.

sif_init() must be called before any other entry point and sif_finalize() after the last one. Between them the library holds process-global state: the logger, the thread ceiling, the FFTW plan cache and the settings table.

struct sif_fft_config_t

FFTW3 configuration.

bool skip_tuning

Skip plan tuning and take FFTW’s estimated plan instead. Faster to set up, slower to transform; worth setting for short runs, or for runs with many distinct transform sizes.

struct sif_omp_config_t

OpenMP configuration.

uint32_t n_threads

Thread ceiling. 0 leaves the OpenMP runtime’s own default in place.

struct sif_config_t

General library configuration.

sif_fft_config_t *fft_config

FFTW settings, or NULL for the defaults.

sif_omp_config_t *omp_config

OpenMP settings, or NULL for the defaults.

uint8_t log_level

Minimum level a message must reach to be printed; one of the SIF_LOG_LEVEL_* constants. SIF_LOG_LEVEL_TRACE is the verbose mode.

Warning

The field is always honoured, and SIF_LOG_LEVEL_TRACE is 0 – so a zero-initialized sif_config_t asks for trace logging, not for the default. Set it explicitly, or use one of the presets below.

int sif_init(sif_config_t *config)

Initialize the library.

Brings up the logger, the thread ceiling, the settings table and the FFTW plan cache. Calling it a second time logs a warning, keeps the first configuration, and returns SIF_OK.

Parameters:

• config – Configuration to apply, or NULL for the defaults. It is read once and copied, so neither the struct nor the sub-structs it points at need to outlive the call, and the library never frees them.

Returns:

SIF_OK, or SIF_ERR_ALLOC if the library state or FFTW could not be brought up – in which case nothing is left initialized, and the call may be retried.

Note

Failing to create the cache or wisdom directories is only a warning: the run still does everything that does not need them.

void sif_finalize(void)

Shut the library down, releasing everything sif_init() acquired.

Saves the settings table if it changed and tears down the FFTW plan cache. No sif entry point may be called afterwards without initializing again.

Ready-made sif_config_t pointers for the common cases.

if (sif_init(SIF_CONFIG_STANDARD) != SIF_OK)
  return 1;

Warning

These expand to compound literals, whose lifetime ends with the enclosing block. Pass one straight to sif_init(); do not store the pointer. @{

SIF_CONFIG_VERBOSE

Trace-level logging, timings reported.

SIF_CONFIG_QUIET

Warnings and errors only.

SIF_CONFIG_STANDARD

The default: informational messages and above.

@}