Module device 

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.

Device Module C API

This module provides C language bindings for DMSC’s device management subsystem. The device module delivers comprehensive device abstraction and control capabilities for managing various types of computational resources including CPU, GPU, memory, storage, network interfaces, sensors, and actuators. This C API enables C/C++ applications to leverage DMSC’s device orchestration features for resource management, scheduling, and hardware abstraction.

Module Architecture

The device management module comprises four primary components that together provide complete device lifecycle management:

• DMSCDevice: Fundamental device abstraction representing any computational resource. Each device instance encapsulates identity, type, capabilities, and state information. Devices can be queried for properties, monitored for status, and controlled through standardized interfaces regardless of underlying hardware implementation.

• DMSCDeviceController: Device control interface providing operational methods for device manipulation. The controller handles device initialization, configuration, activation, deactivation, and error recovery. Controllers implement device-specific logic while presenting a uniform control interface to the rest of the system.

• DMSCDeviceScheduler: Resource scheduling component for coordinating device usage across multiple requestors. The scheduler implements allocation policies, fair queuing, and priority-based scheduling to optimize device utilization while preventing resource contention. Supports both synchronous and asynchronous scheduling modes.

• DMSCDeviceType: Enumeration defining supported device categories. Each device type indicates the general class of hardware or resource being represented. The type system enables type-safe device operations and automatic dispatch to appropriate handlers.

Device Types

The device module supports the following device categories:

• CPU: Central processing unit resources. CPU devices provide processing capability for computational tasks. Scheduling considerations include core count, clock frequency, cache hierarchy, and instruction set capabilities.

• GPU: Graphics processing unit resources. GPU devices are specialized for parallel computation, machine learning inference, and graphics rendering. Support includes CUDA, OpenCL, and Vulkan compute capabilities.

• Memory: Random access memory resources. Memory devices represent available RAM that can be allocated for data processing. Considerations include capacity, latency, bandwidth, and memory hierarchy (cache, main memory, swap).

• Storage: Persistent storage resources. Storage devices provide durable data retention including SSDs, HDDs, and network storage. Performance characteristics include IOPS, throughput, latency, and durability ratings.

• Network: Network interface resources. Network devices enable communication with external systems. Properties include bandwidth, latency, protocol support, and connection state.

• Sensor: Data acquisition devices. Sensors collect environmental or system data including temperature, pressure, location, and system metrics. Support includes polling and event-driven data collection.

• Actuator: Action execution devices. Actuators perform physical or logical actions based on commands. Examples include motor controllers, relay switches, and service invocation endpoints.

• Custom: User-defined device types. Custom devices allow application-specific resource types beyond the standard categories. Custom types can implement any device-like behavior required by the application.

Device Lifecycle

Devices transition through well-defined lifecycle states:

1. DISCOVERED: Device detected but not yet configured or available for use
2. CONFIGURED: Device has been initialized with required settings
3. AVAILABLE: Device ready for allocation and operational use
4. ALLOCATED: Device assigned to a specific consumer or task
5. BUSY: Device actively executing operations
6. ERROR: Device encountered an error condition
7. UNAVAILABLE: Device temporarily or permanently unavailable
8. RELEASED: Device resources freed after allocation

Scheduling Policies

The device scheduler implements multiple allocation strategies:

• FIFO (First In, First Out): Requests processed in arrival order. Simple and predictable, suitable for uniform priority workloads.

• Priority-Based: Requests assigned priorities affecting scheduling order. Higher priority requests jump ahead of lower priority ones. Supports multiple priority levels with configurable behavior at each level.

• Fair-Sharing: Resources distributed equitably across requestors. Prevents any single consumer from monopolizing device capacity. Implements weighted fair queuing for proportional allocation.

• Deadline-Driven: Requests scheduled to meet deadline requirements. Suitable for real-time workloads with timing constraints. Requires deadline specification at request time.

• Load-Balancing: Requests distributed across multiple identical devices. Optimizes resource utilization and maximizes throughput for parallelizable work.

Device Capabilities

Each device advertises its capabilities through a standardized interface:

• Properties: Static characteristics including manufacturer, model, serial number, firmware version, and unique identifiers.

• Metrics: Dynamic measurements including utilization, temperature, error rates, and operational statistics. Metrics are sampled periodically or on demand.

• Capabilities: Supported operations and modes including read/write access, concurrent operation support, and specialized features.

• Constraints: Operational limits including maximum throughput, memory capacity, power limits, and environmental requirements.

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
• Device instances must be properly released after allocation
• Null pointer checks are required before all operations

Thread Safety

The underlying implementations are thread-safe:

• Device controllers handle concurrent access with internal synchronization
• Scheduler operations are thread-safe for multi-threaded request submission
• Device state queries can be performed concurrently
• Device control operations may require exclusive access

Performance Characteristics

Device operations have the following performance profiles:

• Device discovery: O(n) where n is number of potential devices
• Device allocation: O(1) average case, O(log n) for complex policies
• Metric collection: O(1) for cached metrics, O(n) for hardware sampling
• Scheduling decisions: O(1) for FIFO, O(log p) for priority (p = priority levels)

Usage Example

// Create a CPU device
DMSCDevice* cpu = dmsc_device_new("worker-node-1", DEVICE_TYPE_CPU);

// Create device controller
DMSCDeviceController* controller = dmsc_device_controller_new(cpu);

// Configure device
dmsc_device_controller_configure(controller, "max_frequency", "3000000000");

// Initialize device for use
int result = dmsc_device_controller_initialize(controller);

if (result == 0) {
    // Device ready, create scheduler
    DMSCDeviceScheduler* scheduler = dmsc_device_scheduler_new();

    // Register device with scheduler
    dmsc_device_scheduler_register(scheduler, cpu);

    // Allocate device for task
    DMSCDevice* allocated = dmsc_device_scheduler_allocate(scheduler,
        DEVICE_TYPE_CPU, PRIORITY_NORMAL);

    // Use device...

    // Release when done
    dmsc_device_scheduler_release(scheduler, allocated);
    dmsc_device_scheduler_free(scheduler);
}

// Cleanup
dmsc_device_controller_free(controller);
dmsc_device_free(cpu);

Dependencies

This module depends on the following DMSC components:

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

Feature Flags

The device module is always enabled as it provides fundamental infrastructure for resource management in DMSC applications.

Structs

CDMSCDevice

CDMSCDeviceController

CDMSCDeviceScheduler

Functions

dmsc_device_free

dmsc_device_new

Device type enumeration values.