lib-shim-v2 API参考手册：容器操作接口的详细解析

【免费下载链接】lib-shim-v2As a shim V2 ttrpc client, it is called by iSulad and written in rust项目地址: https://gitcode.com/openeuler/lib-shim-v2

前往项目官网免费下载：https://ar.openeuler.org/ar/

欢迎来到lib-shim-v2 API参考手册！作为openEuler生态系统中关键的容器运行时组件，lib-shim-v2为iSulad容器引擎提供了强大的Shim V2 ttrpc客户端功能。本指南将深入解析这个Rust编写的容器操作接口，帮助您快速掌握容器生命周期管理的核心技术。无论您是容器开发新手还是经验丰富的系统管理员，这份详细的API参考手册都将为您提供宝贵的实践指导。

📋 什么是lib-shim-v2？

lib-shim-v2是一个专门为iSulad容器引擎设计的Shim V2 ttrpc客户端库，采用Rust语言编写。它作为容器运行时与容器管理器之间的桥梁，负责处理容器的生命周期操作、进程管理和资源监控等核心功能。通过标准化的API接口，lib-shim-v2确保了容器操作的一致性和可靠性。

🚀 核心API接口详解

容器创建与启动接口

shim_v2_create- 创建新容器实例

pub extern "C" fn shim_v2_create( container_id: *const c_char, bundle: *const c_char, terminal: bool, stdin: *const c_char, stdout: *const c_char, stderr: *const c_char, pid: &mut c_int, ) -> c_int

这个关键函数负责初始化一个新的容器实例。它接收容器ID、bundle路径、终端配置和标准I/O流参数，返回容器的进程ID。函数定义位于 src/lib.rs#L60-L100，是容器生命周期的起点。

shim_v2_start- 启动已创建的容器

pub extern "C" fn shim_v2_start( container_id: *const c_char, exec_id: *const c_char, pid: &mut c_int, ) -> c_int

启动函数激活容器进程，使其进入运行状态。该接口在 src/lib.rs#L103-L124 中定义，是容器从"创建"到"运行"状态转换的关键步骤。

容器进程管理接口

shim_v2_exec- 在容器内执行命令

pub extern "C" fn shim_v2_exec( container_id: *const c_char, exec_id: *const c_char, terminal: bool, stdin: *const c_char, stdout: *const c_char, stderr: *const c_char, spec: *const c_char, ) -> c_int

这个强大的执行接口允许在运行中的容器内部启动新进程。它支持完整的终端配置和I/O重定向，定义在 src/lib.rs#L197-L241。

shim_v2_kill- 发送信号到容器进程

pub extern "C" fn shim_v2_kill( container_id: *const c_char, exec_id: *const c_char, signal: u32, all: bool, ) -> c_int

信号管理接口提供了对容器进程的精确控制，支持向特定进程或所有相关进程发送信号。查看 src/lib.rs#L127-L148 了解详细实现。

容器生命周期控制接口

shim_v2_pause和shim_v2_resume- 暂停与恢复容器

pub extern "C" fn shim_v2_pause(container_id: *const c_char) -> c_int pub extern "C" fn shim_v2_resume(container_id: *const c_char) -> c_int

这对函数提供了容器的暂停和恢复功能，对于资源调度和故障排查非常有用。它们分别在 src/lib.rs#L274-L288 和 src/lib.rs#L291-L305 中实现。

shim_v2_delete- 删除容器资源

pub extern "C" fn shim_v2_delete( container_id: *const c_char, exec_id: *const c_char, resp: &mut DeleteResponse, ) -> c_int

清理接口负责释放容器占用的所有资源，返回退出状态和进程信息。完整实现在 src/lib.rs#L157-L177。

容器状态监控接口

shim_v2_state- 获取容器状态信息

pub extern "C" fn shim_v2_state(container_id: *const c_char, state: &mut State) -> c_int

状态查询接口返回容器的当前运行状态、进程ID和创建时间等信息。State结构体定义在 src/lib.rs#L333-L342。

