## Overview DAP Net Link Manager provides comprehensive link management and connection coordination functionality for the DAP ecosystem. This module handles link establishment, maintenance, monitoring, and optimization for network connections, ensuring reliable and efficient communication channels between DAP nodes and services. **Based on:** `dap-sdk/net/link-manager/include/dap_link_manager.h`, `dap-sdk/net/link-manager/src/dap_link_manager.c` ## Document Structure - [[#Overview|Overview]] - [[#Module Structures|Module Structures]] - [[#dap_link_manager_t|dap_link_manager_t - Link Manager]] - [[#dap_link_t|dap_link_t - Link Structure]] - [[#dap_link_pool_t|dap_link_pool_t - Connection Pool]] - [[#dap_link_stats_t|dap_link_stats_t - Link Statistics]] - [[#dap_link_config_t|dap_link_config_t - Configuration]] - [[#Module Functions|Module Functions]] - [[#Link Manager Operations|Manager Creation and Configuration]] - [[#Link Management|Link Lifecycle Operations]] - [[#Pool Management|Connection Pool Operations]] - [[#Monitoring Functions|Health and Performance Monitoring]] - [[#Error Codes|Error Codes]] - [[#Typical Examples|Typical Examples]] ## Module Structures ### dap_link_manager_t Core link manager structure coordinating all connection management operations. ```c typedef struct dap_link_manager { struct { char *manager_name; // Manager identifier name uint32_t active_links; // Number of active links uint32_t max_links; // Maximum allowed links dap_link_manager_state_t state; // Manager operational state uint64_t total_connections; // Total connections handled dap_time_t startup_time; // Manager startup timestamp dap_link_policy_t load_balance_policy; // Load balancing policy } pub; struct { dap_htable_t *link_table; // Active links hash table dap_list_t *link_pools; // Connection pools list dap_link_config_t *default_config; // Default link configuration pthread_mutex_t manager_mutex; // Manager synchronization dap_timer_t *health_check_timer; // Health monitoring timer dap_link_monitor_t *monitor; // Performance monitor dap_events_t *events_context; // Event handling context } priv; } dap_link_manager_t; ``` **Public Fields:** - `manager_name` - Unique identifier for the link manager instance - `active_links` - Current number of active managed links - `max_links` - Maximum number of concurrent links allowed - `state` - Current operational state (initializing, running, stopping) - `total_connections` - Counter of total connections handled since startup - `startup_time` - Timestamp when manager was initialized - `load_balance_policy` - Current load balancing algorithm in use ### dap_link_t Individual link structure representing a managed network connection. ```c typedef struct dap_link { struct { uint64_t link_id; // Unique link identifier char *remote_addr; // Remote address string uint16_t remote_port; // Remote port number dap_link_type_t type; // Link type (TCP, UDP, etc.) dap_link_state_t state; // Current link state dap_time_t established_time; // Link establishment time dap_time_t last_activity; // Last activity timestamp uint64_t bytes_sent; // Total bytes sent uint64_t bytes_received; // Total bytes received uint32_t quality_score; // Link quality metric (0-100) } pub; struct { dap_link_manager_t *manager; // Parent manager reference dap_events_socket_t *socket; // Underlying socket dap_link_pool_t *pool; // Associated connection pool dap_buffer_t *send_buffer; // Send buffer queue dap_buffer_t *recv_buffer; // Receive buffer pthread_mutex_t link_mutex; // Link synchronization dap_timer_t *keepalive_timer; // Keepalive timer dap_link_stats_t *statistics; // Detailed link statistics uint32_t error_count; // Accumulated error count dap_time_t last_error; // Last error timestamp } priv; } dap_link_t; ``` ### dap_link_pool_t Connection pool structure for managing groups of related links. ```c typedef struct dap_link_pool { struct { char *pool_name; // Pool identifier name uint32_t pool_size; // Current pool size uint32_t max_pool_size; // Maximum pool size uint32_t active_connections; // Active connections in pool dap_link_pool_strategy_t strategy; // Pool management strategy bool is_enabled; // Pool operational status uint64_t total_requests; // Total requests served } pub; struct { dap_list_t *available_links; // Available links list dap_list_t *busy_links; // Busy links list dap_queue_t *pending_requests; // Pending requests queue pthread_mutex_t pool_mutex; // Pool synchronization pthread_cond_t pool_cond; // Pool condition variable dap_link_pool_config_t *config; // Pool configuration dap_timer_t *cleanup_timer; // Cleanup timer dap_link_pool_stats_t *stats; // Pool statistics } priv; } dap_link_pool_t; ``` ### dap_link_stats_t Comprehensive link statistics structure for monitoring and optimization. ```c typedef struct dap_link_stats { struct { uint64_t packets_sent; // Total packets transmitted uint64_t packets_received; // Total packets received uint64_t packets_lost; // Estimated packet loss uint32_t average_latency_ms; // Average round-trip latency uint32_t current_bandwidth_bps; // Current bandwidth utilization uint32_t peak_bandwidth_bps; // Peak bandwidth recorded double packet_loss_rate; // Packet loss percentage uint32_t connection_failures; // Connection failure count } pub; struct { dap_time_t stats_start_time; // Statistics collection start uint64_t latency_samples[100]; // Latency sample buffer uint32_t sample_index; // Current sample index dap_bandwidth_tracker_t *bandwidth; // Bandwidth tracking dap_histogram_t *latency_histogram; // Latency distribution pthread_mutex_t stats_mutex; // Statistics synchronization } priv; } dap_link_stats_t; ``` ### dap_link_config_t Configuration structure for link behavior and policies. ```c typedef struct dap_link_config { struct { uint32_t connection_timeout_ms; // Connection establishment timeout uint32_t keepalive_interval_sec; // Keepalive frequency uint32_t max_retries; // Maximum retry attempts uint32_t retry_delay_ms; // Delay between retries bool auto_reconnect; // Automatic reconnection uint32_t health_check_interval_sec; // Health check frequency uint32_t idle_timeout_sec; // Idle connection timeout } pub; struct { uint32_t buffer_size; // I/O buffer size bool enable_compression; // Data compression dap_enc_key_type_t encryption_type; // Encryption algorithm uint32_t congestion_window; // TCP congestion window bool enable_nagle; // Nagle algorithm uint32_t socket_buffer_size; // Socket buffer size dap_qos_policy_t qos_policy; // Quality of service policy } priv; } dap_link_config_t; ``` ## Module Functions ### Link Manager Operations #### `dap_link_manager_create()` Creates new link manager instance with specified configuration. ```c dap_link_manager_t* dap_link_manager_create(const char *a_manager_name, const dap_link_config_t *a_config); ``` **Parameters:** - `a_manager_name` (const char*) - Unique name for the link manager - `a_config` (const dap_link_config_t*) - Configuration parameters **Returns:** - `dap_link_manager_t*` - Created link manager instance - `NULL` - Manager creation failed **Error Conditions:** - Returns NULL if a_manager_name is NULL or empty - Returns NULL if memory allocation fails - Returns NULL if configuration validation fails **Description:** Creates a new link manager with specified configuration including connection limits, health monitoring settings, and load balancing policies. #### `dap_link_manager_destroy()` Destroys link manager and closes all managed links. ```c void dap_link_manager_destroy(dap_link_manager_t *a_manager); ``` **Parameters:** - `a_manager` (dap_link_manager_t*) - Manager to destroy **Description:** Gracefully shuts down all managed links, cleans up resources, and frees memory. #### `dap_link_manager_start()` Starts the link manager operation. ```c int dap_link_manager_start(dap_link_manager_t *a_manager); ``` **Parameters:** - `a_manager` (dap_link_manager_t*) - Manager to start **Returns:** - `0` - Manager started successfully - `-1` - Invalid manager parameter - `-2` - Manager already running - `-3` - System resource allocation failed #### `dap_link_manager_stop()` Stops the link manager gracefully. ```c int dap_link_manager_stop(dap_link_manager_t *a_manager); ``` ### Link Management #### `dap_link_create()` Creates new managed link to specified destination. ```c dap_link_t* dap_link_create(dap_link_manager_t *a_manager, const char *a_addr, uint16_t a_port, dap_link_type_t a_type); ``` **Parameters:** - `a_manager` (dap_link_manager_t*) - Parent link manager - `a_addr` (const char*) - Destination address - `a_port` (uint16_t) - Destination port - `a_type` (dap_link_type_t) - Link type (TCP, UDP, etc.) **Returns:** - `dap_link_t*` - Created link instance - `NULL` - Link creation failed **Error Conditions:** - Returns NULL if a_manager is NULL or not running - Returns NULL if a_addr is invalid - Returns NULL if maximum link limit reached #### `dap_link_connect()` Establishes connection for the link. ```c int dap_link_connect(dap_link_t *a_link); ``` **Parameters:** - `a_link` (dap_link_t*) - Link to connect **Returns:** - `0` - Connection established successfully - `-1` - Invalid link parameter - `-2` - Connection timeout - `-3` - Connection refused #### `dap_link_disconnect()` Disconnects and closes the link. ```c int dap_link_disconnect(dap_link_t *a_link); ``` #### `dap_link_send_data()` Sends data through the link. ```c ssize_t dap_link_send_data(dap_link_t *a_link, const void *a_data, size_t a_data_size); ``` **Parameters:** - `a_link` (dap_link_t*) - Link to send data through - `a_data` (const void*) - Data to send - `a_data_size` (size_t) - Size of data **Returns:** - `>= 0` - Number of bytes sent - `-1` - Send operation failed ### Pool Management #### `dap_link_pool_create()` Creates new connection pool for link management. ```c dap_link_pool_t* dap_link_pool_create(const char *a_pool_name, uint32_t a_max_size, dap_link_pool_strategy_t a_strategy); ``` **Parameters:** - `a_pool_name` (const char*) - Pool identifier name - `a_max_size` (uint32_t) - Maximum pool size - `a_strategy` (dap_link_pool_strategy_t) - Pool management strategy **Returns:** - `dap_link_pool_t*` - Created pool instance - `NULL` - Pool creation failed #### `dap_link_pool_get_link()` Retrieves available link from pool. ```c dap_link_t* dap_link_pool_get_link(dap_link_pool_t *a_pool); ``` #### `dap_link_pool_return_link()` Returns link to the pool after use. ```c int dap_link_pool_return_link(dap_link_pool_t *a_pool, dap_link_t *a_link); ``` ### Monitoring Functions #### `dap_link_get_stats()` Retrieves comprehensive link statistics. ```c dap_link_stats_t* dap_link_get_stats(dap_link_t *a_link); ``` **Parameters:** - `a_link` (dap_link_t*) - Link to get statistics for **Returns:** - `dap_link_stats_t*` - Link statistics structure - `NULL` - Statistics not available #### `dap_link_check_health()` Performs health check on link. ```c int dap_link_check_health(dap_link_t *a_link); ``` **Parameters:** - `a_link` (dap_link_t*) - Link to check **Returns:** - `1` - Link is healthy - `0` - Link has issues - `-1` - Health check failed ## Error Codes ### Link Manager Error Codes ```c typedef enum dap_link_manager_error { DAP_LINK_MANAGER_SUCCESS = 0, // Operation successful DAP_LINK_MANAGER_ERROR_INVALID_PARAM = -1, // Invalid parameter provided DAP_LINK_MANAGER_ERROR_NO_MEMORY = -2, // Memory allocation failed DAP_LINK_MANAGER_ERROR_LIMIT_REACHED = -3, // Link limit reached DAP_LINK_MANAGER_ERROR_NOT_RUNNING = -4, // Manager not running DAP_LINK_MANAGER_ERROR_CONNECTION_FAILED = -5, // Connection failed DAP_LINK_MANAGER_ERROR_TIMEOUT = -6, // Operation timeout DAP_LINK_MANAGER_ERROR_POOL_FULL = -7, // Connection pool full DAP_LINK_MANAGER_ERROR_LINK_NOT_FOUND = -8, // Link not found DAP_LINK_MANAGER_ERROR_CONFIG_INVALID = -9 // Invalid configuration } dap_link_manager_error_t; ``` ## Typical Examples ### Basic Link Manager Example ```c #include "dap_common.h" #include "dap_link_manager.h" int example_link_manager() { log_it(L_INFO, "=== Link Manager Example ==="); // Step 1: Create link configuration dap_link_config_t config = { .pub.connection_timeout_ms = 5000, .pub.keepalive_interval_sec = 30, .pub.max_retries = 3, .pub.retry_delay_ms = 1000, .pub.auto_reconnect = true, .pub.health_check_interval_sec = 60, .pub.idle_timeout_sec = 300, .priv.buffer_size = 8192, .priv.enable_compression = true, .priv.encryption_type = DAP_ENC_KEY_TYPE_AES256 }; // Step 2: Create link manager dap_link_manager_t *manager = dap_link_manager_create("main_manager", &config); if (!manager) { log_it(L_ERROR, "✗ Failed to create link manager"); return -1; } log_it(L_INFO, "✓ Link manager 'main_manager' created"); // Step 3: Start manager int result = dap_link_manager_start(manager); if (result != 0) { log_it(L_ERROR, "✗ Failed to start link manager: %d", result); dap_link_manager_destroy(manager); return -1; } log_it(L_INFO, "✓ Link manager started successfully"); // Step 4: Create links to different servers const char* servers[] = {"192.168.1.100", "192.168.1.101", "192.168.1.102"}; dap_link_t *links[3]; for (int i = 0; i < 3; i++) { links[i] = dap_link_create(manager, servers[i], 8080, DAP_LINK_TYPE_TCP); if (!links[i]) { log_it(L_ERROR, "✗ Failed to create link to %s", servers[i]); continue; } log_it(L_DEBUG, "✓ Link created to %s:8080", servers[i]); // Connect the link result = dap_link_connect(links[i]); if (result == 0) { log_it(L_INFO, "✓ Connected to %s:8080 (Link ID: %lu)", servers[i], links[i]->pub.link_id); } else { log_it(L_ERROR, "✗ Failed to connect to %s: %d", servers[i], result); } } // Step 5: Send test data through first link if (links[0] && links[0]->pub.state == DAP_LINK_STATE_CONNECTED) { const char *test_data = "Hello from Link Manager!"; ssize_t sent = dap_link_send_data(links[0], test_data, strlen(test_data)); if (sent > 0) { log_it(L_INFO, "✓ Sent %zd bytes through link %lu", sent, links[0]->pub.link_id); } else { log_it(L_ERROR, "✗ Failed to send data through link"); } } // Step 6: Check link statistics for (int i = 0; i < 3; i++) { if (links[i]) { dap_link_stats_t *stats = dap_link_get_stats(links[i]); if (stats) { log_it(L_INFO, "Link %lu Stats:", links[i]->pub.link_id); log_it(L_INFO, " Bytes sent: %lu", stats->pub.bytes_sent); log_it(L_INFO, " Bytes received: %lu", stats->pub.bytes_received); log_it(L_INFO, " Quality score: %u", links[i]->pub.quality_score); log_it(L_INFO, " Average latency: %u ms", stats->pub.average_latency_ms); } } } // Step 7: Cleanup for (int i = 0; i < 3; i++) { if (links[i]) { dap_link_disconnect(links[i]); log_it(L_DEBUG, "✓ Link %lu disconnected", links[i]->pub.link_id); } } dap_link_manager_stop(manager); dap_link_manager_destroy(manager); log_it(L_INFO, "✓ Link Manager example completed"); return 0; } ``` ### Connection Pool Example ```c #include "dap_common.h" #include "dap_link_manager.h" int example_connection_pool() { log_it(L_INFO, "=== Connection Pool Example ==="); // Step 1: Create link manager dap_link_config_t config = { .pub.connection_timeout_ms = 3000, .pub.max_retries = 2, .pub.auto_reconnect = true }; dap_link_manager_t *manager = dap_link_manager_create("pool_manager", &config); if (!manager) { log_it(L_ERROR, "✗ Failed to create manager"); return -1; } dap_link_manager_start(manager); // Step 2: Create connection pool dap_link_pool_t *pool = dap_link_pool_create("web_server_pool", 10, DAP_LINK_POOL_STRATEGY_ROUND_ROBIN); if (!pool) { log_it(L_ERROR, "✗ Failed to create connection pool"); goto cleanup; } log_it(L_INFO, "✓ Connection pool created with max size 10"); // Step 3: Pre-populate pool with connections for (int i = 0; i < 5; i++) { dap_link_t *link = dap_link_create(manager, "web.example.com", 80, DAP_LINK_TYPE_TCP); if (link && dap_link_connect(link) == 0) { dap_link_pool_return_link(pool, link); log_it(L_DEBUG, "✓ Added link %lu to pool", link->pub.link_id); } } log_it(L_INFO, "✓ Pool populated with %u connections", pool->pub.pool_size); // Step 4: Simulate requests using pool for (int request = 0; request < 8; request++) { dap_link_t *link = dap_link_pool_get_link(pool); if (link) { log_it(L_INFO, "Request %d: Using link %lu from pool", request + 1, link->pub.link_id); // Simulate some work const char *http_request = "GET / HTTP/1.1\r\nHost: web.example.com\r\n\r\n"; dap_link_send_data(link, http_request, strlen(http_request)); // Simulate processing time usleep(100000); // 100ms // Return link to pool dap_link_pool_return_link(pool, link); log_it(L_DEBUG, "✓ Link %lu returned to pool", link->pub.link_id); } else { log_it(L_WARNING, "Request %d: No available links in pool", request + 1); } } // Step 5: Display pool statistics log_it(L_INFO, "Pool Statistics:"); log_it(L_INFO, " Total requests served: %lu", pool->pub.total_requests); log_it(L_INFO, " Active connections: %u", pool->pub.active_connections); log_it(L_INFO, " Pool size: %u", pool->pub.pool_size); cleanup: if (pool) { dap_link_pool_destroy(pool); } dap_link_manager_stop(manager); dap_link_manager_destroy(manager); log_it(L_INFO, "✓ Connection Pool example completed"); return 0; } ``` --- **See also:** [[Module DAP Net - Client|Module DAP Net - Client]], [[Module DAP Net - Server|Module DAP Net - Server]], [[Module DAP Net - Stream|Module DAP Net - Stream]] --- *Based on: `dap-sdk/net/link-manager/include/dap_link_manager.h`, `dap-sdk/net/link-manager/src/dap_link_manager.c`*