/**
 * @file mvgal_pool.h
 * @brief MVGAL Network GPU Pool Manager
 *
 * Multi-Vendor GPU Aggregation Layer for Linux
 * Remote GPU discovery, pool management, and distributed scheduling.
 *
 * SPDX-License-Identifier: MIT
 */

#ifndef MVGAL_POOL_H
#define MVGAL_POOL_H

#include "mvgal_gpu.h"
#include "mvgal_network.h"

#ifdef __cplusplus
extern "C" {
#endif

/******************************************************************************
 * Pool Manager API
 ******************************************************************************/

/**
 * @brief Initialize the network GPU pool.
 *
 * Registers transport callbacks, starts discovery (if enabled),
 * and prepares the peer/GPU tracking tables.
 *
 * @param config  Network configuration (NULL = defaults)
 * @return 0 on success, -1 on failure
 */
int mvgal_pool_init(const mvgal_net_config_t *config);

/**
 * @brief Shut down the network GPU pool.
 *
 * Sends PEER_GOODBYE to all connected peers, stops discovery,
 * disconnects all transport connections, and frees pool state.
 */
void mvgal_pool_shutdown(void);

/**
 * @brief Get the number of remote GPUs currently online.
 *
 * @return Number of online remote GPUs, or 0 if pool not initialized
 */
int32_t mvgal_pool_get_remote_gpu_count(void);

/**
 * @brief Get a remote GPU as a local GPU descriptor.
 *
 * Maps the Nth online remote GPU to a mvgal_gpu_descriptor_t
 * suitable for use with the scheduler and execution engine.
 *
 * @param index  0-based index (0 .. count-1)
 * @param gpu    Descriptor to fill (out)
 * @return MVGAL_SUCCESS on success, error code on failure
 */
mvgal_error_t mvgal_pool_get_remote_gpu(uint32_t index, mvgal_gpu_descriptor_t *gpu);

/**
 * @brief Get pool-level network statistics.
 *
 * @param stats  Statistics structure to fill (out)
 * @return MVGAL_SUCCESS on success, error code on failure
 */
mvgal_error_t mvgal_pool_get_stats(mvgal_net_stats_t *stats);

#ifdef __cplusplus
}
#endif

#endif /* MVGAL_POOL_H */
