Admin Module

Overview

The Admin Module is a critical component of the CLIO Runtime system that manages ChiPools and runtime lifecycle operations. It provides essential functionality for pool creation/destruction, runtime shutdown, and distributed task communication between nodes.

Key Responsibilities:

Pool management (creation, destruction)
Runtime lifecycle control (initialization, shutdown)
Distributed task routing and communication
Administrative operations (flush, monitoring)

CMake Integration

External Projects

To use the Admin Module in external projects:

find_package(clio-core CONFIG REQUIRED)    # Core CLIO Runtime + ClioCoreCommon.cmake
find_package(clio_run_admin REQUIRED)      # Admin Module package

target_link_libraries(your_application
  clio::run::admin_client       # Admin client library
  ${CMAKE_THREAD_LIBS_INIT}     # Threading support
)
# Core CLIO Runtime library dependencies are automatically included by Module libraries

Required Headers

#include <clio_runtime/clio_runtime.h>
#include <clio_runtime/admin/admin_client.h>
#include <clio_runtime/admin/admin_tasks.h>

API Reference

Client Class: `clio::run::admin::Client`

The Admin client provides the primary interface for interacting with the admin container.

Constructor

#include <clio_runtime/clio_runtime.h>
#include <clio_runtime/admin/admin_client.h>

void example() {
  // Default constructor (pool_id_ defaults to PoolId(0, 0))
  clio::run::admin::Client default_client;

  // Constructor with an explicit pool ID
  clio::run::admin::Client admin_client(clio::run::kAdminPoolId);
}

Container Management

`AsyncCreate()`

Creates and initializes the admin container asynchronously.

#include <string>
#include <clio_runtime/admin/admin_client.h>

clio::run::Future<clio::run::admin::CreateTask> AsyncCreate(
    const clio::run::PoolQuery& pool_query,
    const std::string& pool_name,
    const clio::run::PoolId& custom_pool_id);

Parameters:

pool_query: Pool domain query (typically clio::run::PoolQuery::Local())
pool_name: Pool name (MUST be "admin" for admin containers)
custom_pool_id: Explicit pool ID for the container

Returns: Future for asynchronous completion checking

Usage:

#include <iostream>
#include <clio_runtime/clio_runtime.h>
#include <clio_runtime/admin/admin_client.h>

void example() {
  clio::run::CLIO_INIT(clio::run::RuntimeMode::kClient, true);
  const clio::run::PoolId pool_id = clio::run::kAdminPoolId;  // Predefined admin pool ID
  clio::run::admin::Client admin_client(pool_id);

  auto pool_query = clio::run::PoolQuery::Local();
  auto task = admin_client.AsyncCreate(pool_query, "admin", pool_id);
  task.Wait();

  if (task->GetReturnCode() != 0) {
    std::cerr << "Admin creation failed" << std::endl;
    return;
  }
}

Pool Management Operations

`AsyncDestroyPool()`

Destroys an existing ChiPool asynchronously.

#include <clio_runtime/admin/admin_client.h>

clio::run::Future<clio::run::admin::DestroyPoolTask> AsyncDestroyPool(
    const clio::run::PoolQuery& pool_query,
    clio::run::PoolId target_pool_id,
    clio::run::u32 destruction_flags = 0);

Parameters:

pool_query: Pool domain query
target_pool_id: ID of the pool to destroy
destruction_flags: Optional flags controlling destruction behavior (default: 0)

Network Communication Operations

`AsyncSendPoll()` - Asynchronous

Creates a periodic task to poll the network queue and send outgoing messages.

#include <clio_runtime/admin/admin_client.h>

clio::run::Future<clio::run::admin::SendTask> AsyncSendPoll(
    const clio::run::PoolQuery& pool_query,
    clio::run::u32 transfer_flags = 0,
    double period_us = 25);

Parameters:

pool_query: Pool domain query
transfer_flags: Transfer behavior flags (default: 0)
period_us: Period in microseconds for polling (default: 25us, 0 = one-shot)

`AsyncRecv()` - Asynchronous

Creates a periodic task to receive incoming messages from the network.

#include <clio_runtime/admin/admin_client.h>

clio::run::Future<clio::run::admin::RecvTask> AsyncRecv(
    const clio::run::PoolQuery& pool_query,
    clio::run::u32 transfer_flags = 0,
    double period_us = 25);

Parameters:

pool_query: Pool domain query
transfer_flags: Transfer behavior flags (default: 0)
period_us: Period in microseconds for polling (default: 25us, 0 = one-shot)

Administrative Operations

`AsyncFlush()`

Flushes all administrative operations asynchronously.

#include <clio_runtime/admin/admin_client.h>

clio::run::Future<clio::run::admin::FlushTask> AsyncFlush(
    const clio::run::PoolQuery& pool_query);

Parameters:

