Module related to stack. See the Stack object.

Stack

The Stack object represents a call stack in the trace. It exposes a list of stack frames that can be used to rebuild a backtrace from its associated Context.

The Stack object offers a view associated to a context that lists all stack frames from the current top of the stack to the first known frame in that stack. The call stack evolves over time, so from a context to another inside the same stack, call frames may be added or removed.

Active stack, previous/next stacks

There are several call stacks depending on the process, on whether we are in kernel land or user land. For a given context, the active stack is defined as the stack that is accessible from the stack pointer (e.g. rsp in x64 architecture).

During the trace, the stack pointer may change to move inside the same stack or move to a different stack (for instance when changing process or switching from ring 3 to ring 0):

              Stack change   Stack change
                   +              +
                   |              |
 +----+---------------+---------------+------------->  Trace
      |            |  |           |   |
      |            +  |           +   |
      |rsp            |rsp            |
      |               |               |
      |               |               |
      |               |               |
      |    Stack 1    |  Stack 2      |
      |    +-----+    |  +-----+      |
      |    |     |    |  |     |      |
      +---->     |    +-->     |      |
           |     |       |     |      |
           +--^--+       +-----+      |
              |                       |
              +-----------------------+

From a given stack, the previous stack refers to the stack that was accessible just before the active stack in the trace, that is the stack that was accessible just before the last value change of the stack pointer to move to a different stack. Similarly, the next stack refers to the stack that will be accessible just after the active stack in the trace:

                    Current context
                           +
              Stack change | Stack change
                   +       |      +
                   |       |      |
 +--+---------------------------------+------------->  Trace
    |              |       |      |   |
    |              +  +----+      +   |
    |rsp              |rsp            |rsp
    |                 |               |
    |                 |               |
    |                 |               |
    |  Stack 1        |  Stack 2      |  Stack 3
    |  +------+       |  +------+     |  +------+
    |  |      |       |  |      |     |  |      |
    +--> Prev |       +-->Active|     +--> Next |
       |      |          |      |        |      |
       +------+          +------+        +------+