Module core

dmsc::c

Module core 

Source
Expand description

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

This file is part of DMSC. The DMSC 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 DMSC’s core application infrastructure. The core module serves as the foundation for building DMSC applications, providing application lifecycle management, configuration handling, and initialization routines. This C API enables C/C++ applications to leverage DMSC’s powerful application builder and configuration management capabilities.

§Module Architecture

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

  • DMSCAppBuilder: Fluent builder pattern implementation for constructing DMSC 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 DMSCApp instance ready for execution.

  • DMSCConfig: 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

DMSC 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
CDMSCConfig* config = dmsc_config_new();

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

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

// Create application builder
CDMSCAppBuilder* builder = dmsc_app_builder_new();

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

// Build and run application
dmsc_app_builder_build(builder);

// Cleanup
dmsc_app_builder_free(builder);
dmsc_config_free(config);
dmsc_string_free(value);

§Dependencies

This module depends on the following DMSC 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 DMSC components.

Structs§

CDMSCAppBuilder
Opaque C wrapper structure for DMSCAppBuilder.
CDMSCConfig
Opaque C wrapper structure for DMSCConfig.

Functions§

dmsc_app_builder_free
Frees a previously allocated CDMSCAppBuilder instance.
dmsc_app_builder_new
Creates a new CDMSCAppBuilder instance.
dmsc_config_free
Frees a previously allocated CDMSCConfig instance.
dmsc_config_get_string
Retrieves a string configuration value by key.
dmsc_config_new
Creates a new CDMSCConfig instance.