pool_query: Pool domain query

Returns: Future for asynchronous completion checking

Runtime Control

`AsyncStopRuntime()` - Asynchronous Only

Stops the entire CLIO Runtime system.

#include <clio_runtime/admin/admin_client.h>

clio::run::Future<clio::run::admin::StopRuntimeTask> AsyncStopRuntime(
    const clio::run::PoolQuery& pool_query,
    clio::run::u32 shutdown_flags = 0,
    clio::run::u32 grace_period_ms = 5000);

Parameters:

pool_query: Pool domain query
shutdown_flags: Optional flags controlling shutdown behavior (default: 0)
grace_period_ms: Grace period in milliseconds for clean shutdown (default: 5000ms)

Note: This operation is only available asynchronously as the runtime shutdown process requires careful coordination.

Compose Operation

`AsyncCompose()` - Asynchronous

Creates a pool from a PoolConfig (for declarative pool creation).

#include <clio_runtime/clio_runtime.h>
#include <clio_runtime/config_manager.h>
#include <clio_runtime/admin/admin_client.h>

clio::run::Future<clio::run::admin::ComposeTask<clio::run::PoolConfig>> AsyncCompose(
    const clio::run::PoolConfig& pool_config);

Parameters:

pool_config: Configuration for the pool to create

Heartbeat Operation

`AsyncHeartbeat()` - Asynchronous

Liveness probe sent to a specific node.

#include <clio_runtime/admin/admin_client.h>

clio::run::Future<clio::run::admin::HeartbeatTask> AsyncHeartbeat(
    const clio::run::PoolQuery& pool_query);

Parameters:

pool_query: Pool routing (use clio::run::PoolQuery::Physical(node_id) to target a node)

Task Types

CreateTask

Container creation task for the admin module. This is an alias for clio::run::admin::BaseCreateTask<CreateParams, Method::kCreate, true>.

Key Fields:

Inherits from BaseCreateTask with admin-specific CreateParams
chimod_name_: Name of the Module being created
pool_name_: Name of the pool (must be "admin" for admin containers)
chimod_params_: Serialized parameters
new_pool_id_: Pool identifier (input/output)
return_code_: Operation result (0 = success)
error_message_: Error description if creation failed

DestroyPoolTask

Pool destruction task.

Key Fields:

target_pool_id_: ID of the pool to destroy
destruction_flags_: Flags controlling destruction behavior
return_code_: Operation result (0 = success)
error_message_: Error description if destruction failed

StopRuntimeTask

Runtime shutdown task.

Key Fields:

shutdown_flags_: Flags controlling shutdown behavior
grace_period_ms_: Grace period for clean shutdown
return_code_: Operation result (0 = success)
error_message_: Error description if shutdown failed

FlushTask

Administrative flush task.

Key Fields:

return_code_: Operation result (0 = success)
total_work_done_: Total work remaining across all containers

SendTask / RecvTask

Network communication tasks for sending and receiving messages.

Key Fields:

transfer_flags_: Transfer behavior flags
error_message_: Transfer result description

Configuration

CreateParams Structure

The admin module uses minimal configuration parameters:

struct CreateParams {
  // Required: chimod library name for the module manager
  static constexpr const char* chimod_lib_name = "clio_admin";

  // Default constructor
  CreateParams() = default;
};

Important: The chimod_lib_name does NOT include the _runtime suffix as it is automatically appended by the module manager.

Usage Examples

Basic Admin Container Setup

#include <iostream>
#include <clio_runtime/clio_runtime.h>
#include <clio_runtime/admin/admin_client.h>

int main() {
  // Initialize Clio runtime (client mode with embedded runtime)
  clio::run::CLIO_INIT(clio::run::RuntimeMode::kClient, true);

  // Create admin client with the predefined admin pool ID
  const clio::run::PoolId pool_id = clio::run::kAdminPoolId;
  clio::run::admin::Client admin_client(pool_id);

  // Create admin container asynchronously (pool name MUST be "admin")
  auto pool_query = clio::run::PoolQuery::Local();
  auto create_task = admin_client.AsyncCreate(pool_query, "admin", pool_id);
  create_task.Wait();

  if (create_task->GetReturnCode() != 0) {
    std::cerr << "Admin creation failed" << std::endl;
    return 1;
  }

  // Perform admin operations...
  auto flush_task = admin_client.AsyncFlush(pool_query);
  flush_task.Wait();

  return 0;
}

Pool Management

#include <iostream>
#include <clio_runtime/clio_runtime.h>
#include <clio_runtime/admin/admin_client.h>

