void recursive_function(int depth) {
    char buffer[1024];  // 在栈上分配 1KB
    if (depth > 0) recursive_function(depth - 1);  // 递归调用
}

#include <ucontext.h>

ucontext_t ctx;  // 存储CPU状态：寄存器、栈指针、程序计数器等

// 获取当前上下文
getcontext(&ctx);

// 修改上下文，设置新的入口函数和栈
makecontext(&ctx, (void (*)(void))entry_func, argc, arg1, arg2, ...);

// 保存当前上下文到 old_ctx，然后跳转到 new_ctx
swapcontext(&old_ctx, &new_ctx);

ucontext_t main_ctx, co_ctx;
char stack[1024*1024];  // 1MB 栈

getcontext(&co_ctx);
co_ctx.uc_stack.ss_sp = stack;
co_ctx.uc_stack.ss_size = sizeof(stack);
co_ctx.uc_link = &main_ctx;  // 协程结束后回到 main_ctx

makecontext(&co_ctx, coroutine_entry, 0);

// 跳转到协程，协程结束后自动回到这里
swapcontext(&main_ctx, &co_ctx);

// 协程状态
#define COROUTINE_DEAD    0  // 已结束
#define COROUTINE_READY   1  // 新建，未运行
#define COROUTINE_RUNNING 2  // 正在运行
#define COROUTINE_SUSPEND 3  // 已 yield，等待恢复

// 调度器：管理所有协程
struct schedule {
    char stack[STACK_SIZE];      // 共享栈！1MB，所有协程共用
    ucontext_t main;             // 主上下文（resume/yield 的落脚点）
    int nco;                     // 当前协程数
    int cap;                     // 协程数组容量
    int running;                 // 当前运行的协程 ID，-1 表示无
    struct coroutine **co;       // 协程指针数组
};

// 单个协程
struct coroutine {
    coroutine_func func;         // 协程函数
    void *ud;                    // 用户数据
    ucontext_t ctx;              // 上下文（寄存器状态）
    struct schedule *sch;        // 所属调度器
    ptrdiff_t cap;               // 私有栈容量
    ptrdiff_t size;              // 私有栈实际大小
    int status;                  // 状态
    char *stack;                 // 私有栈（yield 时保存共享栈内容）
};

struct schedule *S = coroutine_open();

int co_id = coroutine_new(S, my_coroutine_func, user_data);

getcontext(&C->ctx);                    // 初始化上下文
C->ctx.uc_stack.ss_sp = S->stack;       // 使用共享栈！
C->ctx.uc_stack.ss_size = STACK_SIZE;
C->ctx.uc_link = &S->main;              // 结束后回到主流程
makecontext(&C->ctx, mainfunc, 2, ...); // 设置入口函数
swapcontext(&S->main, &C->ctx);         // 跳转！

// 恢复：把保存的私有栈复制回共享栈
memcpy(S->stack + STACK_SIZE - C->size, C->stack, C->size);
swapcontext(&S->main, &C->ctx);         // 跳转！

void coroutine_yield(struct schedule *S) {
    // 保存当前共享栈内容到私有栈
    _save_stack(C, S->stack + STACK_SIZE);

    C->status = COROUTINE_SUSPEND;
    S->running = -1;

    // 切回主流程
    swapcontext(&C->ctx, &S->main);
}

static void _save_stack(struct coroutine *C, char *top) {
    char dummy = 0;  // 局部变量，在当前栈顶附近

    // top 是共享栈底，&dummy 是当前栈顶
    // 两者差值就是当前协程使用的栈大小
    C->size = top - &dummy;

    if (C->cap < C->size) {
        free(C->stack);
        C->stack = malloc(C->size);  // 按需分配
        C->cap = C->size;
    }

    memcpy(C->stack, &dummy, C->size);  // 复制到私有栈
}

void foo(struct schedule *S, void *ud) {
    for (int i = 0; i < 3; i++) {
        printf("iteration %d\n", i);
        coroutine_yield(S);  // 让出
    }
}

int main() {
    struct schedule *S = coroutine_open();
    int co = coroutine_new(S, foo, NULL);

    while (coroutine_status(S, co) != COROUTINE_DEAD) {
        coroutine_resume(S, co);
    }

    coroutine_close(S);
    return 0;
}

