stack.h(3)

🌸 NAME 🌸

okay bestie, you opened stack.h(3) and the top of the page says it's part of the Library Functions Manual 💖 so let's get into it. Here's the whole name in one breath:

stack.h — Контролируемый стек, aka the controlled stack. That's it. That's the name. Periodt 💅

---

🎀 SYNOPSIS 🎀

ngl, the SYNOPSIS section on this page is literally empty — no signature, no flags, no nothing. It just hands the mic straight to the detailed description and lets her cook. So there's nothing for me to copy here, no cap 🫶

---

🦋 Подробное описание 🦋

so what even is this ✨

Local variables of functions can be placed in a controlled stack — a region of memory, and the pointer to it gets passed in as an extra parameter of the function. Iconic.

The controlled stack gets created in a high-level function, passed down the chain into low-level functions, and then it gets cleared and destroyed when the high-level function finishes. It's giving born → passed down → obliterated 🌈

Low-level functions do not have to worry about data leaking out through the controlled stack — they can just park critical objects in that stack. Zero stress, maximum slay 🔥

Low-level functions can put critical objects not only in the controlled stack, but also in variables declared with the register keyword. When a low-level function finishes, those variables must be zeroed out. Not optional, bestie.

The values of critical variables can be determined through the values returned by functions (as a rule, values come back through a register). And critical variables must not be passed through the ordinary stack as function parameters. Don't do it 🙈

how to build your functions so it actually works 🧚

For library functions to work correctly across different hardware platforms, pointers to objects placed in the controlled stack must be aligned to the boundary of the fundamental block (see mem.h). To make that happen, build your functions like this:

1. [Предусловие функции] The stack pointer to the controlled stack must be aligned to the boundary of the fundamental block:

ASSERT(memIsAligned(stack, sizeof(mem_align_t)));

2. [Разметка стека в функции] Memory fragments for the stack objects get allocated with the functions memSlice() or memSlice2(). These functions guarantee that the fragments are aligned to the boundary of the fundamental block.
3. [Смещение границы стека] The last memory fragment when laying out stack can be a stack for subordinate functions. You can get a pointer to that fragment at the address &stack, which shifts the stack boundary. Cute, right? 🎀

the example 💖

Here's a controlled stack and a critical variable doing their thing together:

void f2(octet a[], size_t n, octet b[], size_t m, void* stack)
{
    register word sensitive;
    octet* var1; // [n]
    word* var2;  // [m]
    memSlice(stack,
        n, O_OF_W(m), SIZE_0, SIZE_MAX,
        &var1, &var2, &stack);
    ...
    sensitive = f1(var1, 2 * n, stack);
    ...
    sensitive = 0;
}

In this example the function memSlice2() lays out the controlled stack stack:

• it allocates the variables var1 and var2 in the stack;
• it shifts stack, turning it into a pointer to the stack of the subordinate function f1.

After the layout, stack stays aligned to the boundary of the fundamental block. No alignment drama, we love to see it ⭐

_deep functions, the depth girlies 🌊

The definition of a function f that uses a controlled stack must be accompanied by the definition of a function f_deep, which determines the maximum stack depth of f. The function f_deep takes an arbitrary number of arguments of type size_t (dimensions) or of other types, and it returns the stack depth in octets.

Example (continuation of the previous one):

size_t f2_deep(size_t n, size_t m)
{
    return memSliceSize(
        n, O_OF_W(m), f1_deep(n), SIZE_MAX);
}

The value of f_deep must not decrease when any of its arguments increases. Monotonic or bust 💀

In the description of a function f that uses the auxiliary stack, you must describe the parameters of f_deep (the scheme for calculating the stack depth). The recommended way to describe that scheme is:

f_deep(     // функция
    dim1,   // первая размерность
    dim2,   // вторая размерность
    ...
    dimX    // последняя размерность
);

For example: f1_deep(n), f2_deep2(n, m), f3_deep(). 💜

bundles, state, and _keep 👑

Local variables placed in the controlled stack can be used in not just one function but in several functions. Those functions form a so-called bundle (связка). The shared local variables of the bundle's functions form the state. The pointer to the state is passed in as an extra parameter of the bundle's functions.

The definition of a bundle g must be accompanied by a function g_keep, which returns the stack capture — the length of the state in octets. Functions of type _keep have the exact same interface as functions of type _deep. Sibling energy fr fr 🫶

The state of a bundle's function and its stack can be placed in a single memory buffer. Even so, it's recommended to keep the pointer to the state (state) separate from the pointer to the stack (stack). That way high-level functions can calculate the total volume of the controlled stack more precisely — the states of different bundles have to be kept unchanged, but the stack does not. Lowkey a big deal ✨

doxygen environments 🌸

For standardized formatting of descriptions, doxygen provides the environments \deep, \deep{stack}, \keep, and \keep{state}.

---

👑 Автор 👑

Автоматически создано Doxygen для Библиотека Bee2 из исходного текста — aka automatically generated by Doxygen for the Bee2 library straight from the source text. No human author claimed this page, it just manifested 💫

---

and that's the whole page, bestie!! this cutie came to you from Библиотека Bee2, and the timestamp on it is Вс 25 Янв 2026 00:00:00 — Sunday, January 25, 2026, midnight sharp, iykyk 🎀💖 stay aligned, keep your register variables zeroed, and never pass critical variables through the ordinary stack. mwah 💅🌈