Skip to main content

Module core

ri::c

Module core 

Source
Expand description

Copyright © 2025-2026 Wenze Wei. All Rights Reserved.

This file is part of Ri. The Ri project belongs to the Dunimd Team.

Licensed under the Apache License, Version 2.0 (the “License”); You may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

§Core Module C API

This module provides C language bindings for Ri’s core application infrastructure. The core module serves as the foundation for building Ri applications, providing application lifecycle management, configuration handling, and initialization routines. This C API enables C/C++ applications to leverage Ri’s powerful application builder and configuration management capabilities.

§Module Architecture

The core module comprises two essential components that form the backbone of any Ri application:

  • RiAppBuilder: Fluent builder pattern implementation for constructing Ri applications with type-safe configuration. The builder supports registration of modules, services, and middleware components through a declarative API. It handles dependency injection, service discovery, and lifecycle coordination across all registered components. The builder produces a fully initialized RiApp instance ready for execution.

  • RiConfig: Unified configuration management interface supporting multiple configuration sources including environment variables, command-line arguments, configuration files (YAML, TOML, JSON), and remote configuration services. The configuration system provides type-safe value retrieval with automatic type conversion, validation, and hot-reload capabilities for dynamic configuration updates in running applications.

§Application Lifecycle

Ri applications follow a well-defined lifecycle:

  1. Initialization Phase: Application builder creates and configures components. Services are registered, dependencies are wired, and configuration is loaded.

  2. Startup Phase: All registered services and modules are initialized in dependency order. Health checks verify component readiness.

  3. Running Phase: Application enters active state, processing requests or executing scheduled tasks. Components operate according to their configured behavior.

  4. Shutdown Phase: Graceful shutdown initiates component cleanup in reverse dependency order. Resources are released, connections are closed, and state is persisted as needed.

§Configuration System

The configuration module implements a hierarchical configuration model:

  • Sources: Environment variables override file-based settings, which override default values. Multiple sources can coexist with configurable precedence.

  • Formats: Native support for YAML, TOML, JSON configuration files. Each format has optimized parsing and schema validation.

  • Validation: Configuration values undergo validation against defined schemas. Type mismatches, missing required fields, and constraint violations are detected.

  • Hot Reload: Configuration files are monitored for changes. Updates are applied atomically without application restart. Subscribers are notified of changes.

§Memory Management

All C API objects use opaque pointers with manual memory management:

  • Constructor functions allocate new instances on the heap
  • Destructor functions must be called to release memory
  • Objects must not be used after being freed
  • Null pointer checks are required before all operations

§Thread Safety

The underlying Rust implementations are thread-safe:

  • Application builder operations require external synchronization
  • Configuration reads are concurrent-safe after initialization
  • Configuration writes require exclusive access

§Usage Example

// Create application configuration
CRiConfig* config = ri_config_new();

// Load configuration from file
int result = ri_config_load_file(config, "config.yaml");

// Get configuration value
char* value = ri_config_get_string(config, "database.url");

// Create application builder
CRiAppBuilder* builder = ri_app_builder_new();

// Configure builder with configuration
ri_app_builder_configure(builder, config);

// Build and run application
ri_app_builder_build(builder);

// Cleanup
ri_app_builder_free(builder);
ri_config_free(config);
ri_string_free(value);

§Dependencies

This module depends on the following Ri components:

  • crate::core: Rust core module implementation
  • crate::prelude: Common types and traits

§Feature Flags

The core module is always enabled as it provides fundamental infrastructure required by all other Ri components.

Structs§

CRiAppBuilder
Opaque C wrapper structure for RiAppBuilder.
CRiConfig
Opaque C wrapper structure for RiConfig.

Functions§

ri_app_builder_free
Frees a previously allocated CRiAppBuilder instance.
ri_app_builder_new
Creates a new CRiAppBuilder instance.
ri_config_free
Frees a previously allocated CRiConfig instance.
ri_config_get_string
Retrieves a string configuration value by key.
ri_config_new
Creates a new CRiConfig instance.