void foo(struct schedule *S, void *ud) {
    int start = *(int*)ud;
    for (int i = 0; i < 5; i++) {
        printf("coroutine %d: %d\n", coroutine_running(S), start + i);
        coroutine_yield(S);
    }
}

int main() {
    struct schedule *S = coroutine_open();

    int arg1 = 0, arg2 = 100;
    int co1 = coroutine_new(S, foo, &arg1);
    int co2 = coroutine_new(S, foo, &arg2);

    while (coroutine_status(S, co1) && coroutine_status(S, co2)) {
        coroutine_resume(S, co1);
        coroutine_resume(S, co2);
    }

    coroutine_close(S);
}

/**
 * ============================================================================
 * 用 300 行 C 代码实现一个协程库：共享栈与 ucontext 的艺术
 * ============================================================================
 *
 * 本文件是一个完整的协程库实现，并添加了详细的中文注释，方便学习理解。
 *
 * 核心特性：
 * 1. 使用 POSIX ucontext 实现用户态上下文切换
 * 2. 采用共享栈设计，所有协程共用一个 1MB 栈空间
 * 3. 非对称协程模型：resume/yield 配对使用
 *
 * 编译命令：gcc -o coroutine_tutorial coroutine_tutorial.c
 * 运行命令：./coroutine_tutorial
 */

#include <assert.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/* 平台兼容性处理：macOS 和 Linux 的 ucontext 头文件位置不同 */
#if __APPLE__ && __MACH__
#include <sys/ucontext.h>
#else
#include <ucontext.h>
#endif

/* ============================================================================
 * 第一部分：常量定义
 * ============================================================================
 */

/* 共享栈大小：1MB，所有协程共用这个栈空间 */
#define STACK_SIZE (1024 * 1024)

/* 协程数组默认容量 */
#define DEFAULT_COROUTINE 16

/* ============================================================================
 * 第二部分：协程状态定义
 * ============================================================================
 *
 * 协程有四种状态，形成一个生命周期：
 *
 *   READY ──resume──> RUNNING ──yield──> SUSPEND
 *                      │                    │
 *                      │                    └──resume──> RUNNING
 *                      │
 *                      └──执行完毕──> DEAD
 */

#define COROUTINE_DEAD 0    /* 已结束：协程函数执行完毕 */
#define COROUTINE_READY 1   /* 就绪态：新创建，从未运行过 */
#define COROUTINE_RUNNING 2 /* 运行态：正在执行 */
#define COROUTINE_SUSPEND 3 /* 挂起态：已 yield，等待恢复 */

/* ============================================================================
 * 第三部分：核心数据结构
 * ============================================================================
 */

/* 前向声明 */
struct schedule;

/**
 * 协程函数类型
 *
 * @param S  调度器指针，用于调用 yield 等 API
 * @param ud 用户数据指针，在创建协程时传入
 *
 * 示例：
 *   void my_coroutine(struct schedule *S, void *ud) {
 *       int *data = (int *)ud;
 *       printf("数据: %d\n", *data);
 *       coroutine_yield(S);  // 让出控制权
 *   }
 */
typedef void (*coroutine_func)(struct schedule* S, void* ud);

/**
 * 单个协程结构体
 *
 * 每个协程都有独立的这个结构体来保存其状态，
 * 但所有协程共享同一个栈空间（schedule.stack）。
 */
struct coroutine {
  coroutine_func func;  /* 协程入口函数 */
  void* ud;             /* 用户数据，传递给协程函数 */
  ucontext_t ctx;       /* 上下文：保存寄存器状态、栈指针等 */
  struct schedule* sch; /* 所属调度器的指针 */

  ptrdiff_t cap;  /* 私有栈容量：已分配的字节数 */
  ptrdiff_t size; /* 私有栈实际大小：当前使用的字节数 */

  int status;  /* 当前状态：READY/RUNNING/SUSPEND/DEAD */
  char* stack; /* 私有栈：yield 时保存共享栈的内容 */
};

/**
 * 调度器结构体
 *
 * 调度器是协程的容器和管理者，负责：
 * 1. 维护共享栈空间
 * 2. 管理所有协程的创建、调度和销毁
 * 3. 记录当前运行的协程
 *
 * 注意：调度器不是线程安全的，所有操作必须在同一线程中进行。
 */
