Skip to Content
DocsAPI ReferenceStatus Codes

spires_status

Integer return code used by most SPIRES API functions to indicate success or the category of failure.

Definition

typedef enum {
    SPIRES_OK = 0,
    SPIRES_ERR_INVALID_ARG,
    SPIRES_ERR_ALLOC,
    SPIRES_ERR_INTERNAL
} spires_status;

Values

ValueIntegerDescription
SPIRES_OK0The operation completed successfully.
SPIRES_ERR_INVALID_ARG1One or more arguments are invalid. This includes NULL pointers where a valid pointer is required, out-of-range numeric parameters (e.g., num_neurons == 0), or incompatible configuration fields.
SPIRES_ERR_ALLOC2A memory allocation failed. The library attempted to allocate heap memory via malloc or calloc and received NULL. No partial state is left behind; the operation is fully rolled back.
SPIRES_ERR_INTERNAL3An internal error occurred that does not fit the other categories. This may indicate a bug in the library, a failure in an underlying dependency (e.g., LAPACK), or an unexpected numerical condition.

Usage Pattern

All functions that return spires_status follow a consistent contract: on any non-zero return, the output parameters are left untouched (or, for creation functions, no resource is allocated). This means callers can test for failure with a simple truthiness check:

spires_reservoir *r = NULL;
if (spires_reservoir_create(&cfg, &r)) {
    fprintf(stderr, "reservoir creation failed\n");
    return 1;
}

For finer-grained error handling, compare against specific codes:

spires_status s = spires_train_ridge(r, input, target, len, lambda);
switch (s) {
    case SPIRES_OK:
        break;
    case SPIRES_ERR_INVALID_ARG:
        fprintf(stderr, "bad argument to ridge training\n");
        break;
    case SPIRES_ERR_ALLOC:
        fprintf(stderr, "out of memory during training\n");
        break;
    case SPIRES_ERR_INTERNAL:
        fprintf(stderr, "internal error (LAPACK failure?)\n");
        break;
}

Notes

  • spires_status values are guaranteed to be contiguous starting at 0. However, future library versions may add new error codes after SPIRES_ERR_INTERNAL. Defensive code should treat any non-zero value as an error.
  • Functions that return void (e.g., spires_reservoir_destroy) or a data pointer (e.g., spires_run, spires_copy_reservoir_state) do not use this enum.

See Also

Last updated on
OverviewEnums