goud_engine/core/error/
mod.rs

1//! Error handling infrastructure for GoudEngine.
2//!
3//! This is the canonical Foundation layer location for error types.
4//! `libs/error/` re-exports from here so both import paths work identically.
5//!
6//! # Error Code Ranges
7//!
8//! Error codes are organized into ranges by category:
9//!
10//! | Range     | Category   | Description                          |
11//! |-----------|------------|--------------------------------------|
12//! | 0         | Success    | Operation completed successfully     |
13//! | 1-99      | Context    | Initialization and context errors    |
14//! | 100-199   | Resource   | Asset and resource management errors |
15//! | 200-299   | Graphics   | Rendering and GPU errors             |
16//! | 300-399   | Entity     | ECS entity and component errors      |
17//! | 400-499   | Input      | Input handling errors                |
18//! | 500-599   | System     | Platform and system errors           |
19//! | 600-699   | Provider   | Provider subsystem errors            |
20//! | 900-999   | Internal   | Unexpected internal errors           |
21//!
22//! # FFI Compatibility
23//!
24//! Error codes use `i32` for maximum C ABI compatibility. Negative values
25//! are reserved for future use (e.g., platform-specific errors).
26
27mod codes;
28pub mod context;
29mod conversions;
30mod ffi_bridge;
31mod methods;
32pub mod recovery;
33mod reverse_mapping;
34mod types;
35
36// Re-export everything so external code sees the same flat API as before.
37
38pub use codes::{
39    error_category, is_error, is_success, GoudErrorCode, CONTEXT_ERROR_BASE, ENTITY_ERROR_BASE,
40    ERR_ALREADY_INITIALIZED, ERR_AUDIO_INIT_FAILED, ERR_BACKEND_NOT_SUPPORTED,
41    ERR_BUFFER_CREATION_FAILED, ERR_COMPONENT_ALREADY_EXISTS, ERR_COMPONENT_NOT_FOUND,
42    ERR_CONTEXT_DESTROYED, ERR_DRAW_CALL_FAILED, ERR_ENTITY_ALREADY_EXISTS, ERR_ENTITY_NOT_FOUND,
43    ERR_HANDLE_EXPIRED, ERR_HANDLE_TYPE_MISMATCH, ERR_INITIALIZATION_FAILED,
44    ERR_INPUT_DEVICE_NOT_FOUND, ERR_INTERNAL_ERROR, ERR_INVALID_CONTEXT, ERR_INVALID_HANDLE,
45    ERR_INVALID_INPUT_ACTION, ERR_INVALID_STATE, ERR_NOT_IMPLEMENTED, ERR_NOT_INITIALIZED,
46    ERR_PHYSICS_INIT_FAILED, ERR_PLATFORM_ERROR, ERR_PROVIDER_INIT_FAILED, ERR_PROVIDER_NOT_FOUND,
47    ERR_PROVIDER_OPERATION_FAILED, ERR_QUERY_FAILED, ERR_RENDER_TARGET_FAILED,
48    ERR_RESOURCE_ALREADY_EXISTS, ERR_RESOURCE_INVALID_FORMAT, ERR_RESOURCE_LOAD_FAILED,
49    ERR_RESOURCE_NOT_FOUND, ERR_SHADER_COMPILATION_FAILED, ERR_SHADER_LINK_FAILED,
50    ERR_TEXTURE_CREATION_FAILED, ERR_WINDOW_CREATION_FAILED, GRAPHICS_ERROR_BASE, INPUT_ERROR_BASE,
51    INTERNAL_ERROR_BASE, PROVIDER_ERROR_BASE, RESOURCE_ERROR_BASE, SUCCESS, SYSTEM_ERROR_BASE,
52};
53
54pub use context::GoudErrorContext;
55
56pub use recovery::{is_fatal, is_recoverable, recovery_class, recovery_hint, RecoveryClass};
57
58pub use ffi_bridge::{
59    clear_last_error, get_last_error, last_error_code, last_error_message, last_error_operation,
60    last_error_subsystem, set_last_error, set_last_error_with_context, take_last_error,
61    GoudFFIResult,
62};
63
64pub use types::GoudError;
65
66// =============================================================================
67// Result Type Alias
68// =============================================================================
69
70/// A specialized `Result` type for GoudEngine operations.
71///
72/// This type alias provides a convenient way to work with results that may
73/// contain a `GoudError`. It's the standard return type for fallible operations
74/// throughout the engine.
75///
76/// # Example
77///
78/// ```
79/// use goud_engine::core::error::{GoudResult, GoudError};
80///
81/// fn load_texture(path: &str) -> GoudResult<u32> {
82///     if path.is_empty() {
83///         return Err(GoudError::ResourceNotFound("Empty path".to_string()));
84///     }
85///     Ok(42) // texture id
86/// }
87///
88/// match load_texture("player.png") {
89///     Ok(id) => println!("Loaded texture with id: {}", id),
90///     Err(e) => println!("Failed to load: {}", e),
91/// }
92/// ```
93pub type GoudResult<T> = Result<T, GoudError>;
94
95#[cfg(test)]
96mod tests {
97    mod codes_tests;
98    mod context_errors;
99    mod entity_errors;
100    mod ffi_tests;
101    mod graphics_errors;
102    mod internal_errors;
103    mod resource_errors;
104    mod round_trip;
105    mod system_errors;
106    mod traits;
107
108    mod context_propagation;
109    mod recovery_tests;
110}
goud_engine/core/error/mod.rs

goud_engine/core/error/
mod.rs