struct schedule {
  char stack[STACK_SIZE]; /* 共享栈！所有协程共用这 1MB 空间 */
  ucontext_t main;        /* 主上下文：resume/yield 的跳转目标 */
  int nco;                /* 当前活跃的协程数量 */
  int cap;                /* 协程指针数组的容量 */
  int running;            /* 当前运行的协程 ID，-1 表示无 */
  struct coroutine** co;  /* 协程指针数组 */
};

/* ============================================================================
 * 第四部分：内部辅助函数
 * ============================================================================
 */

/**
 * 创建一个新的协程结构体
 *
 * @param S    调度器指针
 * @param func 协程入口函数
 * @param ud   用户数据
 * @return     新创建的协程指针
 *
 * 此时协程只是分配了结构体，还未开始执行，状态为 READY。
 */
static struct coroutine* _co_new(struct schedule* S, coroutine_func func,
                                 void* ud) {
  struct coroutine* co = malloc(sizeof(*co));
  co->func = func;
  co->ud = ud;
  co->sch = S;
  co->cap = 0;
  co->size = 0;
  co->status = COROUTINE_READY;
  co->stack = NULL; /* 私有栈延迟分配，yield 时才需要 */
  return co;
}

/**
 * 删除协程结构体
 *
 * 释放协程的私有栈和结构体本身。
 * 当协程函数执行完毕时调用。
 */
static void _co_delete(struct coroutine* co) {
  free(co->stack);
  free(co);
}

/**
 * 保存协程的栈内容
 *
 * 这是共享栈设计的核心！当协程 yield 时，需要把当前使用的
 * 共享栈内容保存到协程的私有栈中。
 *
 * @param C   协程指针
 * @param top 共享栈的栈底地址（高地址）
 *
 * 技巧：用一个局部变量 dummy 来探测当前栈顶位置。
 * 因为栈从高地址向低地址增长，所以：
 *   栈使用量 = top - &dummy
 */
static void _save_stack(struct coroutine* C, char* top) {
  /* dummy 是局部变量，位于当前栈顶附近 */
  char dummy = 0;

  /* 确保不会溢出共享栈 */
  assert(top - &dummy <= STACK_SIZE);

  /* 计算当前协程使用的栈大小 */
  ptrdiff_t used_size = top - &dummy;

  /* 如果私有栈容量不够，重新分配 */
  if (C->cap < used_size) {
    free(C->stack);
    C->cap = used_size;
    C->stack = malloc(C->cap);
  }

  /* 记录实际使用的栈大小 */
  C->size = used_size;

  /* 将共享栈的内容复制到私有栈 */
  memcpy(C->stack, &dummy, C->size);
}

/**
 * 协程入口包装函数
 *
 * 当协程第一次被 resume 时，会跳转到这个函数。
 * 这个函数负责调用用户定义的协程函数，并在函数返回后清理资源。
 *
 * 参数传递技巧：由于 makecontext 只能传 int 参数，
 * 我们将指针拆成两个 32 位整数传入，再组合起来。
 */
static void mainfunc(uint32_t low32, uint32_t hi32) {
  /* 组合两个 32 位整数，恢复调度器指针 */
  uintptr_t ptr = (uintptr_t)low32 | ((uintptr_t)hi32 << 32);
  struct schedule* S = (struct schedule*)ptr;

  /* 获取当前运行的协程 */
  int id = S->running;
  struct coroutine* C = S->co[id];

  /* 执行用户定义的协程函数 */
  C->func(S, C->ud);

  /* 协程函数返回，协程结束，清理资源 */
  _co_delete(C);
  S->co[id] = NULL;
  --S->nco;
  S->running = -1;

  /* 函数返回后，会自动跳转到 uc_link 指向的上下文（即 S->main） */
}

/* ============================================================================
 * 第五部分：公开 API 实现
 * ============================================================================
 */

/**
 * 创建调度器
 *
 * @return 新创建的调度器指针
 *
 * 调度器创建后，可以往里面添加协程。
 * 共享栈（1MB）在调度器结构体内部。
 */
struct schedule* coroutine_open(void) {
  struct schedule* S = malloc(sizeof(*S));

  S->nco = 0;                 /* 初始没有协程 */
  S->cap = DEFAULT_COROUTINE; /* 初始容量 */
  S->running = -1;            /* 没有协程在运行 */