shim_v2_stats- 收集容器性能指标

pub extern "C" fn shim_v2_stats(container_id: *const c_char, stats: &mut Stats) -> c_int

性能监控接口收集CPU、内存、磁盘和网络等关键指标。Stats结构体详细定义见 src/lib.rs#L376-L400。

shim_v2_pids- 获取容器进程列表

pub extern "C" fn shim_v2_pids(container_id: *const c_char, pid: &mut c_int) -> c_int

进程列表接口帮助管理员了解容器内部运行的进程情况，定义在 src/lib.rs#L446-L461。

🔧 错误处理与返回值

所有lib-shim-v2 API函数都遵循统一的错误处理模式：

• 返回值0：操作成功完成
• 返回值-1：操作失败，具体错误信息会输出到日志

每个函数都包含详细的日志输出，便于问题排查：

println!("lib-shim-v2::create::{}:: done.", r_container_id); println!("lib-shim-v2::create::{}:: failed, {}.", r_container_id, e);

📁 项目结构与源码组织

lib-shim-v2项目采用清晰的模块化设计：

├── src/ │ ├── client/ # 客户端核心逻辑 │ │ ├── client.rs # 客户端实现 │ │ ├── error.rs # 错误处理 │ │ └── mod.rs # 模块导出 │ ├── protocols/ # 协议定义 │ │ └── protos/ # Protobuf定义 │ └── lib.rs # 主API接口 ├── shim_v2.h # C头文件 └── Cargo.toml # Rust项目配置

🛠️ 快速开始指南

编译与集成

要使用lib-shim-v2，首先需要克隆项目仓库：

git clone https://gitcode.com/openeuler/lib-shim-v2 cd lib-shim-v2 cargo build --release

基本使用示例

以下是一个简单的使用示例，展示如何创建和启动容器：

#include "shim_v2.h" int main() { const char* container_id = "my-container"; const char* bundle = "/path/to/bundle"; int pid; // 创建容器 int result = shim_v2_new(container_id, "/run/containerd/shim.sock"); if (result != 0) { // 错误处理 } // 启动容器进程 result = shim_v2_create(container_id, bundle, false, "/dev/null", "/dev/null", "/dev/null", &pid); // ... 更多操作 }

🎯 最佳实践建议

1. 资源管理：确保及时调用shim_v2_delete释放不再使用的容器资源
2. 错误处理：始终检查API返回值，结合日志输出进行问题诊断
3. 并发安全：lib-shim-v2设计为线程安全，但建议对同一容器的操作进行序列化
4. 性能监控：定期使用shim_v2_stats收集性能数据，优化容器配置

🔍 调试与故障排除

当遇到问题时，可以：

1. 检查日志输出：所有API调用都有详细的日志记录
2. 验证参数：确保传入的参数格式正确，特别是字符串参数
3. 查看返回码：-1返回值通常意味着底层连接或参数问题
4. 检查依赖：确保ttrpc服务正常运行

📚 深入学习资源

要进一步深入理解lib-shim-v2的实现细节，建议阅读：

• src/client/client.rs - 客户端核心实现
• src/protocols/protos/ - 协议定义文件
• shim_v2.h - C语言接口定义

🚀 总结

lib-shim-v2作为openEuler容器生态的关键组件，提供了完整、可靠的容器操作接口。通过本API参考手册，您已经掌握了所有核心接口的使用方法和最佳实践。无论是进行容器开发、系统集成还是性能优化，lib-shim-v2都能为您提供强大的支持。

记住，成功的容器管理不仅需要正确的API调用，更需要对容器生命周期的深入理解。祝您在容器技术的道路上越走越远！ 🎉

提示：本文档基于lib-shim-v2最新版本编写，具体实现细节请参考实际源码。如有疑问，欢迎查阅项目文档或参与社区讨论。

【免费下载链接】lib-shim-v2As a shim V2 ttrpc client, it is called by iSulad and written in rust项目地址: https://gitcode.com/openeuler/lib-shim-v2