void example() {
  clio::run::admin::Client admin_client(clio::run::kAdminPoolId);
  auto pool_query = clio::run::PoolQuery::Local();

  // Destroy a specific pool
  clio::run::PoolId target_pool(8000, 0);
  auto destroy_task = admin_client.AsyncDestroyPool(pool_query, target_pool);
  destroy_task.Wait();

  if (destroy_task->GetReturnCode() != 0) {
    std::cerr << "Pool destruction failed" << std::endl;
  } else {
    std::cout << "Pool destroyed successfully" << std::endl;
  }
}

Runtime Shutdown

#include <iostream>
#include <clio_runtime/clio_runtime.h>
#include <clio_runtime/admin/admin_client.h>

void example() {
  clio::run::admin::Client admin_client(clio::run::kAdminPoolId);
  auto pool_query = clio::run::PoolQuery::Local();

  // Gracefully stop the runtime with a 10 second grace period
  auto stop_task = admin_client.AsyncStopRuntime(pool_query, 0, 10000);  // 10 seconds

  // Don't wait for completion as the runtime will shut down
  std::cout << "Runtime shutdown initiated" << std::endl;
}

Dependencies

HermesShm: Shared memory framework and IPC
CLIO Runtime core runtime: Base runtime objects and task framework
cereal: Serialization library for network communication
Boost.Fiber and Boost.Context: Coroutine support

Installation

Build CLIO Runtime with the admin module:
```
cmake --preset debug
cmake --build build
```

Install to system or custom prefix:

cmake --install build --prefix /usr/local

For external projects, set CMAKE_PREFIX_PATH:

export CMAKE_PREFIX_PATH="/usr/local:/path/to/hermes-shm:/path/to/other/deps"

Error Handling

All operations are asynchronous and return clio::run::Future<TaskType>. Check the return code of the returned task after calling Wait():

0: Success
Non-zero: Error occurred (check error_message_ field)

Example:

#include <iostream>
#include <string>
#include <clio_runtime/clio_runtime.h>
#include <clio_runtime/admin/admin_client.h>

void example() {
  clio::run::admin::Client admin_client(clio::run::kAdminPoolId);
  auto pool_query = clio::run::PoolQuery::Local();
  clio::run::PoolId target_pool(8000, 0);

  auto task = admin_client.AsyncDestroyPool(pool_query, target_pool);
  task.Wait();

  if (task->GetReturnCode() != 0) {
    std::string error = task->error_message_.str();
    std::cerr << "Operation failed: " << error << std::endl;
  }
}

Important Notes

Pool ID for CreateTask: All Module CreateTask operations must use clio::run::kAdminPoolId, not the client's pool_id_.
Admin Pool Name: The admin pool name MUST always be "admin". Multiple admin pools are NOT supported.
Admin Dependency: The admin module is required by all other ChiMods and must be linked in all CLIO Runtime applications.
Future API: Asynchronous operations return clio::run::Future<TaskType>. Call .Wait() on the future and access task data with ->.
Pool Queries: Use clio::run::PoolQuery::Local() for local operations and clio::run::PoolQuery::Physical(node_id) for distributed operations.
Thread Safety: All operations are designed to be called from the main thread. Multi-threaded access requires external synchronization.

Overview​

CMake Integration​

External Projects​

Required Headers​

API Reference​

Client Class: clio::run::admin::Client​

Constructor​

Container Management​

AsyncCreate()​

Pool Management Operations​

AsyncDestroyPool()​

Network Communication Operations​

AsyncSendPoll() - Asynchronous​

AsyncRecv() - Asynchronous​

Administrative Operations​

AsyncFlush()​

Runtime Control​

AsyncStopRuntime() - Asynchronous Only​

Compose Operation​

AsyncCompose() - Asynchronous​

Heartbeat Operation​

AsyncHeartbeat() - Asynchronous​

Task Types​

CreateTask​

DestroyPoolTask​

StopRuntimeTask​

FlushTask​

SendTask / RecvTask​

Configuration​

CreateParams Structure​

Usage Examples​

Basic Admin Container Setup​

Pool Management​

Runtime Shutdown​

Dependencies​

Installation​

Error Handling​

Important Notes​

Overview

CMake Integration

External Projects

Required Headers

API Reference

Client Class: `clio::run::admin::Client`

Constructor

Container Management

`AsyncCreate()`

Pool Management Operations

`AsyncDestroyPool()`

Network Communication Operations

`AsyncSendPoll()` - Asynchronous

`AsyncRecv()` - Asynchronous

Administrative Operations

`AsyncFlush()`

Runtime Control

`AsyncStopRuntime()` - Asynchronous Only

Compose Operation

`AsyncCompose()` - Asynchronous

Heartbeat Operation

`AsyncHeartbeat()` - Asynchronous

Task Types

CreateTask

DestroyPoolTask

StopRuntimeTask

FlushTask

SendTask / RecvTask

Configuration

CreateParams Structure

Usage Examples

Basic Admin Container Setup

Pool Management

Runtime Shutdown

Dependencies

Installation

Error Handling

Important Notes