  /* 分配协程指针数组 */
  S->co = malloc(sizeof(struct coroutine*) * S->cap);
  memset(S->co, 0, sizeof(struct coroutine*) * S->cap);

  /* 注意：S->stack 是结构体成员，已经随 malloc 分配好了 1MB 空间 */

  return S;
}

/**
 * 关闭调度器
 *
 * 释放所有协程和调度器本身的内存。
 */
void coroutine_close(struct schedule* S) {
  int i;
  for (i = 0; i < S->cap; i++) {
    struct coroutine* co = S->co[i];
    if (co) {
      _co_delete(co);
    }
  }
  free(S->co);
  S->co = NULL;
  free(S);
}

/**
 * 创建新协程
 *
 * @param S    调度器指针
 * @param func 协程入口函数
 * @param ud   用户数据（传递给协程函数）
 * @return     协程 ID（非负整数）
 *
 * 协程创建后处于 READY 状态，需要调用 coroutine_resume 才会执行。
 */
int coroutine_new(struct schedule* S, coroutine_func func, void* ud) {
  struct coroutine* co = _co_new(S, func, ud);

  if (S->nco >= S->cap) {
    /* 容量不够，需要扩容 */
    int id = S->cap;
    S->co = realloc(S->co, S->cap * 2 * sizeof(struct coroutine*));
    memset(S->co + S->cap, 0, sizeof(struct coroutine*) * S->cap);
    S->co[S->cap] = co;
    S->cap *= 2;
    ++S->nco;
    return id;
  } else {
    /* 在数组中找一个空位存放协程 */
    int i;
    for (i = 0; i < S->cap; i++) {
      int id = (i + S->nco) % S->cap;
      if (S->co[id] == NULL) {
        S->co[id] = co;
        ++S->nco;
        return id;
      }
    }
  }

  /* 不应该到达这里 */
  assert(0);
  return -1;
}

/**
 * 恢复/启动协程
 *
 * @param S  调度器指针
 * @param id 协程 ID
 *
 * 这是最核心的函数！根据协程状态有两种处理方式：
 *
 * 1. READY 状态（首次 resume）：
 *    - 设置协程上下文，使用共享栈
 *    - 跳转到协程入口函数
 *
 * 2. SUSPEND 状态（后续 resume）：
 *    - 恢复私有栈内容到共享栈
 *    - 跳转到协程上次 yield 的位置
 */
void coroutine_resume(struct schedule* S, int id) {
  /* 确保当前没有其他协程在运行 */
  assert(S->running == -1);
  assert(id >= 0 && id < S->cap);

  struct coroutine* C = S->co[id];
  if (C == NULL) return;

  int status = C->status;

  switch (status) {
    case COROUTINE_READY:
      /* ========== 首次 resume：初始化协程上下文 ========== */

      /* 获取当前上下文作为模板 */
      getcontext(&C->ctx);

      /* 关键！设置协程使用共享栈 */
      C->ctx.uc_stack.ss_sp = S->stack;
      C->ctx.uc_stack.ss_size = STACK_SIZE;

      /* 设置协程结束后的返回位置：回到主流程 */
      C->ctx.uc_link = &S->main;

      /* 标记为运行态 */
      S->running = id;
      C->status = COROUTINE_RUNNING;

      /* 设置协程入口函数
       * 技巧：将调度器指针拆成两个 32 位整数传入
       * 这是因为 makecontext 的参数类型限制 */
      uintptr_t ptr = (uintptr_t)S;
      makecontext(&C->ctx, (void (*)(void))mainfunc, 2, (uint32_t)ptr,
                  (uint32_t)(ptr >> 32));

      /* 保存当前上下文到 S->main，跳转到 C->ctx
       * 协程开始执行！ */
      swapcontext(&S->main, &C->ctx);
      break;

    case COROUTINE_SUSPEND:
      /* ========== 恢复 yield 的协程 ========== */

      /* 关键！将保存的私有栈内容恢复到共享栈 */
      memcpy(S->stack + STACK_SIZE - C->size, C->stack, C->size);

      /* 标记为运行态 */
      S->running = id;
      C->status = COROUTINE_RUNNING;

      /* 保存当前上下文到 S->main，跳转到 C->ctx
       * 协程从 yield 点继续执行！ */
      swapcontext(&S->main, &C->ctx);
      break;

    default:
      /* 不应该出现其他状态 */
      assert(0);
  }
}

