# Chimaera Standard Modules (ChiMods)

This repository contains the standard Chimaera modules that are automatically provided with the Chimaera runtime.

## Repository Structure

```
modules/
├── chimaera_repo.yaml    # Repository metadata
├── CMakeLists.txt        # Main build configuration
├── README.md            # This file
└── MOD_NAME/            # Example module
    ├── chimaera_mod.yaml       # Module metadata
    ├── CMakeLists.txt          # Module build configuration
    ├── autogen/                # Auto-generated code
    │   ├── MOD_NAME_methods.h  # Method constants
    │   └── MOD_NAME_lib_exec.h # Execution dispatcher
    ├── include/MOD_NAME/       # Public headers
    │   ├── MOD_NAME_client.h   # Client API
    │   └── MOD_NAME_tasks.h    # Task definitions
    └── src/                    # Implementation
        ├── MOD_NAME_client.cc  # Client implementation
        └── MOD_NAME_runtime.cc # Runtime implementation
```

## Modules

### MOD_NAME

A basic example module that demonstrates the ChiMod structure with two methods:
- `kCreate` (0): Initialize the container
- `kCustom` (10): Perform custom operations

The Custom method supports different operations based on `operation_id`:
- 0: Echo - Returns the input prefixed with "Echo: "
- 1: Reverse - Returns the reversed input string
- 2: Length - Returns the length of the input string

## Building

To build the ChiMods:

```bash
mkdir build
cd build
cmake ..
make
```

## Using a ChiMod

### Client Side

```cpp
#include <MOD_NAME/MOD_NAME_client.h>

// Create a client
chimaera::MOD_NAME::Client client(pool_id);

// Initialize the container
client.Create(HSHM_MCTX, chi::DomainQuery());

// Execute a custom operation
std::string output;
u32 result = client.Custom(
    HSHM_MCTX,
    chi::DomainQuery(),
    "Hello, World!",  // input data
    0,                // operation_id (0 = echo)
    output            // output data
);
```

### Runtime Side

The runtime automatically loads ChiMods from:
- Directories in `CHI_REPO_PATH` environment variable
- Directories in `LD_LIBRARY_PATH` environment variable
- Default system library directories

When a ChiMod is loaded, its runtime component handles task execution through the `Run`, `Monitor`, and `Del` methods.

## Creating a New ChiMod

1. Copy the MOD_NAME directory as a template
2. Rename all files and update namespaces
3. Update the `chimaera_mod.yaml` with your methods
4. Regenerate the autogen files (or update manually)
5. Implement your task structs in `*_tasks.h`
6. Implement the client API in `*_client.h`
7. Implement the runtime logic in `*_runtime.cc`
8. Add your module to the parent `CMakeLists.txt`

## ChiMod Interface

Every ChiMod must export these C functions:

```c
// Allocate a container (no initialization)
chi::ChiContainer* alloc_chimod();

// Create and initialize a container
chi::ChiContainer* new_chimod(const chi::PoolId* pool_id, const char* pool_name);

// Get the module name
const char* get_chimod_name();

// Destroy a container
void destroy_chimod(chi::ChiContainer* container);
```

These are automatically generated by the `CHI_CHIMOD_CC` macro in the runtime source file.

## Environment Variables

- `CHI_REPO_PATH`: Colon-separated list of directories containing ChiMod repositories
- `LD_LIBRARY_PATH`: Standard library path for loading shared libraries
- `CHI_SERVER_CONF`: Path to Chimaera server configuration file

## License

Apache License 2.0