pub enum KunQuantError {
ExecutorCreationFailed,
LibraryLoadFailed {
path: String,
},
ModuleNotFound {
name: String,
},
BufferNameMapCreationFailed,
InvalidBufferName {
name: String,
},
InvalidStockCount {
num_stocks: usize,
},
BufferSizeMismatch {
name: String,
expected: usize,
actual: usize,
},
StreamCreationFailed,
BufferHandleNotFound {
name: String,
},
NullPointer,
StringConversion(NulError),
Utf8Conversion(Utf8Error),
}Expand description
Comprehensive error types for KunQuant operations.
This enum covers all possible error conditions that can occur when using the KunQuant-rs library, from initialization failures to runtime computation errors. Each variant provides detailed context to help with debugging.
§Error Categories
- Initialization Errors: Executor, library, and buffer map creation failures
- Resource Errors: Library loading, module lookup, and buffer handle errors
- Validation Errors: Invalid parameters, buffer size mismatches, data constraints
- Runtime Errors: Null pointers, computation failures, and system errors
§Error Handling
All KunQuant operations return Result<T, KunQuantError>, allowing for
comprehensive error handling using Rust’s ? operator and pattern matching.
§Examples
use kunquant_rs::{Executor, KunQuantError};
match Executor::single_thread() {
Ok(executor) => println!("Executor created successfully"),
Err(KunQuantError::ExecutorCreationFailed) => {
eprintln!("Failed to create executor - check KunQuant installation");
}
Err(e) => eprintln!("Unexpected error: {}", e),
}Variants§
ExecutorCreationFailed
Failed to create a KunQuant executor.
This error occurs when the underlying C library cannot create an executor, typically due to insufficient system resources or library initialization issues.
Common Causes:
- KunQuant C library not properly installed
- Insufficient memory for executor creation
- Invalid thread configuration (for multi-threaded executors)
- Missing required system dependencies
LibraryLoadFailed
Failed to load a KunQuant factor library from the specified path.
This error indicates that the library file could not be loaded, either because it doesn’t exist, isn’t accessible, or isn’t a valid KunQuant library.
Common Causes:
- File doesn’t exist at the specified path
- Insufficient permissions to read the file
- Library compiled for incompatible architecture
- Missing shared library dependencies
- Corrupted or invalid library file
ModuleNotFound
The requested module was not found in the loaded library.
This error occurs when trying to access a module that doesn’t exist in the loaded library, typically due to incorrect module names or library compilation issues.
Common Causes:
- Typo in module name (names are case-sensitive)
- Module not included during library compilation
- Library compiled with different module names
- Using wrong library file
BufferNameMapCreationFailed
Failed to create a buffer name map for data management.
This error indicates that the internal buffer management system could not be initialized, typically due to memory allocation failures.
Common Causes:
- Insufficient system memory
- Memory fragmentation
- System resource limits exceeded
InvalidBufferName
The specified buffer name is invalid or contains illegal characters.
Buffer names must be valid C strings without null bytes and should match the names defined in the factor module.
Common Causes:
- Buffer name contains null bytes (‘\0’)
- Empty buffer name
- Non-UTF8 characters in buffer name
InvalidStockCount
The number of stocks is not a multiple of 8, which is required for SIMD optimization.
KunQuant uses SIMD (Single Instruction, Multiple Data) instructions for performance optimization, which requires the stock count to be divisible by 8.
Solution: Use a stock count that is a multiple of 8 (e.g., 8, 16, 24, 32, …).
BufferSizeMismatch
Buffer size doesn’t match the expected dimensions for the computation.
This error occurs when the provided buffer size doesn’t match the expected size based on the number of stocks and time points.
Expected Size: num_stocks * total_time for time-series data
StreamCreationFailed
Failed to create a streaming computation context.
This error occurs when the streaming context cannot be initialized, typically due to incompatible module settings or resource constraints.
Common Causes:
- Module not compiled with
output_layout="STREAM" - Invalid number of stocks (not multiple of 8)
- Insufficient memory for streaming buffers
- Incompatible module and executor combination
BufferHandleNotFound
The requested buffer handle was not found in the streaming context.
This error occurs when trying to access a buffer that hasn’t been registered or doesn’t exist in the current streaming context.
Common Causes:
- Buffer name doesn’t match module definition
- Buffer not properly initialized in streaming context
- Typo in buffer name (names are case-sensitive)
NullPointer
A null pointer was encountered during C library interaction.
This error indicates a serious internal issue where a C library function returned a null pointer unexpectedly.
Common Causes:
- Memory allocation failure in C library
- Invalid handle passed to C function
- Library corruption or version mismatch
- System resource exhaustion
StringConversion(NulError)
Error converting Rust string to C string (contains null bytes).
This error occurs when a Rust string contains null bytes (‘\0’), which are not allowed in C strings used by the KunQuant library.
Solution: Ensure strings don’t contain null bytes.
Utf8Conversion(Utf8Error)
Error converting C string to UTF-8.
This error occurs when the C library returns a string that contains invalid UTF-8 sequences.
Common Causes:
- Corrupted data from C library
- Encoding mismatch between C and Rust
- Memory corruption