/**
 * 让出协程
 *
 * @param S 调度器指针
 *
 * 协程主动让出控制权，回到调用 resume 的位置。
 * 当前协程的栈内容会被保存到私有栈。
 */
void coroutine_yield(struct schedule* S) {
  int id = S->running;
  assert(id >= 0);

  struct coroutine* C = S->co[id];

  /* 确保协程的栈在共享栈范围内 */
  assert((char*)&C > S->stack);

  /* 关键！保存当前共享栈内容到私有栈 */
  _save_stack(C, S->stack + STACK_SIZE);

  /* 更新状态 */
  C->status = COROUTINE_SUSPEND;
  S->running = -1;

  /* 保存当前上下文到 C->ctx，跳转到 S->main
   * 控制权回到调用 resume 的位置！ */
  swapcontext(&C->ctx, &S->main);
}

/**
 * 查询协程状态
 *
 * @param S  调度器指针
 * @param id 协程 ID
 * @return   协程状态（COROUTINE_DEAD/READY/RUNNING/SUSPEND）
 */
int coroutine_status(struct schedule* S, int id) {
  assert(id >= 0 && id < S->cap);
  if (S->co[id] == NULL) {
    return COROUTINE_DEAD;
  }
  return S->co[id]->status;
}

/**
 * 获取当前运行的协程 ID
 *
 * @param S 调度器指针
 * @return  当前运行的协程 ID，-1 表示没有协程在运行
 *
 * 这个函数可以在协程内部调用来获取自己的 ID。
 */
int coroutine_running(struct schedule* S) { return S->running; }

/* ============================================================================
 * 第六部分：示例程序
 * ============================================================================
 *
 * 下面的示例展示了如何使用这个协程库：
 * 1. 创建调度器
 * 2. 创建两个协程
 * 3. 轮流恢复两个协程，直到它们都结束
 * 4. 关闭调度器
 */

/* 用户数据结构 */
struct args {
  int n;
};

/**
 * 示例协程函数
 *
 * 这个协程会打印 5 次消息，每次打印后 yield 让出控制权。
 */
static void foo(struct schedule* S, void* ud) {
  struct args* arg = ud;
  int start = arg->n;
  int i;

  for (i = 0; i < 5; i++) {
    /* 打印当前协程 ID 和计数值 */
    printf("coroutine %d : %d\n", coroutine_running(S), start + i);

    /* 让出控制权，等待下次 resume */
    coroutine_yield(S);
  }

  /* 函数返回后，协程自动结束（状态变为 DEAD） */
}

/**
 * 测试函数：演示协程的交替执行
 */
static void test(struct schedule* S) {
  struct args arg1 = {0};   /* 协程 1 的参数，从 0 开始计数 */
  struct args arg2 = {100}; /* 协程 2 的参数，从 100 开始计数 */

  /* 创建两个协程 */
  int co1 = coroutine_new(S, foo, &arg1);
  int co2 = coroutine_new(S, foo, &arg2);

  printf("main start\n");

  /* 轮流恢复两个协程，直到它们都结束
   * 应该分别检查每个协程的状态 */
  while (coroutine_status(S, co1) || coroutine_status(S, co2)) {
    if (coroutine_status(S, co1)) {
      coroutine_resume(S, co1); /* 恢复协程 1 */
    }
    if (coroutine_status(S, co2)) {
      coroutine_resume(S, co2); /* 恢复协程 2 */
    }
  }

  printf("main end\n");
}

/**
 * 主函数
 */
int main() {
  /* 创建调度器 */
  struct schedule* S = coroutine_open();

  /* 运行测试 */
  test(S);

  /* 关闭调度器 */
  coroutine_close(S);

  return 0;
}

/* ============================================================================
 * 预期输出：
 *
 * main start
 * coroutine 0 : 0
 * coroutine 1 : 100
 * coroutine 0 : 1
 * coroutine 1 : 101
 * coroutine 0 : 2
 * coroutine 1 : 102
 * coroutine 0 : 3
 * coroutine 1 : 103
 * coroutine 0 : 4
 * coroutine 1 : 104
 * main end
 *
 * 可以看到两个协程交替执行，每次 yield 后回到主流程，
 * 然后 resume 另一个协程。
 * ============================================================================
 */