Miscellaneous¶

Error handling¶

const char *rascal_last_error(void)¶

Get the last error message that was created on the current thread.

Returns:: the last error message, as a NULL-terminated string

typedef int32_t rascal_status_t¶

Status type returned by all functions in the C API.

The value 0 (RASCAL_SUCCESS) is used to indicate successful operations. Positive non-zero values are reserved for internal use in rascaline. Negative values are reserved for use in user code, in particular to indicate error coming from callbacks.

RASCAL_SUCCESS¶: Status code used when a function succeeded

RASCAL_INVALID_PARAMETER_ERROR¶: Status code used when a function got an invalid parameter

RASCAL_JSON_ERROR¶: Status code used when there was an error reading or writing JSON

RASCAL_UTF8_ERROR¶: Status code used when a string contains non-utf8 data

RASCAL_CHEMFILES_ERROR¶: Status code used for error related to reading files with chemfiles

RASCAL_SYSTEM_ERROR¶: Status code used for errors coming from the system implementation if we don’t have a more specific status

RASCAL_INTERNAL_ERROR¶: Status code used when there was an internal error, i.e. there is a bug inside rascaline

Logging¶

rascal_status_t rascal_set_logging_callback(rascal_logging_callback_t callback)¶: Set the given callback function as the global logging callback. This function will be called on all log events. If a logging callback was already set, it is replaced by the new one.

typedef void (*rascal_logging_callback_t)(int32_t level, const char *message)¶

Callback function type for rascaline logging system. Such functions are called when a log event is emitted in the code.

The first argument is the log level, one of RASCAL_LOG_LEVEL_ERROR, RASCAL_LOG_LEVEL_WARN RASCAL_LOG_LEVEL_INFO, RASCAL_LOG_LEVEL_DEBUG, or RASCAL_LOG_LEVEL_TRACE. The second argument is a NULL-terminated string containing the message associated with the log event.

RASCAL_LOG_LEVEL_ERROR¶: The “error” level designates very serious errors

RASCAL_LOG_LEVEL_WARN¶: The “warn” level designates hazardous situations

RASCAL_LOG_LEVEL_INFO¶: The “info” level designates useful information

RASCAL_LOG_LEVEL_DEBUG¶

The “debug” level designates lower priority information

By default, log messages at this level are disabled in release mode, and enabled in debug mode.

RASCAL_LOG_LEVEL_TRACE¶

The “trace” level designates very low priority, often extremely verbose, information.

By default, rascaline disable this level, you can enable it by editing the code.

Profiling¶

rascal_status_t rascal_profiling_enable(bool enabled)¶

Enable or disable profiling data collection. By default, data collection is disabled.

Rascaline uses the to collect timing information on the calculations. This profiling code collects the total time spent inside the most important functions, as well as the function call graph (which function called which other function).

You can use rascal_profiling_clear to reset profiling data to an empty state, and rascal_profiling_get to extract the profiling data.

Parameters:

enabled – whether data collection should be enabled or not

Returns:

The status code of this operation. If the status is not RASCAL_SUCCESS, you can use rascal_last_error() to get the full error message.

rascal_status_t rascal_profiling_clear(void)¶

Clear all collected profiling data

See also rascal_profiling_enable and rascal_profiling_get.

Returns:: The status code of this operation. If the status is not RASCAL_SUCCESS, you can use rascal_last_error() to get the full error message.

rascal_status_t rascal_profiling_get(const char *format, char *buffer, uintptr_t bufflen)¶

Extract the current set of data collected for profiling.

See also rascal_profiling_enable and rascal_profiling_clear.

Parameters:

format – in which format should the data be provided. "table", "short_table" and "json" are currently supported
buffer – pre-allocated buffer in which profiling data will be copied. If the buffer is too small, this function will return RASCAL_BUFFER_SIZE_ERROR
bufflen – size of the buffer

Returns:

The status code of this operation. If the status is not RASCAL_SUCCESS, you can use rascal_last_error() to get the full error message.