# memkit-co

<div align="center">

**Seamless CPU-GPU Memory Coordination for Performance Applications.**

[![Crates.io](https://img.shields.io/crates/v/memkit-co.svg?style=for-the-badge&color=blue)](https://crates.io/crates/memkit-co)
[![Documentation](https://img.shields.io/badge/docs.rs-memkit--co-green?style=for-the-badge)](https://docs.rs/memkit-co)
[![License: MPL-2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg?style=for-the-badge)](https://opensource.org/licenses/MPL-2.0)

</div>

---

## 🤝 The Bridge

`memkit-co` is the **coordination engine** of the memkit ecosystem. It bridges the gap between deterministic CPU allocations (`memkit`) and hardware-abstracted GPU resource management (`memkit-gpu`). 

By automating the transfer lifecycle, `memkit-co` allows developers to focus on logic rather than synchronizing memory barriers and staging buffer rotations.

## 💎 The Coordination Advantage

| Feature | Manual Management | memkit-co |
|---------|-------------------|-----------|
| **Transfers** | Explicit & Error-prone | Automatic & Batched |
| **Buffering** | Custom Double/Triple | Native Pipelined Support |
| **Logic** | Thread-blocking sync | Async-ready & Lock-free |
| **Flow** | Ad-hoc uploads | Structured Frame-based sync |

## ✨ Features

- 🔄 **Pipelined Buffering** — Native support for Double and Triple buffering schemes.
- 🏗️ **Frame Coordinator** — CPU allocations that automatically "teleport" to the GPU.
- 📦 **Staging Pool** — High-reuse buffer pool to minimize driver-level overhead.
- ⚡ **Auto-Batching** — Coalesces multiple small uploads into optimal GPU transfer operations.
- 🛡️ **Fence Tracking** — Integrated GPU work completion tracking.

## 🛠️ Quick Start

```rust
use memkit_co::{MkCoordinator, CoordinatorConfig, BufferingMode};
use memkit_gpu::DummyBackend;

// Create a coordinator with Triple Buffering enabled
let config = CoordinatorConfig {
    buffering: BufferingMode::Triple,
    ..Default::default()
};
let mut coordinator = MkCoordinator::new(DummyBackend::new(), config);

// Single-call "Upload & Forget"
let vertices: &[f32] = &[0.0, 0.5, 1.0, -0.5, -0.5, 1.0];
let gpu_buffer = coordinator.upload_slice(vertices).unwrap();

// Structured Frame Workflow
coordinator.begin_frame();
{
    // Allocate data on the CPU frame arena
    let transform = coordinator.frame_alloc::<[f32; 16]>();
    *transform = [1.0; 16];
    
    // Mark for automatic GPU upload at end of frame
    coordinator.stage_for_upload(transform);
}
coordinator.end_frame().unwrap(); // Batches all transfers and rotates buffers
```

## 🏗️ Architecture

```mermaid
graph LR
    subgraph CPU
        A[memkit Core]
    end
    subgraph Synchronization
        B[memkit-co Manager]
    end
    subgraph GPU
        C[memkit-gpu Backend]
    end
    A --> B
    B --> C
    C --> B
```

## 🔌 Ecosystem Integration

`memkit-co` acts as the glue that binds the specialized crates together:

- **Use `memkit`** for pure CPU arena allocation.
- **Use `memkit-gpu`** for low-level GPU backend access.
- **Use `memkit-co`** for automated synchronization between the two.

## ⚖️ License

Licensed under the **Mozilla Public License 2.0**. See [LICENSE.md](../LICENSE.md) for details.
