kphp/runtime-light/coroutine/async-stack-structs.h at 4ca71fe45443175115aa70bab4962d60614dcd52 · VKCOM/kphp · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
// Compiler for PHP (aka KPHP)
// Copyright (c) 2025 LLC «V Kontakte»
// Distributed under the GPL v3 License, see LICENSE.notice.txt

#pragma once

/**
 * This header defines the data structures used to represent a coroutine asynchronous stack.
 *
 * Overview:
 * The asynchronous stack is used to manage the execution state of coroutines, allowing for
 * efficient context switching and stack management.
 *
 * Diagram: Normal and Asynchronous Stacks
 *
 *  Base Pointer (%rbp)              async_stack_root
 *         |                                 |
 *         V                                 V
 *    stack_frame                    async_stack_frame
 *         |                                 |
 *         V                                 V
 *    stack_frame                    async_stack_frame
 *        ...                               ...
 *         |                                 |
 *         V                                 V
 *    stack_frame                    async_stack_frame
 *         |                                 |
 *         V                                 V
 *
 * In the diagram above, the left side represents a typical call stack with stack frames linked by
 * the base pointer (%rbp). The right side illustrates an asynchronous stack where `async_stack_frame`
 * structures are linked by `async_stack_root`.
 *
 * Diagram: Backtrace Mechanism
 *
 *  Base Pointer (%rbp)
 *         |
 *         V
 *    stack_frame
 *         |
 *         V
 *    stack_frame (stop_sync_frame)  <- async_stack_root
 *                                             |
 *                                             V
 *                                     async_stack_frame (top_async_frame)
 *                                             |
 *                                             V
 *                                     async_stack_frame
 *                                            ...
 *                                             |
 *                                             V
 *                                     async_stack_frame
 *
 * The backtrace mechanism involves traversing the stack frames to capture the call stack.
 * The `stop_sync_frame` serves as a marker where the transition to the asynchronous stack occurs,
 * allowing the backtrace to continue through the `async_stack_frame` structures.
 */

#define STACK_RETURN_ADDRESS __builtin_return_address(0)

#define STACK_FRAME_ADDRESS __builtin_frame_address(0)

namespace kphp::coro {

struct stack_frame {
  stack_frame* caller_stack_frame{};
  void* return_address{};
};

struct async_stack_root;

struct async_stack_frame {
  async_stack_frame* caller_async_stack_frame{};
  async_stack_root* async_stack_root{};
  void* return_address{};
};

struct async_stack_root {
  async_stack_frame* top_async_stack_frame{};
  stack_frame* stop_sync_stack_frame{};
  async_stack_root* next_async_stack_root{};
};

/**
 * The async_stack_element class facilitates working with asynchronous traces in templated code.
 * This allows for uniform handling of any coroutines in places where async frames are pushed or popped.
 */
struct async_stack_element {
  async_stack_frame& get_async_stack_frame() noexcept {
    return m_async_stack_frame;
  }

private:
  async_stack_frame m_async_stack_frame;
};

/**
 * The async_stack_element class facilitates working with asynchronous traces in templated code.
 * This allows for uniform handling of any coroutines in places where async frames are pushed or popped.
 */

} // namespace kphp::coro