Module module_rpc 

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.

Module RPC C API

This module provides C language bindings for DMSC’s module RPC (Remote Procedure Call) system. The module RPC system enables communication between different modules within the DMSC framework, providing a high-performance, type-safe mechanism for inter-module service calls. This C API enables C/C++ modules to participate in DMSC’s distributed architecture by registering services, making remote calls, and handling asynchronous responses.

Module Architecture

The module RPC system comprises three primary components:

• DMSCModuleRPC: Central RPC router and dispatcher managing service registration, method routing, and call dispatch across modules. The router handles the complete lifecycle of RPC operations including request routing, response aggregation, and error handling.

• DMSCModuleClient: Client interface for making RPC calls to registered services. The client provides synchronous and asynchronous call capabilities with automatic serialization, connection management, and retry logic.

• DMSCModuleEndpoint: Connection endpoint for module communication, managing the transport layer, protocol negotiation, and message framing. Endpoints can be local (in-process) or remote (network-based).

RPC Communication Model

The module RPC system implements a request-response communication model:

• Service Registration: Modules register services with method signatures, enabling discovery and invocation by other modules.

• Method Invocation: Clients call registered methods with serialized parameters, receiving serialized results or errors.

• Request Routing: The router dispatches requests to the appropriate service based on module and method names.

• Response Handling: Results are serialized and returned to the calling client, with support for streaming responses.

Module Discovery

The RPC system provides automatic module discovery:

• Service Registry: Central registry tracks all registered services and their availability status.

• Health Monitoring: Automatic health checks detect unavailable services and remove them from the routing table.

• Load Balancing: Requests distributed across multiple service instances when available.

• Service Dependencies: Dependency graph tracks module relationships for proper initialization and shutdown sequencing.

Serialization

The RPC system supports multiple serialization formats:

• Protocol Buffers: Default serialization with schema-based type safety. Provides efficient binary encoding with backward/forward compatibility.

• MessagePack: Binary serialization format for compact payloads with schema-less flexibility.

• JSON: Human-readable serialization for debugging and HTTP interoperability.

• Custom Codecs: Extension point for application-specific serialization.

Transport Mechanisms

The module RPC supports multiple transport mechanisms:

• In-Process: Zero-copy communication between modules in the same process. Fastest option for co-located modules.

• Shared Memory: High-performance communication using shared memory segments. Suitable for high-throughput, low-latency scenarios.

• TCP/IP: Network-based communication for distributed deployments. Supports TLS encryption and compression.

• Unix Domain Sockets: Local socket communication with near-in-process performance. Available on Unix-like systems.

Request Patterns

The RPC system supports various request patterns:

• Unary Calls: Simple request-response pattern with single request and response. Most common pattern for traditional RPC operations.

• Streaming Calls: Bidirectional streaming for large data transfers or real-time communication patterns.

• Batch Calls: Multiple independent requests batched into a single network round-trip for efficiency.

• Subscription Calls: Long-polling or push-based subscriptions for event notification patterns.

Error Handling

The RPC system implements comprehensive error handling:

• Transport Errors: Connection failures, timeouts, and protocol errors.

• Serialization Errors: Invalid input data, schema mismatches, codec failures.

• Service Errors: Application-level errors returned by the service handler.

• Routing Errors: Service not found, method not found, invalid parameters.

Performance Characteristics

RPC operations have the following performance profiles:

• In-process call latency: Near-zero, single function call overhead
• Serialization overhead: O(n) where n is message size
• Transport latency: O(1) for local, O(network) for remote
• Concurrent calls: Hundreds to thousands per endpoint

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
• Client stubs must be properly cleaned up after use
• Request/response buffers must be freed appropriately

Thread Safety

The underlying implementations are thread-safe:

• RPC router handles concurrent requests from multiple threads
• Client stubs support concurrent method invocations
• Service handlers invoked concurrently for each request
• Endpoint management uses internal synchronization

Usage Example

// Create RPC router instance
DMSCModuleRPC* rpc = dmsc_module_rpc_new();
if (rpc == NULL) {
    fprintf(stderr, "Failed to create RPC router\n");
    return ERROR_INIT;
}

// Register a service module
int result = dmsc_module_rpc_register_service(
    rpc,
    "UserService",
    user_service_handler,
    NULL  // user data passed to handler
);

if (result != 0) {
    fprintf(stderr, "Failed to register service\n");
}

// Create client for remote service
DMSCModuleClient* client = dmsc_module_client_new(rpc);
if (client == NULL) {
    fprintf(stderr, "Failed to create RPC client\n");
    dmsc_module_rpc_free(rpc);
    return ERROR_INIT;
}

// Configure request
DMSCUserRequest request = DMSCUSER_REQUEST_INIT;
request.user_id = 12345;
request.include_profile = true;

// Execute synchronous RPC call
DMSCUserResponse response = DMSCUSER_RESPONSE_INIT;
int status = dmsc_module_client_call(
    client,
    "UserService.GetUser",
    &request,
    &response,
    5000  // timeout in milliseconds
);

if (status == 0) {
    printf("User: %s %s\n", response.first_name, response.last_name);
} else {
    const char* error = dmsc_module_client_last_error(client);
    fprintf(stderr, "RPC error: %s (code: %d)\n", error, status);
}

// Cleanup
dmsc_module_client_free(client);
dmsc_module_rpc_free(rpc);

Dependencies

This module depends on the following DMSC components:

• crate::module_rpc: Rust module RPC implementation
• crate::prelude: Common types and traits
• Serialization framework (prost, serde, or custom)

Feature Flags

The module RPC module is enabled by the “module-rpc” feature flag. Disable this feature to reduce binary size when module RPC is not required.

Additional features:

• module-rpc-tls: Enable TLS for network transport
• module-rpc-streaming: Enable streaming RPC calls
• module-rpc-metrics: Enable RPC metrics collection

Structs

CDMSCModuleClient

CDMSCModuleEndpoint

CDMSCModuleRPC

Functions

dmsc_module_rpc_free

dmsc_module_rpc_new