Initialization

Enumerations

JaniceLogLevel

A enumeration to control the logging fidelity of JanICE applications. Possible log levels are:

Level Description
JaniceLogDebug Output fine-grained informational events useful for debugging.
JaniceLogInfo Output course-grained events indicating progress.
JaniceLogWarning Output warning events that might lead to a failure.
JaniceLogError Output failure events that don’t stop the application from running.
JaniceLogCritical Output events that will cause the application to abort.

Structs

JaniceConfigurationItem

A key-value pair representing a single configuration setting

Fields

Name Type Description
key char* A null-terminated configuration key
value char* A null-terminated configuration value

JaniceConfiguration

A structure representing a list of JaniceConfigurationItem objects.

Fields

Name Type Description
values JaniceConfigurationItem* An array of configuration objects
length size_t The number of elements in values

Functions

janice_initialize

Initialize global or shared state for the implementation. This function should be called once at the start of the application, before making any other calls to the API.

Signature

JANICE_EXPORT JaniceError janice_initialize(const char* sdk_path,
                                            const char* temp_path,
                                            const char* algorithm,
                                            const int num_threads,
                                            const int* gpus,
                                            const int num_gpus);

Thread Safety

This function is Thread Unsafe.

Parameters

Name Type Description
sdk_path const char* Path to a read-only directory containing the JanICE compliant SDK as specified by the implementor.
temp_path const char* Path to an existing empty read-write directory for use as temporary file storage by the implementation. This path must be guaranteed until janice_finalize.
algorithm const char* An empty string indicating the default algorithm, or an implementation defined containing an alternative configuration.
num_threads const int The number of threads the implementation is allowed to use. A value of ‘-1’ indicates that the implementation should use all available hardware.
gpus const int* A list of indices of GPUs available to the implementation. The length of the list is given by num_gpus. If the implementor does not require a GPU in their solution they can ignore this parameter. Memory for the object should be managed by the user. The implementation should assume this points to a valid object.
num_gpus const int The length of the gpus array. If no GPUs are available this should be set to 0.

janice_set_log_level

Set the global log level for the implementation. By default, the log level is set to JaniceLogWarning.

Signature

JANICE_EXPORT JaniceError janice_set_log_level(JaniceLogLevel level);

Thread Safety

This function is Thread Unsafe.

Parameters

Name Type Description
level JaniceLogLevel The new log level for the implementation

janice_api_version

Query the implementation for the version of the JanICE API it was designed to implement. See Versioning for more information on the versioning convention for this API.

Signature

JANICE_EXPORT JaniceError janice_api_version(uint32_t* major,
                                             uint32_t* minor,
                                             uint32_t* patch);

Thread Safety

This function is Reentrant.

Parameters

Name Type Description
major uint32_t* The supported major version of the API. Memory for the object should be managed by the user. The implementation should assume this points to a valid object.
minor uint32_t* The supported minor version of the API. Memory for the object should be managed by the user. The implementation should assume this points to a valid object.
patch uint32_t* The supported patch version of the API. Memory for the object should be managed by the user. The implementation should assume this points to a valid object.

janice_sdk_version

Query the implementation for its SDK version.

Signature

JANICE_EXPORT JaniceError janice_sdk_version(uint32_t* major,
                                             uint32_t* minor,
                                             uint32_t* patch);

Thread Safety

This function is Reentrant.

Parameters

Name Type Description
major uint32_t* The major version of the SDK. Memory for the object should be managed by the user. The implementation should assume this points to a valid object.
minor uint32_t* The minor version of the SDK. Memory for the object should be managed by the user. The implementation should assume this points to a valid object.
patch uint32_t* The patch version of the SDK. Memory for the object should be managed by the user. The implementation should assume this points to a valid object.

janice_get_current_configuration

Get the current implementation configuration as a list of key value pairs

Signature

JANICE_EXPORT JaniceError janice_get_current_configuration(JaniceConfiguration* configuration);

Parameters

Name Type Description
configuration JaniceConfiguration* A list to hold the current configuration settings of the implementation. The user is responsible for allocating memory for the struct before the function call. The implementor is responsbile for allocating and filling internal members. The user is responsible for clearing the object by calling janice_clear_configuration.

janice_finalize

Destroy any resources created by janice_initialize and finalize the application. This should be called once after all other API calls.

Signature

JANICE_EXPORT JaniceError janice_finalize();

Thread Safety

This function is Thread Unsafe.

janice_clear_configuration

Free any memory associated with a JaniceConfiguration object.

Signature

JANICE_EXPORT JaniceError janice_clear_configuration(JaniceConfiguration* configuration);

Thread Safety

This function is Reentrant.

Parameters

Name Type Description
configuration JaniceConfiguration* A configuration object to clear.