Module coroutine

---

title: Coroutine Design date: 2024-12-29 16:00:00 author: loongs-zhang

Coroutine Design

What is coroutine?

A coroutine is a function that can be paused and resumed, yielding values to the caller. A coroutine can suspend itself from any point in its call stack. In addition to receiving yielded values from a coroutine, you can also pass data into the coroutine each time it is resumed.

The above is excerpted from corosensei.

State in open-coroutine

           Ready
        ↗    ↓
Suspend ← Running ⇄ Syscall
           ↙   ↘
      Complete Error

In open-coroutine, a coroutine created is in Ready state, once you call the Coroutine::resume_with method, the state will change from Ready to Running. After that, the coroutine maybe suspend by Suspender::delay_with, then the state will change from Running to Suspend, the Suspend state also records the timestamp that can be awakened, and its unit is ns.

When the coroutine enters a syscall, the state will change from Running to Syscall, and after the syscall is completed, the state will change from Syscall to Running(Note: if you use open-coroutine-core, you will need to manually switch the coroutine state by calling Coroutine::syscall and Coroutine::running at the appropriate time, which is a huge workload and prone to errors, so please use open-coroutine and enable hook). BTW, the Syscall state records the syscall name and a helpful state which used in open-coroutine inner.

When the coroutine is successfully completed, the state will change from Running to Complete. If an error occurs during the coroutine execution, and the coroutine does not handle the error, the state will change from Running to Error, the error message will be recorded at the same time.

Listener

To enhance extension, we provide the Listener API, which notifies Listener whenever Coroutine state changes.

CoroutineLocal

The original design intention of ThreadLocal is to solve thread safety issues in multi-thread environments. In multi-thread programs, multiple threads may simultaneously access and modify the same shared variable, which can lead to thread safety issues such as data inconsistency and race conditions. To solve these issues, the traditional approach is to synchronize access to shared resources through locking, but this can lead to performance degradation, especially in high concurrency scenarios. ThreadLocal provides a new solution by providing independent copies of variables for each thread, thereby avoiding shared variable conflicts between multiple threads, ensuring thread safety, and improving program concurrency performance.

In the coroutine environment, although the scheduled thread is single, due to the existence of the work steel mechanism, coroutines may flow between multiple threads which makes ThreadLocal invalid. To solve this problem, we have to introduce CoroutineLocal. It’s similar to ThreadLocal’s approach of providing replicas, but CoroutineLocal has upgraded the replicas to the coroutine level, which means each coroutine has its own local variables. These local variables will be dropped together when the coroutine is dropped.

Modules

• listener
  Coroutine listener abstraction and impl.
• local
  Coroutine local abstraction.
• suspender
  Coroutine suspender abstraction and impl.

Structs

• Coroutine
  Use corosensei as the low-level coroutine.
• StackInfo
  The coroutine stack information.