DEV Community: Ilean Monterrubio Jr

Common Embedded Patterns: Finite State Machine

Ilean Monterrubio Jr — Fri, 09 Oct 2026 00:00:00 +0000

This is the third part of the series re-exploring common embedded patterns. This one focuses on the finite state machine. The complete, tested source lives in the companion repo: ileanmjr88/tetzontli. Each pattern in this series is its own module with a full GoogleTest suite, so you can clone it and run the tests yourself. The suite also wires up the full motor controller used throughout this post, so it doubles as the usage example. Basic Concept A finite state machine is one of the most common ways we design behavior into a system, and in embedded it is especially important. Behavior is what turns hardware into a product: the system has to know what it is doing right now, and what to do when something happens. Think of it like following a recipe for bread. You gather the ingredients, mix the dry ones, mix the wet ones, then combine the two. Each step is a state. You are in exactly one at a time, and you only move on when that step is done. The recipe also has notes like "if the dough is too watery, add flour; if it is too firm, add water." Those notes are the interesting part. Something happens (you check the dough), a condition decides which note applies (too watery or too firm), and you take an action (add flour or water) before carrying on. That is all a state machine is: states, the events that arrive while you are in them, the conditions (guards) that decide which rule applies, and the actions you take. Modeling behavior this way is what lets a system adapt. We would all like perfect, ideal conditions, but the real world is chaotic, and the system has to handle it anyway. Almost every embedded system is a state machine: a button debouncer, a modem driver, a battery charger, a bootloader. Most start life as switch(state) with a nested switch(event) in each case. That works for three states and four events. By ten states it is a wall of cases where the behavior is scattered across hundreds of lines, entry and exit logic is copy-pasted, and nobody can answer "what happens if OVERTEMP arrives while we are CHARGING?" without reading all of it. The Idea The recipe showed that we all already use state machines. Before looking at an example state machine, let's pin down the vocabulary, since every representation that follows uses the same five ideas. State: what the system is doing right now. In the recipe, each step is a state. The system is always in exactly one. Event: something that happens and needs a response, like an input, a timer firing, or a sensor reading. In the recipe, checking the dough. Guard: a condition that decides whether a rule applies. In the recipe: is the dough too watery? Action: what the system does in response. In the recipe: add flour. Transition: moving from one state to another because of an event (and its guard). In the recipe: the dough is ready, so you move on to the next step. Here's the motor controller from the GoogleTest suite, written the switch way. It has four states (IDLE, ARMED, RUNNING, FAULT) and events like EV_ARM, EV_START, and EV_ESTOP. if (event == EV_ESTOP) { /* any state / motor_off(); state = FAULT; return; } switch (state) { case IDLE: if (event == EV_ARM) { state = ARMED; } break; case ARMED: switch (event) { case EV_DISARM: state = IDLE; break; case EV_START: if (battery_ok()) { state = RUNNING; } else { warn_battery_low(); / stay ARMED / } break; default: break; } break; case RUNNING: switch (event) { case EV_STOP: state = ARMED; break; case EV_SET_SPEED: set_speed(); / stay RUNNING / break; case EV_OVERCURRENT: motor_off(); state = FAULT; break; default: break; } break; case FAULT: if (event == EV_RESET && fault_cleared()) { state = IDLE; } break; } It works, but look at what's already happening with just four states. The emergency stop had to live outside the switch, because a rule that applies to every state has no natural home. To answer "what does EV_START do when the battery is low?" you have to trace nested branches. And every case needs its break: my first draft of this example was missing several, and it silently fell through from IDLE into ARMED. Add ten states and twenty events, and this becomes hundreds of lines where nobody can see the whole behavior at once. Table-Driven State Machine Here's the same behavior as a table: static const sm_transition_t kMotorTable[] = { // from event guard action to {SM_ANY_STATE, EV_ESTOP, NULL, motor_off, FAULT}, {IDLE, EV_ARM, NULL, NULL, ARMED}, {ARMED, EV_DISARM, NULL, NULL, IDLE}, {ARMED, EV_START, battery_ok, NULL, RUNNING}, {ARMED, EV_START, NULL, warn_battery_low, ARMED}, {RUNNING, EV_STOP, NULL, NULL, ARMED}, {RUNNING, EV_SET_SPEED, NULL, set_speed, RUNNING}, {RUNNING, EV_OVERCURRENT, NULL, motor_off, FAULT}, {FAULT, EV_RESET, fault_cleared, NULL, IDLE}, }; Each row defines a single rule. The from state and the event together act as the key: when an event arrives, the state machine looks for a row that matches its current state and that event. The guard is an optional condition that has to be true for the rule to apply. If it is, the machine runs the action (if there is one) and moves to the to state. Rules are checked from top to bottom, and the first matching rule wins. That one convention does a lot of work: The SM_ANY_STATE row for EV_ESTOP sits at the top, so an emergency stop wins from any state. It finally has a natural home. The two ARMED, EV_START rows depend on order: the rule guarded by battery_ok is checked first, and the unguarded rule underneath is the fallback that warns about the battery. Swap them, and the warning always fires. If no rule fires, like EV_RESET while the fault hasn't cleared (the row matches, but its guard says no), nothing happens and the machine stays where it is. The whole behavior now fits on one screen, and it reads like a specification. Answering "what does EV_START do when the battery is low?" means reading two rows instead of tracing nested branches. Implementation Having compared a switch-based state machine with a table-driven one, the natural question is: what actually triggers the guards and actions? The short answer is sm_dispatch, but first we need the pieces it works with. The behavior lives in two caller-owned tables: the transition table (sm_transition_t), which defines how the machine responds to events, and an optional hooks table (sm_state_hooks_t), which defines what each state does when it's entered, while it's active, and when it's left. Table Structs The transition table. Each row reads as one sentence: in from, on event, if guard passes, run action and go to to. // modules/state_machine/state_machine.h typedef struct { sm_state_t from; /< State, or SM_ANY_STATE. */ sm_event_t event; /< Triggering event. */ sm_guard_fn guard; /< NULL = always passes. */ sm_action_fn action; /< NULL = no action. */ sm_state_t to; /< Next state. */ } sm_transition_t; The hooks table (optional). One entry per state, each with on_entry, on_exit, and on_run. Entry and exit logic live in one place per state, instead of being repeated on every transition that touches it. // modules/state_machine/state_machine.h typedef struct { sm_action_fn on_entry; /< NULL = none. */ sm_action_fn on_exit; /< NULL = none. */ sm_run_fn on_run; /< NULL = none. */ } sm_state_hooks_t; For the motor, the hooks table looks like this: static const sm_state_hooks_t kMotorHooks[STATE_COUNT] = { // on_entry on_exit on_run {idle_entry, NULL, NULL}, // IDLE {NULL, NULL, NULL}, // ARMED {running_entry, running_exit, running_run}, // RUNNING {fault_entry, NULL, NULL}, // FAULT }; One entry per state, in enum order. IDLE and FAULT engage the brake when entered, ARMED needs nothing, and RUNNING turns the PWM output on in running_entry, off in running_exit, and polls the motor current in running_run. State Machine Struct The caller owns everything: the tables, the struct, the context. The library never allocates, which matters on systems where malloc isn't welcome (see the memory pool post). // modules/state_machine/state_machine.h typedef struct { const sm_transition_t *table; size_t count; const sm_state_hooks_t *hooks; sm_state_t state_count; sm_state_t current; bool started; void *ctx; } sm_t; Types Looking over the structs we used to define the tables, you may be wondering about some of the data types that aren't familiar. They're custom types defined by the library. // modules/state_machine/state_machine.h typedef uint8_t sm_state_t; /< 0 .. state_count - 1; 0xFF reserved. */ typedef uint8_t sm_event_t; /< Caller-defined; 0xFF reserved. */ #define SM_ANY_STATE ((sm_state_t)0xFFu) /< from wildcard: any state. */ #define SM_NO_EVENT ((sm_event_t)0xFFu) /< on_run: nothing to dispatch. */ typedef bool (*sm_guard_fn)(void *ctx); /< true = allow the row. */ typedef void (*sm_action_fn)(void *ctx); /< Action, entry or exit. */ typedef sm_event_t (*sm_run_fn)(void *ctx); /< Event or SM_NO_EVENT. */ sm_state_t and sm_event_t are uint8_t. The library can't know your states and events, so you define your own enum and the library just stores the numbers. Eight bits keep each table row small, at the cost of a limit: 255 states and events, with 0xFF reserved as a sentinel (SM_ANY_STATE for states, SM_NO_EVENT for events). For a firmware state machine, that's plenty. sm_guard_fn returns bool: should this row apply? It answers a question and changes nothing. sm_action_fn does the work. The same type serves transition actions and the on_entry and on_exit hooks, since they all have the same shape: do something, return nothing. sm_run_fn is the interesting one: it returns an event. A state's on_run can watch the world (poll a sensor, check a timeout) and report what happened, or return SM_NO_EVENT if nothing did. That's how a state generates its own events without the caller having to. Every callback takes void *ctx. The machine passes your context pointer through, so callbacks never need globals. That means you can run several independent machines, and in tests you can hand in a fake context and check exactly what happened. The functions that drive the machine return an sm_result_t, so the caller always knows what happened to an event: // modules/state_machine/state_machine.h typedef enum { SM_HANDLED, /< A row fired, or sm_run() had nothing to do. */ SM_UNHANDLED, /< No row matches. */ SM_GUARD_REJECTED, /< Rows matched; every guard rejected. */ SM_ERROR /*< NULL, not started, or state out of range. */ } sm_result_t; SM_HANDLED: a rule matched and fired, or sm_run() had nothing to do. SM_UNHANDLED: no rule exists for this state and event. The event was ignored. SM_GUARD_REJECTED: rules existed for this state and event, but every guard said no. The event was understood but blocked. SM_ERROR: misuse, not behavior. It covers a NULL argument, a machine that hasn't been started, or a state out of range. Init Function Like the ring buffer and memory pool, the state machine needs an init function. The caller owns the sm_t and the tables; sm_init validates them and wires them together. // modules/state_machine/state_machine.c bool sm_init(sm_t *sm, const sm_transition_t *table, size_t count, const sm_state_hooks_t *hooks, sm_state_t state_count, sm_state_t initial, void *ctx) { if (sm == NULL) { return false; } *sm = (sm_t){0}; if (table == NULL || count == 0u || state_count == 0u || initial >= state_count) { return false; } for (size_t i = 0u; i < count; i++) { if (table[i].from != SM_ANY_STATE && table[i].from >= state_count) { return false; } if (table[i].to >= state_count || table[i].event == SM_NO_EVENT) { return false; } } sm->table = table; sm->count = count; sm->hooks = hooks; sm->state_count = state_count; sm->ctx = ctx; sm->current = initial; return true; } NULL check on sm first. Without somewhere to write, there's nothing else to do. *sm = (sm_t){0}; happens before the rest of the validation, on purpose. If any later check fails, the caller is left with a zeroed machine: started is false and table is NULL. sm_start refuses it, and sm_dispatch and sm_run return SM_ERROR instead of acting on garbage. A failed init leaves the machine in a known safe state. Basic argument checks: the table must exist, count and state_count can't be zero, and initial must be a valid state. Every row is validated once, up front: from must be a real state or SM_ANY_STATE. to must be a real state. Since SM_ANY_STATE is 0xFF, which is always >= state_count, "any state" is automatically rejected as a destination. You can't transition to any state, and the check falls out for free. event can't be SM_NO_EVENT, since that value is reserved to mean "nothing happened." Then the fields are stored. Note what's not set: started stays false. Helper Functions Before we start the machine, let's look at two small helpers that keep the hooks optional at every level: // modules/state_machine/state_machine.c static void run_entry(const sm_t *sm, sm_state_t state) { if (sm->hooks != NULL && sm->hooks[state].on_entry != NULL) { sm->hooks[state].on_entry(sm->ctx); } } static void run_exit(const sm_t *sm, sm_state_t state) { if (sm->hooks != NULL && sm->hooks[state].on_exit != NULL) { sm->hooks[state].on_exit(sm->ctx); } } static: they're private to state_machine.c. Callers never invoke hooks directly; the machine decides when they run. Two NULL checks, two levels of "optional": the whole hooks table can be NULL (a machine with no hooks at all), and any single hook in it can be NULL (a state that only needs on_entry, say). Either way, nothing runs. Indexed by state, with no bounds check here. The helpers trust state, because every state that reaches them has already been validated: the initial state in sm_init, and each to state when its row was checked. Validate once at the edges, and the inner code stays simple. The caller's ctx is passed through, so hooks work on the caller's data, never globals. Start Function sm_init wires the machine together, but it doesn't run anything. Starting is a separate step: sm_start enters the initial state, running its on_entry hook, and marks the machine as live. // modules/state_machine/state_machine.c bool sm_start(sm_t *sm) { if (sm == NULL || sm->table == NULL || sm->started) { return false; } run_entry(sm, sm->current); sm->started = true; return true; } sm->table == NULL catches a failed init. Because sm_init zeroes the struct before validating, a machine that failed to initialize has a NULL table, so sm_start refuses it. That's the payoff of zeroing first. sm->started guards against starting twice. A second call would run the current state's on_entry again: re-enabling hardware or resetting a timer that's already running. Returning false makes the mistake visible instead of silently repeating side effects. run_entry(sm, sm->current) runs the initial state's on_entry hook, if there's a hooks table and that state has one, passing along the caller's ctx. Then started is set and the function returns true. Dispatch Function sm_dispatch does the heavy lifting: given an event, it finds the first rule that applies to the current state and carries it out. // modules/state_machine/state_machine.c sm_result_t sm_dispatch(sm_t *sm, sm_event_t event) { if (sm == NULL || !sm->started || sm->current >= sm->state_count) { return SM_ERROR; } bool matched = false; for (size_t i = 0u; i < sm->count; i++) { const sm_transition_t *row = &sm->table[i]; if ((row->from != sm->current && row->from != SM_ANY_STATE) || row->event != event) { continue; } matched = true; if (row->guard != NULL && !row->guard(sm->ctx)) { continue; } if (row->to != sm->current) { run_exit(sm, sm->current); } if (row->action != NULL) { row->action(sm->ctx); } if (row->to != sm->current) { sm->current = row->to; run_entry(sm, sm->current); } return SM_HANDLED; } return matched ? SM_GUARD_REJECTED : SM_UNHANDLED; } Defensive checks: a NULL machine, a machine that was never started (including one whose init failed), or a current state outside the valid range all return SM_ERROR. sm_init already validated the table, but this check is cheap insurance against a corrupted struct. A linear scan, top to bottom. A row matches when its from is the current state (or SM_ANY_STATE) and its event matches. Everything else is skipped. matched = true is set before the guard is checked. That one flag is what separates SM_UNHANDLED (no rule exists) from SM_GUARD_REJECTED (rules existed, but every guard said no). A failed guard means continue, not return. The scan keeps looking, which is exactly how the fallback works: in ARMED, the battery_ok row fails, so the next EV_START row (the battery warning) gets its chance. The order of a transition is exit, then action, then entry. The old state cleans up, the transition does its work, and then the new state sets itself up. First match wins: the function returns SM_HANDLED immediately, so later rows never run. Self-transitions don't re-run the hooks. When to equals the current state (like RUNNING on EV_SET_SPEED), only the action runs. Exit and entry are skipped. Changing speed shouldn't stop and restart the motor, which is exactly what running running_exit and then running_entry would do to the PWM output. Some frameworks re-run the hooks on self-transitions; I chose not to, because in embedded code entry and exit usually touch hardware. Guards, actions, and hooks must not call sm_dispatch or sm_run. During the action, the old state has already exited, but current hasn't been updated yet. A nested dispatch would see a state that's halfway through a transition. A nested call from a guard is no better: the outer scan is still partway down the table, and it would carry on comparing rows against a current that may have changed underneath it. If an action needs to trigger another event, queue it, and dispatch after the first one returns. (The ring buffer from part one is a natural event queue.) Run Function sm_run is what gets called from the main loop. Where sm_dispatch reacts to events someone else delivers, sm_run gives the current state a chance to look at the world and report its own. // modules/state_machine/state_machine.c sm_result_t sm_run(sm_t *sm) { if (sm == NULL || !sm->started || sm->current >= sm->state_count) { return SM_ERROR; } if (sm->hooks == NULL || sm->hooks[sm->current].on_run == NULL) { return SM_HANDLED; } sm_event_t ev = sm->hooks[sm->current].on_run(sm->ctx); if (ev == SM_NO_EVENT) { return SM_HANDLED; } return sm_dispatch(sm, ev); } Same defensive checks as sm_dispatch. Misuse returns SM_ERROR before any user code runs. No on_run, nothing to do. If there's no hooks table, or the current state has no on_run, it returns SM_HANDLED. That makes it safe to call sm_run on every pass of the loop, even when the current state only reacts to events from outside. The current state's on_run gets the caller's ctx and returns an event. This is where polling lives: reading a sensor, comparing a timer against a timeout, or checking a flag an ISR set. SM_NO_EVENT means nothing happened, which is the common case, so it returns SM_HANDLED. This is also why sm_init rejects any row with SM_NO_EVENT as its event: that value can never be dispatched. Anything else goes straight to sm_dispatch, and its result is returned as is. An event reported by on_run goes through the same table as one from the caller, so every transition takes the same path. This is why on_run returns an event instead of calling sm_dispatch itself. Returning lets the hook finish before the transition starts, so the machine never dispatches from inside one of its own hooks. It's the same rule as for actions: hooks report what happened, and the machine decides what to do about it. In the simplest case, where every event comes from a state's on_run, the main loop is a single call: for (;;) { sm_run(&motor_sm); } Most machines aren't that simple. In the motor example, EV_ARM, EV_START, and EV_ESTOP come from outside, so they still go through sm_dispatch. Current State Function The last function is the simplest: sm_state returns the state the machine is currently in. // modules/state_machine/state_machine.c sm_state_t sm_state(const sm_t *sm) { return (sm == NULL) ? SM_ANY_STATE : sm->current; } Read-only. It takes a const sm_t *, so asking can't change anything. The fields of sm_t are readable, but going through sm_state keeps callers from reaching into the struct. NULL returns SM_ANY_STATE. Since 0xFF can never be a real state, it doubles as "no answer." There's no need for a bool return and an out parameter the way ring_buffer_get does it. It doesn't check started. Before sm_start, it returns the initial state from sm_init. After a failed init it returns 0, from the zeroed struct, which looks like a real state. Check the return value of sm_init instead of relying on sm_state to tell you something went wrong. It's mostly for tests and logging. A typical test dispatches an event and then checks sm_state to confirm where the machine landed. Wrap-Up That's a complete state machine. The behavior lives in a table instead of a wall of switch cases, so the whole machine fits on one screen and reads like a specification. It does no dynamic allocation, validates its transition table once at init, and sends every event down the same path, whether it came from the caller or from a state's own on_run. The trades, all deliberate: Not ISR-safe or thread-safe. sm_dispatch reads and writes current with no protection. Events from an ISR go into a queue and get dispatched from one context. No re-entrant calls. Guards, actions, and hooks must not call sm_dispatch or sm_run on the same machine. on_run returns its event instead, and anything else gets queued. Guards must be side-effect free. A guard can run for a row that never fires, so it answers a question and changes nothing. Row order is behavior. The first match wins, so SM_ANY_STATE safety rows go first and guarded rows go above their fallbacks. Reordering the table changes what the machine does. Self-transitions skip entry and exit. Only the action runs, so changing speed doesn't stop and restart the motor. Linear scan. Each dispatch walks the table top to bottom, which is fine for dozens of rows. Flat machine. There are no hierarchical states, so behavior shared across states goes in SM_ANY_STATE rows. 255 states and 255 events. uint8_t keeps each row small, and 0xFF is reserved for SM_ANY_STATE and SM_NO_EVENT. The hooks table size isn't checked. sm_init only gets a pointer, so it can't tell whether hooks has state_count entries, and a short table means jumping through a garbage function pointer. Declare it as hooks[STATE_COUNT], with STATE_COUNT as the last value of your state enum. The compiler flags extra entries (build with -Werror to make that a hard error), and missing ones are zero-filled to NULL, which means no hook. sm_t fields are read-only. They're readable for debugging, but writing them skips the validation sm_init did. Ask sm_state where the machine is. Three patterns in, and this is the one where the data starts to mean something. Most embedded applications break down into a state machine once you list what the system can be doing and what can happen to it, and writing that list as a table forces you to answer every "what if" up front. The ring buffer and the pool gave us storage that didn't care what it held. The state machine decides what happens next, and since sm_event_t is a single byte, the ring buffer from part one can carry its events as they are. Next in the series is the command dispatcher. It reads its input straight out of a ring buffer and maps each command to the function that handles it, the same table-driven idea applied to text instead of events. See you there.

Patrones embebidos comunes: máquina de estados finitos

Ilean Monterrubio Jr — Fri, 09 Oct 2026 00:00:00 +0000

Esta es la tercera parte de la serie donde vuelvo a explorar los patrones embebidos más comunes. Esta vez le toca a la máquina de estados finitos (finite state machine). El código fuente completo y probado vive en el repositorio complementario: ileanmjr88/tetzontli. Cada patrón de esta serie es su propio módulo con una suite completa de GoogleTest, así que se puede clonar el repositorio y ejecutar las pruebas uno mismo. La suite también arma el controlador de motor completo que se usa a lo largo de este post, así que sirve además como ejemplo de uso. Concepto básico Una máquina de estados finitos es una de las formas más comunes de diseñar el comportamiento de un sistema, y en sistemas embebidos es especialmente importante. El comportamiento es lo que convierte el hardware en un producto: el sistema tiene que saber qué está haciendo en este momento, y qué hacer cuando algo pasa. Es como seguir una receta de pan. Se juntan los ingredientes, se mezclan los secos, se mezclan los húmedos, y luego se combinan ambos. Cada paso es un estado. Se está en un solo paso a la vez, y solo pasa al siguiente cuando ese paso termina. La receta también tiene notas como «si la masa está muy aguada, agregar harina; si está muy firme, agregar agua». Esas notas son la parte interesante. Algo pasa (se revisa la masa), una condición decide qué nota aplica (muy aguada o muy firme), y se toma una acción (agregar harina o agua) antes de continuar. Eso es todo lo que es una máquina de estados: estados, los eventos que llegan mientras se está en ellos, las condiciones (guardas) que deciden qué regla aplica y las acciones que se toman. Modelar el comportamiento así es lo que permite que un sistema se adapte. A todos nos gustarían condiciones perfectas e ideales, pero el mundo real es caótico, y el sistema tiene que manejarlo de todos modos. Casi todo sistema embebido es una máquina de estados: un antirrebote de botón, un driver de módem, un cargador de batería, un bootloader. La mayoría empiezan como un switch(state) con un switch(event) anidado en cada caso. Eso funciona para tres estados y cuatro eventos. Con diez estados es un muro de casos donde el comportamiento está disperso en cientos de líneas, la lógica de entrada y salida está copiada y pegada, y nadie puede responder «¿qué pasa si llega OVERTEMP mientras estamos en CHARGING?» sin leerlo todo. La idea La receta mostró que todos ya usamos máquinas de estados. Antes de ver una máquina de estados de ejemplo, fijemos el vocabulario, ya que cada representación que sigue usa las mismas cinco ideas. Estado: lo que el sistema está haciendo en este momento. En la receta, cada paso es un estado. El sistema siempre está exactamente en uno. Evento: algo que pasa y necesita una respuesta, como una entrada, un temporizador que se dispara o una lectura de un sensor. En la receta, revisar la masa. Guarda (guard): una condición que decide si una regla aplica. En la receta: ¿la masa está muy aguada? Acción: lo que el sistema hace en respuesta. En la receta: agregar harina. Transición: pasar de un estado a otro por un evento (y su guarda). En la receta: la masa está lista, así que se pasa al siguiente paso. Aquí está el controlador de motor de la suite de GoogleTest, escrito a la manera del switch. Tiene cuatro estados (IDLE, ARMED, RUNNING, FAULT) y eventos como EV_ARM, EV_START y EV_ESTOP. if (event == EV_ESTOP) { /* any state / motor_off(); state = FAULT; return; } switch (state) { case IDLE: if (event == EV_ARM) { state = ARMED; } break; case ARMED: switch (event) { case EV_DISARM: state = IDLE; break; case EV_START: if (battery_ok()) { state = RUNNING; } else { warn_battery_low(); / stay ARMED / } break; default: break; } break; case RUNNING: switch (event) { case EV_STOP: state = ARMED; break; case EV_SET_SPEED: set_speed(); / stay RUNNING / break; case EV_OVERCURRENT: motor_off(); state = FAULT; break; default: break; } break; case FAULT: if (event == EV_RESET && fault_cleared()) { state = IDLE; } break; } Funciona, pero veamos lo que ya está pasando con solo cuatro estados. El paro de emergencia tuvo que vivir fuera del switch, porque una regla que aplica a todos los estados no tiene un lugar natural. Para responder «¿qué hace EV_START cuando la batería está baja?» hay que rastrear ramas anidadas. Y cada caso necesita su break: a mi primer borrador de este ejemplo le faltaban varios, y en silencio se pasaba de IDLE a ARMED. Con diez estados y veinte eventos, esto se vuelve cientos de líneas donde nadie puede ver todo el comportamiento a la vez. Máquina de estados basada en tablas Aquí está el mismo comportamiento como tabla: static const sm_transition_t kMotorTable[] = { // from event guard action to {SM_ANY_STATE, EV_ESTOP, NULL, motor_off, FAULT}, {IDLE, EV_ARM, NULL, NULL, ARMED}, {ARMED, EV_DISARM, NULL, NULL, IDLE}, {ARMED, EV_START, battery_ok, NULL, RUNNING}, {ARMED, EV_START, NULL, warn_battery_low, ARMED}, {RUNNING, EV_STOP, NULL, NULL, ARMED}, {RUNNING, EV_SET_SPEED, NULL, set_speed, RUNNING}, {RUNNING, EV_OVERCURRENT, NULL, motor_off, FAULT}, {FAULT, EV_RESET, fault_cleared, NULL, IDLE}, }; Cada fila define una sola regla. El estado from y el event juntos actúan como la clave: cuando llega un evento, la máquina de estados busca una fila que coincida con su estado actual y con ese evento. La guard es una condición opcional que tiene que ser verdadera para que la regla aplique. Si lo es, la máquina ejecuta la action (si hay una) y pasa al estado to. Las reglas se revisan de arriba hacia abajo, y gana la primera regla que coincide. Esa sola convención hace mucho trabajo: La fila SM_ANY_STATE para EV_ESTOP está hasta arriba, así que un paro de emergencia gana desde cualquier estado. Por fin tiene un lugar natural. Las dos filas ARMED, EV_START dependen del orden: la regla con la guarda battery_ok se revisa primero, y la regla sin guarda que está debajo es el respaldo que avisa sobre la batería. Si se intercambian, la advertencia se dispara siempre. Si ninguna regla se dispara, como EV_RESET mientras la falla siga activa (la fila coincide, pero su guarda dice que no), no pasa nada y la máquina se queda donde está. Todo el comportamiento ahora cabe en una pantalla, y se lee como una especificación. Responder «¿qué hace EV_START cuando la batería está baja?» significa leer dos filas en lugar de rastrear ramas anidadas. Implementación Después de comparar una máquina de estados basada en switch con una basada en tablas, la pregunta natural es: ¿qué es lo que realmente dispara las guardas y las acciones? La respuesta corta es sm_dispatch, pero primero necesitamos las piezas con las que trabaja. El comportamiento vive en dos tablas que son propiedad de quien llama: la tabla de transiciones (sm_transition_t), que define cómo responde la máquina a los eventos, y una tabla de hooks opcional (sm_state_hooks_t), que define qué hace cada estado al entrar, mientras está activo y al salir. Structs de las tablas La tabla de transiciones. Cada fila se lee como una oración: en from, ante event, si guard pasa, ejecutar action e ir a to. // modules/state_machine/state_machine.h typedef struct { sm_state_t from; /< State, or SM_ANY_STATE. */ sm_event_t event; /< Triggering event. */ sm_guard_fn guard; /< NULL = always passes. */ sm_action_fn action; /< NULL = no action. */ sm_state_t to; /< Next state. */ } sm_transition_t; La tabla de hooks (opcional). Una entrada por estado, cada una con on_entry, on_exit y on_run. La lógica de entrada y salida vive en un solo lugar por estado, en lugar de repetirse en cada transición que lo toca. // modules/state_machine/state_machine.h typedef struct { sm_action_fn on_entry; /< NULL = none. */ sm_action_fn on_exit; /< NULL = none. */ sm_run_fn on_run; /< NULL = none. */ } sm_state_hooks_t; Para el motor, la tabla de hooks se ve así: static const sm_state_hooks_t kMotorHooks[STATE_COUNT] = { // on_entry on_exit on_run {idle_entry, NULL, NULL}, // IDLE {NULL, NULL, NULL}, // ARMED {running_entry, running_exit, running_run}, // RUNNING {fault_entry, NULL, NULL}, // FAULT }; Una entrada por estado, en el orden del enum. IDLE y FAULT activan el freno al entrar, ARMED no necesita nada, y RUNNING enciende la salida PWM en running_entry, la apaga en running_exit y sondea la corriente del motor en running_run. Struct de la máquina de estados Quien llama es dueño de todo: las tablas, el struct, el contexto. La biblioteca nunca reserva memoria, lo cual importa en sistemas donde malloc no es bienvenido (ver el post del pool de memoria). // modules/state_machine/state_machine.h typedef struct { const sm_transition_t *table; size_t count; const sm_state_hooks_t *hooks; sm_state_t state_count; sm_state_t current; bool started; void *ctx; } sm_t; Tipos Al revisar los structs que usamos para definir las tablas, puede que surjan dudas sobre algunos tipos de datos que no resultan familiares. Son tipos personalizados definidos por la biblioteca. // modules/state_machine/state_machine.h typedef uint8_t sm_state_t; /< 0 .. state_count - 1; 0xFF reserved. */ typedef uint8_t sm_event_t; /< Caller-defined; 0xFF reserved. */ #define SM_ANY_STATE ((sm_state_t)0xFFu) /< from wildcard: any state. */ #define SM_NO_EVENT ((sm_event_t)0xFFu) /< on_run: nothing to dispatch. */ typedef bool (*sm_guard_fn)(void *ctx); /< true = allow the row. */ typedef void (*sm_action_fn)(void *ctx); /< Action, entry or exit. */ typedef sm_event_t (*sm_run_fn)(void *ctx); /< Event or SM_NO_EVENT. */ sm_state_t y sm_event_t son uint8_t. La biblioteca no puede conocer los estados y eventos de cada quien, así que uno define su propio enum y la biblioteca solo guarda los números. Ocho bits mantienen chica cada fila de la tabla, a costa de un límite: 255 estados y eventos, con 0xFF reservado como centinela (SM_ANY_STATE para estados, SM_NO_EVENT para eventos). Para una máquina de estados de firmware, eso sobra. sm_guard_fn devuelve bool: ¿debería aplicar esta fila? Responde una pregunta y no cambia nada. sm_action_fn hace el trabajo. El mismo tipo sirve para las acciones de transición y para los hooks on_entry y on_exit, ya que todos tienen la misma forma: hacer algo, no devolver nada. sm_run_fn es el interesante: devuelve un evento. El on_run de un estado puede observar el mundo (sondear un sensor, revisar un timeout) y reportar lo que pasó, o devolver SM_NO_EVENT si no pasó nada. Así es como un estado genera sus propios eventos sin que quien llama tenga que hacerlo. Todo callback recibe void *ctx. La máquina pasa tal cual el puntero de contexto de quien llama, así que los callbacks nunca necesitan variables globales. Eso significa que se pueden ejecutar varias máquinas independientes, y en las pruebas se puede pasar un contexto falso y verificar exactamente qué pasó. Las funciones que manejan la máquina devuelven un sm_result_t, así que quien llama siempre sabe qué le pasó a un evento: // modules/state_machine/state_machine.h typedef enum { SM_HANDLED, /< A row fired, or sm_run() had nothing to do. */ SM_UNHANDLED, /< No row matches. */ SM_GUARD_REJECTED, /< Rows matched; every guard rejected. */ SM_ERROR /*< NULL, not started, or state out of range. */ } sm_result_t; SM_HANDLED: una regla coincidió y se disparó, o sm_run() no tenía nada que hacer. SM_UNHANDLED: no existe ninguna regla para este estado y evento. El evento se ignoró. SM_GUARD_REJECTED: existían reglas para este estado y evento, pero todas las guardas dijeron que no. El evento se entendió, pero se bloqueó. SM_ERROR: mal uso, no comportamiento. Cubre un argumento NULL, una máquina que no se ha arrancado o un estado fuera de rango. Función de inicialización Igual que el búfer circular y el pool de memoria, la máquina de estados necesita una función de inicialización. Quien llama es dueño del sm_t y de las tablas; sm_init las valida y las conecta. // modules/state_machine/state_machine.c bool sm_init(sm_t *sm, const sm_transition_t *table, size_t count, const sm_state_hooks_t *hooks, sm_state_t state_count, sm_state_t initial, void *ctx) { if (sm == NULL) { return false; } *sm = (sm_t){0}; if (table == NULL || count == 0u || state_count == 0u || initial >= state_count) { return false; } for (size_t i = 0u; i < count; i++) { if (table[i].from != SM_ANY_STATE && table[i].from >= state_count) { return false; } if (table[i].to >= state_count || table[i].event == SM_NO_EVENT) { return false; } } sm->table = table; sm->count = count; sm->hooks = hooks; sm->state_count = state_count; sm->ctx = ctx; sm->current = initial; return true; } Primero, la verificación de NULL sobre sm. Sin un lugar donde escribir, no hay nada más que hacer. *sm = (sm_t){0}; ocurre antes del resto de la validación, a propósito. Si cualquier verificación posterior falla, quien llama se queda con una máquina en cero: started es falso y table es NULL. sm_start la rechaza, y sm_dispatch y sm_run devuelven SM_ERROR en lugar de actuar sobre basura. Un init fallido deja la máquina en un estado seguro y conocido. Verificaciones básicas de argumentos: la tabla tiene que existir, count y state_count no pueden ser cero, e initial tiene que ser un estado válido. Cada fila se valida una sola vez, por adelantado: from tiene que ser un estado real o SM_ANY_STATE. to tiene que ser un estado real. Como SM_ANY_STATE es 0xFF, que siempre es >= state_count, «cualquier estado» queda rechazado automáticamente como destino. No se puede pasar a cualquier estado, y la verificación sale gratis. event no puede ser SM_NO_EVENT, ya que ese valor está reservado para significar «no pasó nada». Después se guardan los campos. Nótese lo que no se asigna: started sigue en falso. Funciones auxiliares Antes de arrancar la máquina, veamos dos pequeñas funciones auxiliares que mantienen los hooks opcionales en todos los niveles: // modules/state_machine/state_machine.c static void run_entry(const sm_t *sm, sm_state_t state) { if (sm->hooks != NULL && sm->hooks[state].on_entry != NULL) { sm->hooks[state].on_entry(sm->ctx); } } static void run_exit(const sm_t *sm, sm_state_t state) { if (sm->hooks != NULL && sm->hooks[state].on_exit != NULL) { sm->hooks[state].on_exit(sm->ctx); } } static: son privadas de state_machine.c. Quien llama nunca invoca los hooks directamente; la máquina decide cuándo se ejecutan. Dos verificaciones de NULL, dos niveles de «opcional»: toda la tabla de hooks puede ser NULL (una máquina sin ningún hook), y cualquier hook individual dentro de ella puede ser NULL (un estado que solo necesita on_entry, por ejemplo). En ambos casos, no se ejecuta nada. Indexadas por estado, sin verificación de límites aquí. Las funciones confían en state, porque todo estado que llega a ellas ya se validó: el estado inicial en sm_init, y cada estado to cuando se revisó su fila. Se valida una vez en los bordes, y el código interno se mantiene simple. Se pasa el ctx de quien llama, así que los hooks trabajan sobre los datos de quien llama, nunca sobre variables globales. Función de arranque sm_init conecta la máquina, pero no ejecuta nada. Arrancar es un paso aparte: sm_start entra al estado inicial, ejecutando su hook on_entry, y marca la máquina como activa. // modules/state_machine/state_machine.c bool sm_start(sm_t *sm) { if (sm == NULL || sm->table == NULL || sm->started) { return false; } run_entry(sm, sm->current); sm->started = true; return true; } sm->table == NULL atrapa un init fallido. Como sm_init pone el struct en cero antes de validar, una máquina que no se pudo inicializar tiene una tabla NULL, así que sm_start la rechaza. Esa es la recompensa de poner en cero primero. sm->started protege contra arrancar dos veces. Una segunda llamada ejecutaría otra vez el on_entry del estado actual: volver a habilitar hardware o reiniciar un temporizador que ya está en marcha. Devolver false hace visible el error en lugar de repetir efectos secundarios en silencio. run_entry(sm, sm->current) ejecuta el hook on_entry del estado inicial, si hay tabla de hooks y ese estado tiene uno, pasando el ctx de quien llama. Luego se asigna started y la función devuelve true. Función de despacho sm_dispatch hace el trabajo pesado: dado un evento, encuentra la primera regla que aplica al estado actual y la lleva a cabo. // modules/state_machine/state_machine.c sm_result_t sm_dispatch(sm_t *sm, sm_event_t event) { if (sm == NULL || !sm->started || sm->current >= sm->state_count) { return SM_ERROR; } bool matched = false; for (size_t i = 0u; i < sm->count; i++) { const sm_transition_t *row = &sm->table[i]; if ((row->from != sm->current && row->from != SM_ANY_STATE) || row->event != event) { continue; } matched = true; if (row->guard != NULL && !row->guard(sm->ctx)) { continue; } if (row->to != sm->current) { run_exit(sm, sm->current); } if (row->action != NULL) { row->action(sm->ctx); } if (row->to != sm->current) { sm->current = row->to; run_entry(sm, sm->current); } return SM_HANDLED; } return matched ? SM_GUARD_REJECTED : SM_UNHANDLED; } Verificaciones defensivas: una máquina NULL, una máquina que nunca se arrancó (incluida una cuyo init falló) o un estado actual fuera del rango válido devuelven SM_ERROR. sm_init ya validó la tabla, pero esta verificación es un seguro barato contra un struct corrupto. Un recorrido lineal, de arriba hacia abajo. Una fila coincide cuando su from es el estado actual (o SM_ANY_STATE) y su event coincide. Todo lo demás se salta. matched = true se asigna antes de revisar la guarda. Esa sola bandera es lo que separa SM_UNHANDLED (no existe ninguna regla) de SM_GUARD_REJECTED (existían reglas, pero todas las guardas dijeron que no). Una guarda fallida significa continue, no return. El recorrido sigue buscando, que es exactamente como funciona el respaldo: en ARMED, la fila de battery_ok falla, así que la siguiente fila de EV_START (la advertencia de batería) tiene su oportunidad. El orden de una transición es salida, luego acción, luego entrada. El estado viejo limpia, la transición hace su trabajo, y luego el estado nuevo se prepara. Gana la primera coincidencia: la función devuelve SM_HANDLED de inmediato, así que las filas posteriores nunca se ejecutan. Las autotransiciones no vuelven a ejecutar los hooks. Cuando to es igual al estado actual (como RUNNING ante EV_SET_SPEED), solo se ejecuta la acción. La salida y la entrada se omiten. Cambiar la velocidad no debería detener y volver a arrancar el motor, que es justo lo que running_exit y luego running_entry le harían a la salida PWM. Algunos frameworks vuelven a ejecutar los hooks en las autotransiciones; elegí no hacerlo, porque en código embebido la entrada y la salida suelen tocar hardware. Las guardas, las acciones y los hooks no deben llamar a sm_dispatch ni a sm_run. Durante la acción, el estado viejo ya salió, pero current todavía no se ha actualizado. Un despacho anidado vería un estado a medio camino de una transición. Una llamada anidada desde una guarda no es mejor: el recorrido externo todavía va a la mitad de la tabla, y seguiría comparando filas contra un current que pudo haber cambiado sin que se diera cuenta. Si una acción necesita disparar otro evento, hay que encolarlo y despacharlo después de que regrese el primero. (El búfer circular de la primera parte es una cola de eventos natural.) Función de ejecución sm_run es lo que se llama desde el bucle principal. Mientras que sm_dispatch reacciona a eventos que entrega alguien más, sm_run le da al estado actual la oportunidad de mirar el mundo y reportar los suyos. // modules/state_machine/state_machine.c sm_result_t sm_run(sm_t *sm) { if (sm == NULL || !sm->started || sm->current >= sm->state_count) { return SM_ERROR; } if (sm->hooks == NULL || sm->hooks[sm->current].on_run == NULL) { return SM_HANDLED; } sm_event_t ev = sm->hooks[sm->current].on_run(sm->ctx); if (ev == SM_NO_EVENT) { return SM_HANDLED; } return sm_dispatch(sm, ev); } Las mismas verificaciones defensivas que sm_dispatch. El mal uso devuelve SM_ERROR antes de que se ejecute cualquier código del usuario. Sin on_run, no hay nada que hacer. Si no hay tabla de hooks, o el estado actual no tiene on_run, devuelve SM_HANDLED. Eso hace que sea seguro llamar a sm_run en cada pasada del bucle, aun cuando el estado actual solo reacciona a eventos externos. El on_run del estado actual recibe el ctx de quien llama y devuelve un evento. Aquí es donde vive el sondeo (polling): leer un sensor, comparar un temporizador contra un timeout o revisar una bandera que activó una ISR. SM_NO_EVENT significa que no pasó nada, que es el caso común, así que devuelve SM_HANDLED. Por eso también sm_init rechaza cualquier fila con SM_NO_EVENT como evento: ese valor nunca se puede despachar. Cualquier otra cosa va directo a sm_dispatch, y su resultado se devuelve tal cual. Un evento reportado por on_run pasa por la misma tabla que uno de quien llama, así que todas las transiciones siguen el mismo camino. Por eso on_run devuelve un evento en lugar de llamar a sm_dispatch por su cuenta. Devolverlo permite que el hook termine antes de que empiece la transición, así que la máquina nunca despacha desde dentro de uno de sus propios hooks. Es la misma regla que para las acciones: los hooks reportan lo que pasó, y la máquina decide qué hacer al respecto. En el caso más simple, donde todos los eventos vienen del on_run de un estado, el bucle principal es una sola llamada: for (;;) { sm_run(&motor_sm); } La mayoría de las máquinas no son tan simples. En el ejemplo del motor, EV_ARM, EV_START y EV_ESTOP vienen de fuera, así que siguen pasando por sm_dispatch. Función de estado actual La última función es la más simple: sm_state devuelve el estado en el que está la máquina. // modules/state_machine/state_machine.c sm_state_t sm_state(const sm_t *sm) { return (sm == NULL) ? SM_ANY_STATE : sm->current; } Solo lectura. Recibe un const sm_t *, así que preguntar no puede cambiar nada. Los campos de sm_t se pueden leer, pero pasar por sm_state evita que quien llama meta mano dentro del struct. NULL devuelve SM_ANY_STATE. Como 0xFF nunca puede ser un estado real, sirve también como «sin respuesta». No hace falta devolver un bool y usar un parámetro de salida como lo hace ring_buffer_get. No verifica started. Antes de sm_start, devuelve el estado inicial de sm_init. Después de un init fallido devuelve 0, del struct en cero, que parece un estado real. Hay que revisar el valor de retorno de sm_init en lugar de confiar en que sm_state avise que algo salió mal. Sirve sobre todo para pruebas y logging. Una prueba típica despacha un evento y luego revisa sm_state para confirmar dónde terminó la máquina. Cierre Eso es una máquina de estados completa. El comportamiento vive en una tabla en lugar de un muro de casos de switch, así que toda la máquina cabe en una pantalla y se lee como una especificación. No hace reserva dinámica, valida su tabla de transiciones una sola vez en el init y manda cada evento por el mismo camino, ya venga de quien llama o del propio on_run de un estado. Las concesiones, todas deliberadas: No es ISR-safe ni thread-safe. sm_dispatch lee y escribe current sin ninguna protección. Los eventos de una ISR van a una cola y se despachan desde un solo contexto. Sin llamadas reentrantes. Las guardas, las acciones y los hooks no deben llamar a sm_dispatch ni a sm_run sobre la misma máquina. on_run devuelve su evento en su lugar, y todo lo demás se encola. Las guardas no deben tener efectos secundarios. Una guarda se puede ejecutar para una fila que nunca se dispara, así que responde una pregunta y no cambia nada. El orden de las filas es comportamiento. Gana la primera coincidencia, así que las filas de seguridad con SM_ANY_STATE van primero y las filas con guarda van arriba de sus respaldos. Reordenar la tabla cambia lo que hace la máquina. Las autotransiciones omiten la entrada y la salida. Solo se ejecuta la acción, así que cambiar la velocidad no detiene ni vuelve a arrancar el motor. Recorrido lineal. Cada despacho recorre la tabla de arriba hacia abajo, lo cual está bien para decenas de filas. Máquina plana. No hay estados jerárquicos, así que el comportamiento compartido entre estados va en filas SM_ANY_STATE. 255 estados y 255 eventos. uint8_t mantiene chica cada fila, y 0xFF está reservado para SM_ANY_STATE y SM_NO_EVENT. No se verifica el tamaño de la tabla de hooks. sm_init solo recibe un puntero, así que no puede saber si hooks tiene state_count entradas, y una tabla corta significa saltar a través de un puntero a función basura. Hay que declararla como hooks[STATE_COUNT], con STATE_COUNT como el último valor del enum de estados. El compilador marca las entradas de más (compilar con -Werror para que sea un error duro), y las que faltan se rellenan con ceros, es decir NULL, que significa sin hook. Los campos de sm_t son de solo lectura. Se pueden leer para depurar, pero escribirlos se salta la validación que hizo sm_init. Para saber dónde está la máquina, hay que preguntarle a sm_state. Llevamos tres patrones, y este es en el que los datos empiezan a significar algo. La mayoría de las aplicaciones embebidas se descomponen en una máquina de estados en cuanto se enumera lo que el sistema puede estar haciendo y lo que le puede pasar, y escribir esa lista como una tabla obliga a responder cada «¿y si...?» por adelantado. El búfer circular y el pool nos dieron almacenamiento al que no le importaba qué guardaba. La máquina de estados decide qué pasa después, y como sm_event_t es un solo byte, el búfer circular de la primera parte puede transportar sus eventos tal cual. Lo que sigue en la serie es el despachador de comandos. Lee su entrada directamente de un búfer circular y asigna cada comando a la función que lo maneja: la misma idea basada en tablas, aplicada a texto en lugar de eventos. Nos vemos ahí.

Common Embedded Patterns: Memory Pool

Ilean Monterrubio Jr — Thu, 10 Sep 2026 00:00:00 +0000

This is the second part of the series re-exploring common embedded patterns. This one focuses on the memory pool. This pattern is often used as an alternative to malloc() and free().

The complete, tested source lives in the companion repo: ileanmjr88/tetzontli. Each pattern in this series is its own module with a full GoogleTest suite, so you can clone it and run the tests yourself.

Basic Concept

Let's start with a quick comparison to the ring buffer pattern. Both patterns are used to store data, but they differ in their point of view of going about it. We refer to the ring buffer as a container. Each item inserted into the data structure is homogeneous and uniform, and it owns the order of that data: you push in, you pop out, following FIFO. The buffer is aware of what's inside it, at least in terms of size and sequence.

The memory pool takes the opposite point of view. It isn't a container, it's custom memory management. It doesn't know the structure of the data being stored, it doesn't care what's in the data, and it doesn't track the sequence. You ask for a block, it checks if one is available, and if it is, it hands you a pointer to that block. From the memory pool's point of view it only sees blocks as occupied or free, with no reference to their structure or the order in which they were handed out.

At this point you're probably wondering what a memory pool is in the simplest terms. It's a buffer of equal-sized memory blocks, typically implemented as an array, so we have a chunk or pool of memory we can grab from. Our init determines the size of our blocks, and initializes the manager structure that keeps track of where the next available block is located.

A Quick Look at `malloc()` and `free()`

Before diving into the memory pool itself, it's worth stepping back and recalling what malloc() and free() actually do. This is important since we'll be implementing similar functionality. The difference is that we pre-allocate a fixed buffer up front, usually a static array, while these functions dynamically allocate and deallocate memory on the heap.

malloc() asks the heap allocator for a chunk of memory, sized for the item you're trying to store. If the allocation is successful, meaning the heap allocator found space, it returns a pointer. If it's unable to find any space it returns NULL, indicating failure. The heap allocator manages this by keeping track of free and used chunks internally. Each time we use malloc() it keeps track of how much we used, and the same goes for free(): each time we free memory it marks it as available. free() does the reverse of malloc(). We call it with the pointer we want to give back to the heap allocator, it marks that chunk as free, and moves on.

These two functions for dynamically allocating and deallocating memory work great on modern computers and in server farms where they have large amounts of memory and a large address space. If a malloc() takes a microsecond longer to find a chunk of memory it's not a big deal. Embedded systems don't get to make those same assumptions, and that's where the cracks start to show:

Fragmentation : as we allocate and deallocate chunks of mixed sizes, the free memory left behind stops being contiguous. Eventually a request fails even though there are more than enough free bytes in total, just not enough of them next to each other. The failure is late, intermittent, and not reproducible on the bench.
Non-deterministic timing : not every embedded system needs deterministic timing, but for the ones that do, malloc() is a problem. The allocator searches for a chunk that fits, so how long it takes depends on the state of the heap. That's hard to accept in a hard-deadline loop, and impossible to budget for.
Late failure : you learn you're out of memory at the exact moment you need memory, which is usually the moment you can least do anything about it. There's no boot-time or link-time answer to "will this fit."

Keeping track of the available blocks

While we aren't using malloc() or free(), it also means we aren't using the built-in heap manager that kept its own record of which chunks were free and which were handed out. Our implementation needs to do that bookkeeping itself. There are really only two things it has to know: whether any block is available at all, and if so, where one is.

Before we get into the implementation used in the tetzontli repo, let's briefly explore two common approaches to this bookkeeping. The first is the bitmap, where each bit of an integer is used to indicate whether a block is in use or free. The number of blocks determines the integer type used. The alternative is the free list method, which threads the available blocks into a linked list, keeping a tracker pointer aimed at the next block that's available. When we deallocate, the block goes back onto the tracker pointer. There is one clear advantage to the free list method: it never has to search. Taking a block means grabbing whatever the tracker pointer is aimed at, and giving one back means putting it at the front. Both are a single pointer update, no matter how full the pool is. The bitmap has to scan for a spare bit, and how long that takes depends on how many blocks are already in use. The bitmap does have one advantage we are giving up though: because it records the state of every block, it can tell a double free from a legitimate one. The free list cannot, and we will come back to what that costs us.

The tetzontli implementation uses the intrusive free list approach. It's a common variation on the free list where each free block itself knows where the next available chunk of memory is located. The reason for this approach is that there's no need to keep a bitmap to keep track of the available blocks, since our next pointer already knows the next available block. Also a reminder, since we aren't allocating memory dynamically, we're using an array as the container to create the pool of memory. That makes traversal easier after init. Once we start to allocate and deallocate, we want the most recently deallocated blocks to be the ones we hand out first, keeping it like a stack, which is friendlier to cache.

Implementation

Memory pool structure

Similar to the ring buffer, we will create a struct. This is a simple way to keep all the parameters together and accessible from a single variable pointer.

// modules/memory_pool/memory_pool.h
typedef struct {
  uint8_t *base;
  size_t block_size;
  size_t capacity;
  size_t used;
  size_t high_water;
  void *free_head;
} memory_pool_t;

uint8_t *base : the address of block 0 , and the anchor the entire pool is measured from. Every block lives at base + i * block_size . It is tempting to read this as the first byte of the buffer you hand to the pool, and most of the time that's exactly what it is, but the two can come apart, for a reason we'll get into in memory_pool_init().
size_t block_size: this is what we will often call the stride. It defines the size of each memory block and how far apart they are from block to block.
size_t capacity: this is the number of blocks in the pool. Fixed at memory_pool_init() and never changes. How many are free at any moment is capacity - used.
size_t used: the number of blocks currently handed out. Incremented by memory_pool_alloc(), decremented by memory_pool_free(). Note handed out, not in use. The pool has no idea what you're doing with a block, only whether it has given it away and not gotten it back.
size_t high_water : the peak value used has ever reached since memory_pool_init(). This is the number you size the pool from: run the system under worst-case load, read it back, and you know how many blocks you actually needed. It deliberately survives memory_pool_reset(). Handing every block back doesn't change the fact that you once needed that many at once, and clearing the peak would throw away the measurement. Only a fresh memory_pool_init() starts it over.
void *free_head: the head of the free list. The first available block to hand out, or NULL when every block is outstanding. The list is intrusive, meaning its links live inside the free blocks themselves rather than in separate node structs. Each free block stores a pointer to the next one in its own first bytes. That's what makes the free list cost zero extra memory, and it's why memory_pool_init() refuses a block_size smaller than a pointer.

Round-up function

We will leverage the is_power_of_two() in this pattern as well but we will also add a new method to round up to the next multiple of a. We covered is_power_of_two() in detail in the ring buffer post, so we won't repeat it here. It rejects zero as well as non-powers of two, which is what keeps block_align = 0 from ever reaching round_up().

// modules/memory_pool/memory_pool.c
static size_t round_up(size_t x, size_t a) {
  return (x + (a - 1u)) & ~(a - 1u);
}

(x + (a - 1u)) : This takes the variable x, the number we want to round up, and the variable a, the alignment we want to round it up to. Adding a - 1 first is what pushes any value that isn't already on a boundary past the next one.
~(a - 1u) : this takes the number we want to align by, subtracts one, and does a bitwise not, which gives us a mask that clears the low bits and leaves everything above them alone.
Taking both and doing the bitwise & drops the value back down onto a boundary. On its own that would round down. Adding a - 1 first is what turns it into a round up. This can be confusing at first glance.

caller: round_up(x = 12, a = 16);

- (x + (a - 1u)) = (12 + (16 - 1u)) = (12 + 15) = 27 = 0b00011011
- (a - 1u) = (16 - 1u) = 15

Taking the evaluation further on the right hand side of the &
- ~(15) = ~(0b00001111) = 0b11110000

Now putting both sides together 
- 0b00011011 & 0b11110000 = 0b00010000 = 16

Meaning we need to round up 12 to 16

And when the value is already on a boundary, nothing moves:
- round_up(16, 16) = (16 + 15) & ~15
- 0b00011111 & 0b11110000 = 0b00010000 = 16

In the ring buffer, the masking trick only worked because the capacity was a power of two. The same rule applies here, except it lands on a, the alignment we are rounding up to, and not on the capacity. a needs to be a power of two, which is why memory_pool_init() runs is_power_of_two() on it before doing any rounding at all.

Example when a is not a power of two.

- round_up(12, 12) = (12 + 11) & ~11 = 23 & ~11
- 0b00010111 & ~0b00001011 = 0b00010111 & 0b11110100 = 0b00010100 = 20

It should yield 12, since 12 is already a multiple of 12 and a correct
round up would leave it alone. The reason it breaks is that 11 is
0b00001011, not a clean run of ones, so the mask clears the wrong bits.
This is why the power of two is used here to be able to optimize the round_up.

Reset function

Before we get to the init function, it's worth talking about how we reset the memory pool. This does the job of relinking the blocks of memory in sequential order, which makes it handy to reuse inside init.

// modules/memory_pool/memory_pool.c
void memory_pool_reset(memory_pool_t *mp) {
  if (mp == NULL) {
    return;
  }

  mp->free_head = NULL;
  for (size_t i = mp->capacity; i-- > 0;) {
    uint8_t *blk = mp->base + i * mp->block_size;
    write_next(blk, mp->free_head);
    mp->free_head = blk;
  }
  mp->used = 0u;
}

We start with a quick check that we didn't pass a NULL pointer to the function. Without it, the very next line, mp->free_head = NULL, would dereference that null handle. On a desktop that's a segmentation fault. On most microcontrollers there's no MMU to catch it, so address zero is real memory, often the vector table, and the write quietly succeeds and corrupts something instead. If mp is an actual memory address, we set mp->free_head = NULL so we know the state we're starting from before we assign the next pointer in each block.

Then we iterate with for (size_t i = mp->capacity; i-- > 0;). The decrement lives in the comparison so the check runs first and the decrement second, which means the body sees capacity - 1 down to 0, and the loop exits after 0 has run. The obvious version, for (size_t i = capacity - 1; i >= 0; i--), never terminates. size_t is unsigned, so i >= 0 is always true, and decrementing 0 wraps around to SIZE_MAX rather than going negative. This is the same unsigned wraparound we leaned on in the ring buffer's count, working against us here instead of for us.

The direction matters for a second reason. Each pass writes the current head into a block and then makes that block the new head, so walking the array backwards produces a list that comes out forwards. After a reset the first memory_pool_alloc() returns block 0, the next returns block 1, and so on in address order. Build the list the other way and the pool works identically, it just hands out descending addresses, which is harder to read when you are staring at pointer values in a debugger.

memory_pool_reset() rebuilds the whole list without asking who is holding what, so it invalidates every outstanding pointer. used goes back to zero, while high_water deliberately does not.

Initialization function

The initialization function is our entry point of actually starting to use this pattern. It will accept as parameters: memory_pool_t *mp, void *storage, size_t storage_size, size_t block_size, size_t block_align.

// modules/memory_pool/memory_pool.c
bool memory_pool_init(memory_pool_t *mp, void *storage, size_t storage_size, size_t block_size, size_t block_align) {
  if (mp == NULL || storage == NULL || !is_power_of_two(block_align) || block_size < sizeof(void *)) {
    return false;
  }

  if (block_align < _Alignof(void *)) {
    block_align = _Alignof(void *);
  }

  size_t stride = round_up(block_size, block_align);
  if (stride < block_size) {
    return false;
  }

  uintptr_t addr = (uintptr_t)storage;
  uintptr_t aligned = (uintptr_t)round_up((size_t)addr, block_align);
  uint8_t *base = (uint8_t *)aligned;

  size_t offset = (size_t)(base - (uint8_t *)storage);
  if (offset >= storage_size) {
    return false;
  }

  size_t usable = storage_size - offset;
  size_t capacity = usable / stride;
  if (capacity == 0u) {
    return false;
  }

  mp->base = base;
  mp->block_size = stride;
  mp->capacity = capacity;
  mp->used = 0u;
  mp->high_water = 0u;
  memory_pool_reset(mp);
  return true;
}

The first thing when passing or dealing with pointers is to make sure they are not NULL. A null pointer means we would be writing to memory address zero. As stated before, on a computer that's a segmentation fault, but here we could write at address zero and corrupt an unintended address. The check also verifies explicitly that block_align is a power of two, since round_up is called twice further down and only works under that guarantee. The final check is block_size < sizeof(void *). Any block we hand out has to be big enough to hold a free list link while it's free, so a block smaller than a pointer would have its link spill into the block next to it.

Alignment clamp: block_align gets raised to _Alignof(void *) if you ask for less. You're allowed to request 1-byte alignment, but the free list stores a pointer inside every free block, so the pool quietly gives you pointer alignment instead. Same reason as the block_size guard, from the other direction. It is worth spelling out what falls out of this: because base is aligned and the stride is a multiple of block_align, every block in the pool is aligned, not just the first one. That is the guarantee you are leaning on when you put a struct in a block, so pass _Alignof(T) for a pool of T. The clamp only promises pointer alignment on its own.
Overflow guard: if (stride < block_size) looks unreachable, since rounding up can't make a number smaller. It catches wraparound: round_up adds a - 1 before masking, and if block_size is near SIZE_MAX that addition wraps. That is unsigned wraparound biting us again, this time caught on purpose.
Base bump: the caller's buffer may not start on an aligned address, so base gets rounded up and the lead-in bytes are lost. That's offset, and it's why base and storage can differ.
Capacity math: usable / stride, with the remainder discarded. Between the bump and the truncation, capacity is usually less than storage_size / block_size, which is why memory_pool_capacity() exists rather than the caller computing it. Align your storage yourself, with alignas on the array set at least as large as the block_align you pass, and the bump costs you nothing. Leave it to chance and you can quietly lose a block.

Allocate and free functions

Now that we have initialized the memory pool we can start using it. To memory_pool_alloc() we will need to pass the parameter of memory_pool_t *mp:

// modules/memory_pool/memory_pool.c
void *memory_pool_alloc(memory_pool_t *mp) {
  if (mp == NULL || mp->free_head == NULL) {
    return NULL;
  }

  void *p = mp->free_head;
  mp->free_head = read_next(p);
  mp->used++;
  if (mp->used > mp->high_water) {
    mp->high_water = mp->used;
  }
  return p;
}

We do our standard check that mp is not NULL, and alongside it we check mp->free_head. That second one is how an exhausted pool announces itself: the free list being empty is the head being NULL, so there is no need for a separate is_empty helper the way the ring buffer needed one. Returning NULL here also matches malloc(), so a caller that already handles a failed allocation doesn't have to learn a new convention. If both checks pass, we create a new pointer p and point it at mp->free_head. That is the block we are about to hand back to the caller, and before we let go of it we call read_next(p) to pull the link out of its first bytes, which is what becomes the new head. The last thing we do is bookkeeping: mp->used++ records that one more block is outstanding, and if that pushes used past mp->high_water we move the peak up with it. That comparison is the only place high_water ever changes.

Next, memory_pool_free():

// modules/memory_pool/memory_pool.c
bool memory_pool_free(memory_pool_t *mp, void *block) {
  if (!memory_pool_owns(mp, block)) {
    return false;
  }
  if (mp->used == 0u) {
    return false;
  }

  write_next(block, mp->free_head);
  mp->free_head = block;
  mp->used--;
  return true;
}

Giving a block back is the mirror image. The first check hands the pointer to memory_pool_owns(), the subject of the next section, which answers whether this is actually the start of a block in this pool. The second, mp->used == 0u, rejects a free into a pool with nothing outstanding. Both run before we write anything, so a rejected free leaves the pool completely untouched, free list included. The order of those two is not interchangeable either, since mp->used dereferences mp and is only safe because memory_pool_owns() already turned away a null pool. Swap them to fail on the cheaper check first and you have written a null dereference.

Then we push. write_next(block, mp->free_head) writes the current head into the returned block, mp->free_head = block makes that block the new head, and mp->used-- brings the count down. This is the stack behavior from earlier: the block you just gave back is the one the next memory_pool_alloc() hands out.

There is one case these checks cannot catch, freeing the same block twice. We will come back to that after the implementation.

Memory pool owns memory address

// modules/memory_pool/memory_pool.c
bool memory_pool_owns(const memory_pool_t *mp, const void *p) {
  if (mp == NULL || p == NULL) {
    return false;
  }

  uintptr_t addr = (uintptr_t)p;
  uintptr_t base = (uintptr_t)mp->base;
  uintptr_t end = base + ((uintptr_t)mp->capacity * (uintptr_t)mp->block_size);

  if (addr < base || addr >= end){
    return false;
  }
  return (addr - base) % (uintptr_t)mp->block_size == 0u;
}

This is the validation memory_pool_free() leans on, and it asks two questions. The first is whether the pointer is inside the arena at all, comparing it against base and end.

The second is the interesting one: (addr - base) % mp->block_size == 0u checks the pointer is exactly on a block boundary. A pointer into the middle of a block passes the range test but is not a block, and freeing it would splice a bogus node into the free list at an offset, so the next allocation would hand out a block overlapping its neighbor. This modulo is the one division in the module, and it is the same cost we avoided in the ring buffer. Making the stride a power of two turns it back into a mask.

Capacity function

Knowing the capacity is important because from that we can identify how much of the memory pool we have to hand out to be used.

// modules/memory_pool/memory_pool.c
size_t memory_pool_capacity(const memory_pool_t *mp) {
  return (mp == NULL) ? 0u : mp->capacity;
}

We do our NULL check on mp. If it is null we return 0u, otherwise we return the capacity derived back in memory_pool_init().

Helper functions

These are the functions to access the data members of the memory_pool_t without modifying them. We will get started with memory_pool_used():

// modules/memory_pool/memory_pool.c
size_t memory_pool_used(const memory_pool_t *mp) {
  return (mp == NULL) ? 0u : mp->used;
}

Here we just check that the mp passed as an argument is not NULL, otherwise we return the field we are asking for, in this case mp->used.

// modules/memory_pool/memory_pool.c
size_t memory_pool_available(const memory_pool_t *mp) {
  return (mp == NULL) ? 0u : mp->capacity - mp->used;
}

size_t memory_pool_high_water(const memory_pool_t *mp) {
  return (mp == NULL) ? 0u : mp->high_water;
}

Here we have the remainder of the helper functions, following the same NULL check and returning the value we asked for. Note that memory_pool_available() works out capacity - used rather than walking the free list to count what's left, which is the same answer without the traversal.

Example usage

Now that we have explained the full implementation, let's see how we will use the pattern.

typedef struct {
  uint32_t timestamp;
  int16_t value;
  uint8_t sensor_id;
} sample_t;

static alignas(void *) uint8_t sample_storage[16 * sizeof(sample_t)];
static memory_pool_t sample_pool;
static sample_t *current;

bool sensor_init(void) {
  return memory_pool_init(&sample_pool, sample_storage, sizeof sample_storage,
                          sizeof(sample_t), _Alignof(sample_t));
}

bool sensor_take_reading(uint8_t sensor_id) {
  current = memory_pool_alloc(&sample_pool);
  if (current == NULL) {
    return false;
  }

  current->timestamp = now();
  current->value = read_adc(sensor_id);
  current->sensor_id = sensor_id;
  return true;
}

void sensor_flush(void) {
  if (current == NULL) {
    return;
  }

  transmit(current);
  memory_pool_free(&sample_pool, current);
  current = NULL;
}

This example shows we will be using the memory pool to store sample_t, which is made up of timestamp, value and sensor_id. Notice the block is allocated in one function and freed in another. That is the point of the pool, the memory outlives the call that asked for it, which is what lets a reading sit around until something else is ready to deal with it. One slot keeps the example short; a real caller holds several at once.

Now alignas(void *) on sample_storage. We pass _Alignof(sample_t) to init, but init clamps that up to _Alignof(void *), because every free block has to hold a pointer. The storage has to satisfy whichever of the two ends up larger, and here that's void *, on a 64-bit host it's 8 against sample_t's 4, and on a 32-bit target the two are equal, so aligning to the pointer covers both. Get it wrong and base gets bumped forward and you quietly lose a block. Notice we declare sample_storage as uint8_t so the array is raw bytes and we can size it by multiplying the block count by sizeof(sample_t). Note that alignas needs <stdalign.h> in C11, and the snippet leaves out the includes.

Also notice the pool has no idea which sensor a block belongs to. sensor_id is a field we put in the struct ourselves, not something the pool tracks. It only ever knew the block size and alignment we handed it at init.

Notice that alloc, free, and the way we use the memory in between are the same shape as malloc() and free(). Ask for memory, check for NULL, use it, hand it back. That is deliberate, code written against the heap ports over by changing two call sites. Two differences worth knowing: memory_pool_free() returns a bool instead of nothing, and freeing the same block twice does not behave the way your heap allocator would. We will get to that next.

Double-free edge case

Back in memory_pool_free() we said there was one case the checks cannot catch. Freeing into an empty pool is rejected by mp->used == 0u, and a pointer that isn't a block start is rejected by memory_pool_owns(). But freeing a block that is already on the free list passes both. It is a legitimate block start, so owns says yes, and other blocks are still outstanding, so used is nonzero.

So the push runs. We write free_head into the block and then make the block the new head. If that block was already the head, it now points at itself.

Before:
  free_head -> [B] -> [C] -> NULL

memory_pool_free(mp, B) a second time:
  write_next(B, free_head) B's next now points at B
  free_head = B

After:
  free_head -> [B] -> [B] -> [B] -> ...

  alloc() returns B
  alloc() returns B again, to a different caller

Nothing reports this. memory_pool_free() returns true, used looks plausible, and every query says the pool is healthy. You find it later, in whatever code was unlucky enough to own the block second.

There are ways to catch it and both cost something we chose this pattern for. We could walk the free list on every free and reject a block already on it, which is correct and turns a constant-time free into a scan. We could keep a side bitmap of allocated blocks, which costs memory and gives up the zero-overhead property that motivated the intrusive list in the first place. For a small firmware codebase where the allocation sites are few and reviewable, documenting it is a defensible trade, and the limitation is written into the header right next to the function that cannot catch it. For a larger codebase it would be worth paying for a debug-build check.

Wrap-up

That's a complete memory pool. It does no dynamic allocation, hands blocks out and takes them back in constant time with no search, carries zero bytes of per-block overhead, cannot fragment by construction, and tells you afterwards how much of it you actually needed.

The trades, all deliberate:

One size per pool. Four object types means four pools. This is what buys away fragmentation, and it makes the pool a poor fit for genuinely variable-sized data.
Not thread-safe or ISR-safe. Unlike the ring buffer, there is no lock-free path here. Every mutating call touches free_head, and there is no way to split that between two contexts the way head and tail split. A shared pool needs a critical section around every mutating call, which is also why there is no volatile anywhere in memory_pool_t.
Blocks aren't zeroed. These are malloc semantics, not calloc. A fresh block holds a stale free list pointer in its first bytes and whatever the last owner left in the rest.
Double free is only partly detectable. Covered above, and the most important limitation in the module.
Capacity is derived, not given. Stride rounding, the alignment bump, and the tail remainder all eat into it. Read it back with memory_pool_capacity().

Two patterns in and they have started to lean on each other. The ring buffer gave us fixed storage for bytes, the pool gives us fixed storage for objects, and the event queue later in this series will want both: a ring of pointers to blocks handed out by a pool. That is how you get a queue of structs without a single call to malloc.

Next in the series is the state machine. The ring buffer and the pool both dealt in storage, bytes in one and blocks in the other, and neither cared what any of it meant. The state machine is where it starts to mean something.

Patrones embebidos comunes: pool de memoria

Ilean Monterrubio Jr — Thu, 10 Sep 2026 00:00:00 +0000

Esta es la segunda parte de la serie donde vuelvo a explorar los patrones embebidos más comunes. Esta vez le toca al pool de memoria (memory pool). Este patrón se usa a menudo como alternativa a malloc() y free().

El código fuente completo y probado vive en el repositorio complementario: ileanmjr88/tetzontli. Cada patrón de esta serie es su propio módulo con una suite completa de pruebas en GoogleTest, así que puedes clonarlo y ejecutar las pruebas tú mismo.

Concepto básico

Empecemos con una comparación rápida contra el búfer circular. Ambos patrones sirven para guardar datos, pero difieren en el punto de vista desde el cual lo hacen. Al búfer circular lo llamamos contenedor. Cada elemento que se inserta en la estructura de datos es homogéneo y uniforme, y el búfer es dueño del orden de esos datos: se empuja por un lado y se saca por el otro, siguiendo FIFO. El búfer sabe qué hay dentro, al menos en cuanto a tamaño y secuencia.

El pool de memoria toma el punto de vista opuesto. No es un contenedor, es gestión de memoria propia. No conoce la estructura de los datos que se guardan, no le importa qué contienen, y no lleva registro de la secuencia. Uno pide un bloque, el pool revisa si hay alguno disponible, y si lo hay, devuelve un puntero a ese bloque. Desde el punto de vista del pool solo existen bloques ocupados o libres, sin referencia a su estructura ni al orden en que se entregaron.

Llegados a este punto, la pregunta obvia es qué es un pool de memoria en los términos más simples. Es un búfer de bloques de memoria del mismo tamaño, normalmente implementado como un arreglo, así que tenemos un trozo o pool de memoria del cual tomar. Nuestro init determina el tamaño de los bloques e inicializa la estructura administradora que lleva registro de dónde está el siguiente bloque disponible.

Un repaso rápido a `malloc()` y `free()`

Antes de entrar al pool de memoria en sí, vale la pena dar un paso atrás y recordar qué hacen realmente malloc() y free(). Es importante porque vamos a implementar una funcionalidad parecida. La diferencia es que nosotros reservamos por adelantado un búfer de tamaño fijo, normalmente un arreglo estático, mientras que estas funciones reservan y liberan memoria del heap de forma dinámica.

malloc() le pide al asignador del heap un trozo de memoria del tamaño del elemento que se quiere guardar. Si la reserva tiene éxito, es decir, si el asignador encontró espacio, devuelve un puntero. Si no logra encontrar espacio devuelve NULL, indicando el fallo. El asignador del heap gestiona esto llevando su propio registro interno de los trozos libres y usados. Cada vez que usamos malloc() lleva registro de cuánto usamos, y lo mismo con free(): cada vez que liberamos memoria la marca como disponible. free() hace lo contrario de malloc(): se llama con el puntero que queremos devolverle al asignador del heap, este marca ese trozo como libre, y sigue adelante.

Estas dos funciones para reservar y liberar memoria dinámicamente funcionan muy bien en computadoras modernas y en granjas de servidores, donde hay grandes cantidades de memoria y un espacio de direcciones amplio. Si un malloc() tarda un microsegundo más en encontrar un trozo de memoria no pasa nada. Los sistemas embebidos no pueden hacer esas mismas suposiciones, y ahí es donde empiezan a aparecer las grietas:

Fragmentación : a medida que reservamos y liberamos trozos de tamaños mezclados, la memoria libre que va quedando deja de ser contigua. Con el tiempo una petición falla aunque en total haya bytes libres de sobra, solo que no hay suficientes juntos. El fallo llega tarde, es intermitente y no se reproduce en el banco de pruebas.
Tiempos no deterministas : no todo sistema embebido necesita tiempos deterministas, pero para los que sí, malloc() es un problema. El asignador busca un trozo que quepa, así que cuánto tarda depende del estado del heap. Eso es difícil de aceptar en un bucle con plazos estrictos, e imposible de presupuestar.
Fallo tardío : uno se entera de que se quedó sin memoria justo en el momento en que necesita memoria, que suele ser el momento en que menos puede hacer al respecto. No hay respuesta en tiempo de arranque ni en tiempo de enlazado a la pregunta «¿esto va a caber?».

Llevar el registro de los bloques disponibles

Que no usemos malloc() ni free() también significa que no usamos el administrador del heap, que llevaba su propio registro de qué trozos estaban libres y cuáles entregados. Nuestra implementación tiene que hacer esa contabilidad por su cuenta. En realidad solo hay dos cosas que necesita saber: si hay algún bloque disponible, y si lo hay, dónde está.

Antes de entrar en la implementación que se usa en el repositorio tetzontli, exploremos brevemente dos enfoques comunes para esta contabilidad. El primero es el mapa de bits (bitmap), donde cada bit de un entero indica si un bloque está en uso o libre. La cantidad de bloques determina el tipo de entero que se usa. La alternativa es el método de la lista de libres (free list), que enhebra los bloques disponibles en una lista enlazada y mantiene un puntero apuntando al siguiente bloque disponible. Al liberar, el bloque vuelve al frente de ese puntero. Hay una ventaja clara en el método de la lista de libres: nunca tiene que buscar. Tomar un bloque significa quedarse con aquello a lo que apunta el puntero de seguimiento, y devolver uno significa ponerlo al frente. Ambas son una sola actualización de puntero, sin importar qué tan lleno esté el pool. El mapa de bits tiene que recorrer buscando un bit libre, y cuánto tarda depende de cuántos bloques ya estén en uso. Eso sí, el mapa de bits tiene una ventaja a la que estamos renunciando: como registra el estado de cada bloque, puede distinguir una doble liberación de una legítima. La lista de libres no puede, y volveremos a lo que eso nos cuesta.

La implementación de tetzontli usa el enfoque de lista de libres intrusiva. Es una variación común donde cada bloque libre sabe por sí mismo dónde está el siguiente trozo de memoria disponible. La razón de este enfoque es que no hace falta un mapa de bits para llevar registro de los bloques disponibles, ya que nuestro puntero next ya sabe cuál es el siguiente bloque libre. También un recordatorio: como no reservamos memoria dinámicamente, usamos un arreglo como contenedor para crear el pool de memoria. Eso facilita el recorrido después del init. Una vez que empezamos a reservar y liberar, queremos que los bloques liberados más recientemente sean los primeros en entregarse, manteniéndolo como una pila, lo cual es más amigable con caché.

Implementación

Estructura del pool de memoria

Igual que en el búfer circular, vamos a crear un struct. Es una forma simple de mantener todos los parámetros juntos y accesibles desde un solo puntero.

// modules/memory_pool/memory_pool.h
typedef struct {
  uint8_t *base;
  size_t block_size;
  size_t capacity;
  size_t used;
  size_t high_water;
  void *free_head;
} memory_pool_t;

uint8_t *base: la dirección del bloque 0, y el ancla desde la cual se mide todo el pool. Cada bloque vive en base + i * block_size. Es tentador leer esto como el primer byte del búfer que se le entrega al pool, y la mayoría de las veces eso es exactamente lo que es, pero los dos pueden separarse, por una razón que veremos en memory_pool_init().
size_t block_size: esto es lo que solemos llamar el stride. Define el tamaño de cada bloque de memoria y qué tan separados están entre sí.
size_t capacity: la cantidad de bloques del pool. Se fija en memory_pool_init() y nunca cambia. Cuántos están libres en un momento dado es capacity - used.
size_t used: la cantidad de bloques entregados. memory_pool_alloc() lo incrementa y memory_pool_free() lo decrementa. Ojo: entregados, no en uso. El pool no tiene idea de qué se hace con un bloque, solo de si lo entregó y no lo ha recuperado.
size_t high_water: el valor máximo que used ha alcanzado desde memory_pool_init(). Este es el número con el que se dimensiona el pool: ejecutar el sistema bajo la peor carga, leerlo de vuelta, y así se sabe cuántos bloques hacían falta realmente. Sobrevive deliberadamente a memory_pool_reset(). Devolver todos los bloques no cambia el hecho de que en algún momento se necesitaron todos esos a la vez, y borrar el pico tiraría a la basura la medición. Solo un memory_pool_init() nuevo lo reinicia.
void *free_head: la cabeza de la lista de libres. El primer bloque disponible para entregar, o NULL cuando todos los bloques están fuera. La lista es intrusiva, es decir, sus enlaces viven dentro de los propios bloques libres en vez de en structs de nodo aparte. Cada bloque libre guarda un puntero al siguiente en sus primeros bytes. Eso es lo que hace que la lista de libres no cueste memoria extra, y es la razón por la que memory_pool_init() rechaza un block_size más chico que un puntero.

Función de redondeo hacia arriba

También vamos a aprovechar is_power_of_two() en este patrón, y además agregamos un método nuevo para redondear hacia arriba al siguiente múltiplo de a. Cubrimos is_power_of_two() en detalle en el post del búfer circular, así que no lo repetimos aquí. Rechaza el cero además de los números que no son potencia de dos, que es lo que impide que block_align = 0 llegue a round_up().

// modules/memory_pool/memory_pool.c
static size_t round_up(size_t x, size_t a) {
  return (x + (a - 1u)) & ~(a - 1u);
}

(x + (a - 1u)): toma la variable x, el número que queremos redondear hacia arriba, y la variable a, la alineación a la que queremos redondearlo. Sumar a - 1 primero es lo que empuja cualquier valor que no esté ya en un límite más allá del siguiente.
~(a - 1u): toma el número por el que queremos alinear, le resta uno, y aplica un not a nivel de bits, lo cual nos da una máscara que limpia los bits bajos y deja intacto todo lo que está por encima.
Tomar ambos lados y hacer el & a nivel de bits baja el valor de vuelta a un límite. Por sí solo eso redondearía hacia abajo. Sumar a - 1 primero es lo que lo convierte en un redondeo hacia arriba. Esto puede confundir a primera vista.

llamada: round_up(x = 12, a = 16);

- (x + (a - 1u)) = (12 + (16 - 1u)) = (12 + 15) = 27 = 0b00011011
- (a - 1u) = (16 - 1u) = 15

Siguiendo la evaluación del lado derecho del &
- ~(15) = ~(0b00001111) = 0b11110000

Ahora juntando ambos lados
- 0b00011011 & 0b11110000 = 0b00010000 = 16

Es decir, hay que redondear 12 hacia arriba hasta 16

Y cuando el valor ya está en un límite, nada se mueve:
- round_up(16, 16) = (16 + 15) & ~15
- 0b00011111 & 0b11110000 = 0b00010000 = 16

En el búfer circular, el truco de la máscara solo funcionaba porque la capacidad era potencia de dos. Aquí aplica la misma regla, salvo que recae sobre a, la alineación a la que redondeamos, y no sobre la capacidad. a tiene que ser potencia de dos, y por eso memory_pool_init() le aplica is_power_of_two() antes de hacer cualquier redondeo.

Ejemplo cuando a no es potencia de dos.

- round_up(12, 12) = (12 + 11) & ~11 = 23 & ~11
- 0b00010111 & ~0b00001011 = 0b00010111 & 0b11110100 = 0b00010100 = 20

Debería dar 12, ya que 12 ya es múltiplo de 12 y un redondeo correcto
lo dejaría igual. Falla porque 11 es 0b00001011, no una serie limpia
de unos, así que la máscara limpia los bits equivocados.
Por eso aquí se usa la potencia de dos, para poder optimizar round_up.

Funciones de lectura y escritura del siguiente

Este par de funciones son las que leen cuál es el siguiente bloque disponible y actualizan cuál pasa a serlo. Empecemos con read_next(): para cada reserva vamos a necesitar leer dónde está el siguiente bloque a entregar.

// modules/memory_pool/memory_pool.c
static void *read_next(const void *block) {
  void *const *slot = (void *const *)block;
  void *next;
  memcpy(&next, slot, sizeof next);
  return next;
}

Esta función toma el puntero block, que llega como const void *, y lo castea a void *const *. Ese cast se lee de derecha a izquierda: slot es un puntero a un puntero constante a void. El const aplica al puntero guardado dentro del bloque, no a slot en sí, y está ahí para que el cast no descarte silenciosamente el calificador que el parámetro ya traía. Creamos la variable void *next como contenedor al cual copiar. Hacemos una copia de memoria de sizeof next bytes desde el slot hacia next. Así es como devolvemos un puntero al siguiente bloque de datos disponible.

Vale la pena detenerse en el memcpy, porque la versión obvia es una sola línea, return *(void **)block;. El problema es que esos bytes viven dentro de un arreglo de uint8_t, así que leerlos a través de un void** significa acceder a un objeto mediante un puntero de otro tipo, que es justo lo que prohíben las reglas de aliasing. El compilador tiene permiso de asumir que no hicimos eso. memcpy es la manera sancionada de decir «copia estos bytes tal cual sin afirmar nada sobre tipos», y no cuesta nada en cualquier nivel de optimización por encima de -O0: todo compilador reconoce un memcpy del tamaño de un puntero y emite una sola carga o escritura. En una compilación de depuración se queda como una llamada real, lo cual conviene saber pero no amerita cambiar el código.

Sigue write_next():

// modules/memory_pool/memory_pool.c
static void write_next(void *block, void *next) {
  void **slot = (void**)block;
  memcpy(slot, &next, sizeof next);
}

Esta función es el espejo de read_next(). La diferencia es que recibimos void *block y declaramos slot como void **, asignándole el cast de block, lo cual le dice al compilador que trate esos primeros bytes como un lugar donde vive un puntero. Después copiamos sizeof next bytes desde &next, la dirección de nuestra variable local, hacia el slot. Lo que queda en el bloque es el valor del puntero mismo. Ninguna de estas dos funciones mira nunca block_size, solo tocan los primeros sizeof(void *) bytes, y por eso la lista de libres cuesta lo mismo sin importar qué tan grandes sean los bloques.

Función de reinicio (reset)

Antes de llegar a la función init, conviene hablar de cómo reiniciamos el pool de memoria. Esta hace el trabajo de reenlazar los bloques de memoria en orden secuencial, lo cual la vuelve práctica para reutilizarla dentro de init.

// modules/memory_pool/memory_pool.c
void memory_pool_reset(memory_pool_t *mp) {
  if (mp == NULL) {
    return;
  }

  mp->free_head = NULL;
  for (size_t i = mp->capacity; i-- > 0;) {
    uint8_t *blk = mp->base + i * mp->block_size;
    write_next(blk, mp->free_head);
    mp->free_head = blk;
  }
  mp->used = 0u;
}

Empezamos con una verificación rápida de que no le pasamos un puntero NULL a la función. Sin ella, la siguiente línea, mp->free_head = NULL, dereferenciaría ese handle nulo. En una computadora de escritorio eso es un fallo de segmentación. En la mayoría de los microcontroladores no hay MMU que lo atrape, así que la dirección cero es memoria real, a menudo la tabla de vectores, y la escritura tiene éxito en silencio y corrompe algo. Si mp es una dirección de memoria real, ponemos mp->free_head = NULL para saber desde qué estado partimos antes de asignar el puntero siguiente en cada bloque.

Después iteramos con for (size_t i = mp->capacity; i-- > 0;). El decremento vive dentro de la comparación, así que la verificación va primero y el decremento después, lo que significa que el cuerpo ve desde capacity - 1 hasta 0, y el bucle termina después de ejecutar el 0. La versión obvia, for (size_t i = capacity - 1; i >= 0; i--), nunca termina. size_t es sin signo, así que i >= 0 siempre es verdadero, y decrementar 0 da la vuelta hasta SIZE_MAX en lugar de volverse negativo. Este es el mismo desbordamiento sin signo en el que nos apoyamos con el count del búfer circular, solo que aquí trabaja en nuestra contra.

La dirección importa por una segunda razón. Cada pasada escribe la cabeza actual dentro de un bloque y luego hace de ese bloque la nueva cabeza, así que recorrer el arreglo hacia atrás produce una lista que sale hacia adelante. Después de un reinicio, el primer memory_pool_alloc() devuelve el bloque 0, el siguiente devuelve el 1, y así en orden de direcciones. Si se construye la lista al revés el pool funciona igual, solo que entrega direcciones descendentes, lo cual es más difícil de leer cuando uno está mirando valores de punteros en un depurador.

memory_pool_reset() reconstruye la lista completa sin preguntar quién tiene qué, así que invalida todos los punteros pendientes. used vuelve a cero, mientras que high_water deliberadamente no.

Función de inicialización

La función de inicialización es nuestro punto de entrada para empezar a usar el patrón. Acepta como parámetros: memory_pool_t *mp, void *storage, size_t storage_size, size_t block_size, size_t block_align.

// modules/memory_pool/memory_pool.c
bool memory_pool_init(memory_pool_t *mp, void *storage, size_t storage_size, size_t block_size, size_t block_align) {
  if (mp == NULL || storage == NULL || !is_power_of_two(block_align) || block_size < sizeof(void *)) {
    return false;
  }

  if (block_align < _Alignof(void *)) {
    block_align = _Alignof(void *);
  }

  size_t stride = round_up(block_size, block_align);
  if (stride < block_size) {
    return false;
  }

  uintptr_t addr = (uintptr_t)storage;
  uintptr_t aligned = (uintptr_t)round_up((size_t)addr, block_align);
  uint8_t *base = (uint8_t *)aligned;

  size_t offset = (size_t)(base - (uint8_t *)storage);
  if (offset >= storage_size) {
    return false;
  }

  size_t usable = storage_size - offset;
  size_t capacity = usable / stride;
  if (capacity == 0u) {
    return false;
  }

  mp->base = base;
  mp->block_size = stride;
  mp->capacity = capacity;
  mp->used = 0u;
  mp->high_water = 0u;
  memory_pool_reset(mp);
  return true;
}

Lo primero al pasar o manejar punteros es asegurarse de que no sean NULL. Un puntero nulo significa que estaríamos escribiendo en la dirección de memoria cero. Como ya dijimos, en una computadora eso es un fallo de segmentación, pero aquí podríamos escribir en la dirección cero y corromper una dirección no intencionada. La verificación también comprueba explícitamente que block_align sea potencia de dos, ya que round_up se llama dos veces más abajo y solo funciona bajo esa garantía. La última verificación es block_size < sizeof(void *). Cualquier bloque que entreguemos tiene que ser lo bastante grande para guardar un enlace de la lista de libres mientras está libre, así que un bloque más chico que un puntero derramaría su enlace sobre el bloque de al lado.

Ajuste de alineación: block_align se sube a _Alignof(void *) si se pide menos. Está permitido pedir alineación de 1 byte, pero la lista de libres guarda un puntero dentro de cada bloque libre, así que el pool entrega en silencio alineación de puntero en su lugar. Misma razón que la guarda de block_size, desde el otro lado. Conviene explicitar lo que se desprende de esto: como base está alineado y el stride es múltiplo de block_align, todos los bloques del pool quedan alineados, no solo el primero. Esa es la garantía en la que uno se apoya al meter un struct en un bloque, así que hay que pasar _Alignof(T) para un pool de T. El ajuste por sí solo únicamente promete alineación de puntero.
Guarda de desbordamiento: if (stride < block_size) parece inalcanzable, ya que redondear hacia arriba no puede hacer un número más chico. Lo que atrapa es la vuelta al inicio: round_up suma a - 1 antes de enmascarar, y si block_size está cerca de SIZE_MAX esa suma da la vuelta. Es el desbordamiento sin signo mordiéndonos otra vez, esta vez atrapado a propósito.
Corrimiento de la base: el búfer de quien llama puede no empezar en una dirección alineada, así que base se redondea hacia arriba y los bytes iniciales se pierden. Eso es offset, y por eso base y storage pueden diferir.
Cálculo de la capacidad: usable / stride, descartando el resto. Entre el corrimiento y el truncamiento, la capacidad suele ser menor que storage_size / block_size, y por eso existe memory_pool_capacity() en vez de que quien llama la calcule. Si uno alinea su propio almacenamiento, con alignas en el arreglo puesto al menos tan grande como el block_align que pasa, el corrimiento no cuesta nada. Si se deja al azar, se puede perder un bloque en silencio.

Funciones de reserva y liberación

Ahora que inicializamos el pool de memoria podemos empezar a usarlo. A memory_pool_alloc() hay que pasarle el parámetro memory_pool_t *mp:

// modules/memory_pool/memory_pool.c
void *memory_pool_alloc(memory_pool_t *mp) {
  if (mp == NULL || mp->free_head == NULL) {
    return NULL;
  }

  void *p = mp->free_head;
  mp->free_head = read_next(p);
  mp->used++;
  if (mp->used > mp->high_water) {
    mp->high_water = mp->used;
  }
  return p;
}

Hacemos nuestra verificación estándar de que mp no sea NULL, y junto a ella verificamos mp->free_head. Esa segunda es la forma en que un pool agotado se anuncia: que la lista de libres esté vacía es que la cabeza sea NULL, así que no hace falta un helper is_empty aparte como sí lo necesitaba el búfer circular. Devolver NULL aquí también coincide con malloc(), así que quien ya maneja una reserva fallida no tiene que aprender una convención nueva. Si ambas verificaciones pasan, creamos un puntero nuevo p y lo apuntamos a mp->free_head. Ese es el bloque que estamos por devolverle a quien llama, y antes de soltarlo llamamos a read_next(p) para sacar el enlace de sus primeros bytes, que es lo que pasa a ser la nueva cabeza. Lo último que hacemos es contabilidad: mp->used++ registra que hay un bloque más entregado, y si eso empuja used por encima de mp->high_water subimos el pico con él. Esa comparación es el único lugar donde high_water cambia.

Sigue memory_pool_free():

// modules/memory_pool/memory_pool.c
bool memory_pool_free(memory_pool_t *mp, void *block) {
  if (!memory_pool_owns(mp, block)) {
    return false;
  }
  if (mp->used == 0u) {
    return false;
  }

  write_next(block, mp->free_head);
  mp->free_head = block;
  mp->used--;
  return true;
}

Devolver un bloque es la imagen espejo. La primera verificación le pasa el puntero a memory_pool_owns(), tema de la siguiente sección, que responde si esto es realmente el inicio de un bloque de este pool. La segunda, mp->used == 0u, rechaza una liberación en un pool que no tiene nada pendiente. Ambas se ejecutan antes de escribir nada, así que una liberación rechazada deja el pool completamente intacto, lista de libres incluida. El orden de esas dos tampoco es intercambiable, ya que mp->used dereferencia mp y solo es seguro porque memory_pool_owns() ya rechazó un pool nulo. Si se invierten para fallar primero en la verificación más barata, lo que se escribió es una dereferencia nula.

Después empujamos. write_next(block, mp->free_head) escribe la cabeza actual dentro del bloque devuelto, mp->free_head = block hace de ese bloque la nueva cabeza, y mp->used-- baja la cuenta. Este es el comportamiento de pila del que hablábamos antes: el bloque que se acaba de devolver es el que va a entregar el siguiente memory_pool_alloc().

Hay un caso que estas verificaciones no pueden atrapar: liberar el mismo bloque dos veces. Volveremos a eso después de la implementación.

El pool es dueño de la dirección de memoria

// modules/memory_pool/memory_pool.c
bool memory_pool_owns(const memory_pool_t *mp, const void *p) {
  if (mp == NULL || p == NULL) {
    return false;
  }

  uintptr_t addr = (uintptr_t)p;
  uintptr_t base = (uintptr_t)mp->base;
  uintptr_t end = base + ((uintptr_t)mp->capacity * (uintptr_t)mp->block_size);

  if (addr < base || addr >= end){
    return false;
  }
  return (addr - base) % (uintptr_t)mp->block_size == 0u;
}

Esta es la validación en la que se apoya memory_pool_free(), y hace dos preguntas. La primera es si el puntero está dentro de la zona del pool siquiera, comparándolo contra base y end.

La segunda es la interesante: (addr - base) % mp->block_size == 0u verifica que el puntero esté exactamente en un límite de bloque. Un puntero al medio de un bloque pasa la prueba de rango pero no es un bloque, y liberarlo insertaría un nodo falso en la lista de libres a un desplazamiento, así que la siguiente reserva entregaría un bloque que se solapa con su vecino. Esta operación módulo es la única división de todo el módulo, y es el mismo costo que evitamos en el búfer circular. Hacer que el stride sea potencia de dos la vuelve a convertir en una máscara.

Función de capacidad

Conocer la capacidad es importante porque a partir de ella podemos identificar cuánto del pool de memoria tenemos para entregar.

// modules/memory_pool/memory_pool.c
size_t memory_pool_capacity(const memory_pool_t *mp) {
  return (mp == NULL) ? 0u : mp->capacity;
}

Hacemos nuestra verificación de NULL sobre mp. Si es nulo devolvemos 0u, de lo contrario devolvemos la capacidad derivada allá en memory_pool_init().

Funciones auxiliares

Estas son las funciones para acceder a los miembros de memory_pool_t sin modificarlos. Empezamos con memory_pool_used():

// modules/memory_pool/memory_pool.c
size_t memory_pool_used(const memory_pool_t *mp) {
  return (mp == NULL) ? 0u : mp->used;
}

Aquí solo verificamos que el mp pasado como argumento no sea NULL, y si no lo es devolvemos el campo que pedimos, en este caso mp->used.

// modules/memory_pool/memory_pool.c
size_t memory_pool_available(const memory_pool_t *mp) {
  return (mp == NULL) ? 0u : mp->capacity - mp->used;
}

size_t memory_pool_high_water(const memory_pool_t *mp) {
  return (mp == NULL) ? 0u : mp->high_water;
}

Aquí está el resto de las funciones auxiliares, siguiendo la misma verificación de NULL y devolviendo el valor que pedimos. Nótese que memory_pool_available() calcula capacity - used en lugar de recorrer la lista de libres para contar lo que queda, que es la misma respuesta sin el recorrido.

Ejemplo de uso

Ahora que explicamos la implementación completa, veamos cómo vamos a usar el patrón.

typedef struct {
  uint32_t timestamp;
  int16_t value;
  uint8_t sensor_id;
} sample_t;

static alignas(void *) uint8_t sample_storage[16 * sizeof(sample_t)];
static memory_pool_t sample_pool;
static sample_t *current;

bool sensor_init(void) {
  return memory_pool_init(&sample_pool, sample_storage, sizeof sample_storage,
                          sizeof(sample_t), _Alignof(sample_t));
}

bool sensor_take_reading(uint8_t sensor_id) {
  current = memory_pool_alloc(&sample_pool);
  if (current == NULL) {
    return false;
  }

  current->timestamp = now();
  current->value = read_adc(sensor_id);
  current->sensor_id = sensor_id;
  return true;
}

void sensor_flush(void) {
  if (current == NULL) {
    return;
  }

  transmit(current);
  memory_pool_free(&sample_pool, current);
  current = NULL;
}

Este ejemplo muestra que vamos a usar el pool de memoria para guardar sample_t, que está compuesto por timestamp, value y sensor_id. Nótese que el bloque se reserva en una función y se libera en otra. Ese es el punto del pool: la memoria sobrevive a la llamada que la pidió, que es lo que permite que una lectura se quede ahí hasta que algo más esté listo para ocuparse de ella. Un solo espacio mantiene corto el ejemplo; un llamador real tiene varios a la vez.

Ahora el alignas(void *) sobre sample_storage. A init le pasamos _Alignof(sample_t), pero init lo sube a _Alignof(void *), porque todo bloque libre tiene que poder guardar un puntero. El almacenamiento tiene que satisfacer al mayor de los dos, y aquí ese es void *: en un host de 64 bits son 8 contra los 4 de sample_t, y en un objetivo de 32 bits los dos son iguales, así que alinear al puntero cubre ambos casos. Si uno se equivoca, base se corre hacia adelante y se pierde un bloque en silencio. Nótese que declaramos sample_storage como uint8_t, así que el arreglo son bytes crudos y podemos dimensionarlo multiplicando la cantidad de bloques por sizeof(sample_t). Ojo que alignas necesita <stdalign.h> en C11, y el fragmento omite los includes.

Nótese también que el pool no tiene idea de a qué sensor pertenece un bloque. sensor_id es un campo que pusimos nosotros en el struct, no algo que el pool registre. Lo único que supo siempre fue el tamaño de bloque y la alineación que le entregamos en init.

Nótese que alloc, free, y la forma en que usamos la memoria entre medio tienen la misma forma que malloc() y free(). Pedir memoria, verificar NULL, usarla, devolverla. Eso es deliberado: el código escrito contra el heap se porta cambiando dos puntos de llamada. Dos diferencias que conviene conocer: memory_pool_free() devuelve un bool en lugar de nada, y liberar el mismo bloque dos veces no se comporta como lo haría el asignador del heap. Vamos a eso ahora.

Caso límite: doble liberación

Allá en memory_pool_free() dijimos que había un caso que las verificaciones no pueden atrapar. Liberar en un pool vacío lo rechaza mp->used == 0u, y un puntero que no es el inicio de un bloque lo rechaza memory_pool_owns(). Pero liberar un bloque que ya está en la lista de libres pasa ambas. Es un inicio de bloque legítimo, así que owns dice que sí, y hay otros bloques pendientes, así que used no es cero.

Así que el empuje se ejecuta. Escribimos free_head dentro del bloque y luego hacemos de ese bloque la nueva cabeza. Si ese bloque ya era la cabeza, ahora se apunta a sí mismo.

Antes:
  free_head -> [B] -> [C] -> NULL

memory_pool_free(mp, B) por segunda vez:
  write_next(B, free_head) el next de B ahora apunta a B
  free_head = B

Después:
  free_head -> [B] -> [B] -> [B] -> ...

  alloc() devuelve B
  alloc() devuelve B otra vez, a otro llamador

Nada reporta esto. memory_pool_free() devuelve true, used se ve plausible, y toda consulta dice que el pool está sano. Uno lo encuentra después, en el código que tuvo la mala suerte de ser el segundo dueño del bloque.

Hay formas de atraparlo, y ambas cuestan algo por lo cual elegimos este patrón. Podríamos recorrer la lista de libres en cada liberación y rechazar un bloque que ya esté en ella, lo cual es correcto y convierte una liberación de tiempo constante en un recorrido. Podríamos mantener un mapa de bits aparte con los bloques reservados, lo cual cuesta memoria y renuncia a la propiedad de cero sobrecarga que motivó la lista intrusiva en primer lugar. Para una base de código de firmware pequeña, donde los puntos de reserva son pocos y revisables, documentarlo es una decisión defendible, y la limitación está escrita en el header justo al lado de la función que no puede atraparla. Para una base de código más grande valdría la pena pagar una verificación en la compilación de depuración.

Cierre

Eso es un pool de memoria completo. No hace reserva dinámica, entrega bloques y los recupera en tiempo constante sin búsquedas, no lleva ni un byte de sobrecarga por bloque, no puede fragmentarse por construcción, y después dice cuánto de él hacía falta realmente.

Los sacrificios, todos deliberados:

Un solo tamaño por pool. Cuatro tipos de objeto significan cuatro pools. Esto es lo que compra la ausencia de fragmentación, y hace que el pool sea mala opción para datos de tamaño genuinamente variable.
No es thread-safe ni ISR-safe. A diferencia del búfer circular, aquí no hay un camino sin bloqueos. Toda llamada que muta toca free_head, y no hay forma de repartir eso entre dos contextos como sí se reparten head y tail. Un pool compartido necesita una sección crítica alrededor de cada llamada que muta, que es también la razón por la que no hay ningún volatile en memory_pool_t.
Los bloques no se ponen en cero. Estas son semánticas de malloc, no de calloc. Un bloque recién entregado tiene un puntero viejo de la lista de libres en sus primeros bytes y lo que haya dejado el dueño anterior en el resto.
La doble liberación solo es parcialmente detectable. Cubierto arriba, y la limitación más importante del módulo.
La capacidad se deriva, no se da. El redondeo del stride, el corrimiento por alineación y el resto de la cola le comen espacio. Hay que leerla de vuelta con memory_pool_capacity().

Dos patrones y ya empezaron a apoyarse uno en el otro. El búfer circular nos dio almacenamiento fijo para bytes, el pool nos da almacenamiento fijo para objetos, y la cola de eventos, más adelante en la serie, va a querer los dos: un anillo de punteros a bloques entregados por un pool. Así se consigue una cola de structs sin una sola llamada a malloc.

Lo que sigue en la serie es la máquina de estados. El búfer circular y el pool trataron con almacenamiento, bytes en uno y bloques en el otro, y a ninguno le importaba qué significaba nada de eso. La máquina de estados es donde empieza a significar algo.

Patrones embebidos comunes: búfer circular

Ilean Monterrubio Jr — Fri, 31 Jul 2026 00:00:00 +0000

Esta es la primera parte de una nueva serie donde vuelvo a explorar los patrones embebidos más comunes, empezando por el búfer circular (ring buffer). Es uno de esos patrones que se usan en la comunicación serial para asegurarnos de no perder ni una trama de datos, y además es un bloque de construcción para otros patrones que veremos más adelante.

Concepto básico

El búfer circular usa dos índices, head y tail. Para agregar datos hacemos put de un byte en head e incrementamos head en uno. Para quitar datos hacemos get de un byte en tail e incrementamos tail en uno. Ambos índices solo avanzan hacia adelante: tail persigue a head por todo el búfer.

Este patrón se puede implementar con una lista enlazada o con un arreglo (array) de longitud fija. La lista enlazada suena tentadora, pero en un sistema embebido no quieres asignación dinámica de memoria. En una computadora moderna con gigabytes de memoria, llamar a malloc no es problema. En un microcontrolador tienes kilobytes, y tres problemas más grandes: el heap se fragmenta en un dispositivo que funciona durante meses, el tiempo que tarda una asignación no es determinista, y muchas veces necesitas agregar datos desde dentro de una interrupción, donde no te puedes dar el lujo de ninguna de las dos cosas. Un arreglo fijo evita todo eso, porque el espacio queda garantizado en tiempo de compilación.

Ese espacio garantizado es justo lo que le da tiempo al consumidor: los bytes que llegan más rápido de lo que los puedes procesar se quedan seguros en el búfer hasta que llegues a ellos, en lugar de perderse.

Dar la vuelta dentro del arreglo

Un arreglo no da la vuelta. Cuando llegas al final e intentas pasarte, no regresa al inicio. Te sales del espacio asignado, lo que puede provocar un fallo de segmentación, devolverte un puntero NULL o entregarte basura.

La intuición

La forma intuitiva de regresar al inicio es el operador módulo %, que devuelve el residuo de una división.

Array of length/capacity: 10

Formula: index % capacity -> array index

- index 0: 0 % 10 = 0
- index 1: 1 % 10 = 1
- index 4: 4 % 10 = 4
- index 10: 10 % 10 = 0
- index 11: 11 % 10 = 1

El módulo nos deja tratar el arreglo fijo como un anillo, lo que lo hace ideal para un búfer circular. Funciona bien en una computadora moderna con varios núcleos, frecuencias altas y una unidad de división por hardware. Pero el módulo tiene una desventaja: requiere división, y muchos microcontroladores no tienen división por hardware. El compilador la emula por software, que es lento, y pagamos ese costo con cada byte que pasa por el búfer.

Optimizando con una máscara de bits

Hay una forma más rápida de hacer exactamente lo mismo que el operador módulo, con una restricción: la longitud del arreglo debe ser una potencia de dos. Esa restricción es la llave que nos permite recrear el módulo con una sola operación a nivel de bits. La fórmula es index = head & mask, donde mask = capacity - 1. Repasemos las matemáticas.

Array of length/capacity: 8 (power of two)

mask = 8 - 1 = 7 = 0b0111

- index 0: 0b0000 & 0b0111 = 0
- index 1: 0b0001 & 0b0111 = 1
- index 2: 0b0010 & 0b0111 = 2
- index 8: 0b1000 & 0b0111 = 0
- index 10: 0b1010 & 0b0111 = 2
- index 14: 0b1110 & 0b0111 = 6

Fíjate que son las mismas respuestas que daría el módulo: 8 % 8 = 0, 10 % 8 = 2, 14 % 8 = 6. No es coincidencia. La máscara 0b0111 conserva solo los tres bits más bajos y limpia todo lo que está arriba, y los tres bits más bajos de cualquier número son exactamente ese número módulo 8. Quedarte con los bits bajos es sacar el residuo. Como la capacidad es potencia de dos, capacity - 1 es una secuencia limpia de unos, y eso es lo que hace que el AND coincida perfectamente con el módulo. Intenta esto con un número que no sea potencia de dos y se cae todo: 11 & 9 = 9, pero 11 % 10 = 1.

Implementación

La estructura del búfer circular

Creamos un struct para mantener juntos todos los datos. Esto nos facilita la vida, porque con un solo puntero a la estructura podemos acceder a buffer, capacity, mask, head y tail. También hace que los datos sean fáciles de pasar por puntero a cualquier función que necesite agregar o leer de él.

// modules/ring_buffer/ring_buffer.h
typedef struct {
  uint8_t *buffer;
  size_t capacity;
  size_t mask;
  volatile size_t head;
  volatile size_t tail;
} ring_buffer_t;

Como puedes ver, el struct usa varios tipos distintos, y cada uno es deliberado.

uint8_t: el búfer guarda bytes crudos. Sea cual sea la fuente, datos seriales de UART, I2C o cualquier otra cosa, llegan como octetos, así que un arreglo de bytes es el almacenamiento natural para la cola.
size_t: capacity, mask, head y tail son todos size_t. Es un tipo sin signo del tamaño de la plataforma (normalmente un alias de unsigned int o unsigned long), lo que mantiene la aritmética de índices portable entre compiladores y evita problemas de desbordamiento con signo. Que sea sin signo importa más adelante, cuando dependemos de que head - tail dé la vuelta limpiamente.
volatile: head y tail están marcados como volatile para que el compilador siempre los lea de memoria en lugar de guardarse una copia vieja en un registro. El productor y el consumidor pueden ejecutarse en contextos distintos (por ejemplo, una ISR llenando el búfer mientras el bucle principal lo vacía), así que un valor guardado en un registro podría perderse la actualización del otro lado. Ojo: volatile solo garantiza que la lectura ocurra, no hace que el acceso sea atómico ni seguro entre hilos. Veremos por qué este diseño es seguro de todos modos en la sección sobre interrupciones.

Las funciones de inicialización y de potencia de dos

Empecemos con init y su ayudante is_power_of_two. La función init prepara la estructura de datos, y la verificación de potencia de dos es el primer filtro: si quien la llama pide una capacidad que no es potencia de dos, la rechazamos, porque todo el esquema de enmascarado depende de eso. Arranquemos con el ayudante.

// modules/ring_buffer/ring_buffer.c
static bool is_power_of_two(size_t x) {
  return x != 0u && (x & (x - 1u)) == 0u;
}

Esta implementación hace lo siguiente:

x != 0u: verifica que x no sea 0.
(x & (x - 1u)) == 0u: esta es la parte que verifica que haya un solo bit encendido. Una potencia de dos tiene exactamente un bit encendido. Restarle uno apaga ese bit y enciende todos los que están debajo, así que x y x - 1 no comparten ningún bit y el AND da cero. Toma x = 8: 8 - 1 = 7, y 0b1000 & 0b0111 = 0. Ahora toma un número que no sea potencia de dos, x = 12: 12 - 1 = 11, y 0b1100 & 0b1011 = 0b1000, que no es cero. Ese bit que sobra delata que x tenía más de un bit encendido.

Si ambas condiciones se cumplen, entonces x es potencia de dos, así que la función devuelve true si y solo si x es potencia de dos. Ahora pasemos a la función ring_buffer_init.

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_init(ring_buffer_t *rb, uint8_t *storage, size_t capacity) {
  if (rb == NULL || storage == NULL || !is_power_of_two(capacity)) {
    return false;
  }

  rb->buffer = storage;
  rb->capacity = capacity;
  rb->mask = capacity - 1u;
  rb->head = 0u;
  rb->tail = 0u;
  return true;
}

init valida primero sus entradas: un puntero nulo al struct, un storage nulo, o una capacidad que no sea potencia de dos hacen que se salga y devuelva false. Una vez que pasan las verificaciones, arma el struct, precalcula mask = capacity - 1 para que put y get nunca tengan que recalcularlo, y pone ambos índices en cero.

Fíjate que init no asigna nada. Quien la llama nos entrega el arreglo storage, así que el búfer puede vivir en memoria estática o en la pila. Este es el principio de no usar malloc que mencionamos antes, hecho concreto: no hay ni un malloc a la vista, y el espacio quedó garantizado en el momento en que el llamador declaró el arreglo.

Las funciones put y get

Estas funciones ponen y sacan un solo byte a la vez. Las limitamos a un byte porque a veces un solo byte es todo lo que necesitamos, y porque las funciones write y read de la siguiente sección están construidas encima de ellas. Empecemos con ring_buffer_put:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_put(ring_buffer_t *rb, uint8_t byte) {
  if (rb == NULL || ring_buffer_is_full(rb)) {
    return false;
  }
  rb->buffer[rb->head & rb->mask] = byte;
  rb->head++;
  return true;
}

La función empieza validando que rb no sea NULL, y luego llama al ayudante ring_buffer_is_full. Si el búfer está lleno salimos temprano y devolvemos false, avisándole al llamador que no se guardó ningún byte. Veremos cómo funciona is_full en la siguiente sección. Si hay espacio, hacemos la escritura, y aquí es donde rinde frutos la sección anterior: rb->head & rb->mask calcula el índice del arreglo con el AND a nivel de bits, envolviendo el head de avance libre de regreso a una ranura válida. Escribimos el byte ahí, y luego incrementamos head en uno para que el siguiente put caiga en la ranura que sigue. Fíjate en el orden: primero escribimos la ranura, después avanzamos head. Ese orden importa para la seguridad con interrupciones, y llegaremos a eso más adelante. Ahora veamos ring_buffer_get:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_get(ring_buffer_t *rb, uint8_t *out) {
  if (rb == NULL || out == NULL || ring_buffer_is_empty(rb)) {
    return false;
  }
  *out = rb->buffer[rb->tail & rb->mask];
  rb->tail++;
  return true;
}

Esta función también empieza validando que rb no sea NULL, y luego verifica que out tampoco lo sea. Ese es el puntero donde se guarda el byte que leemos, que es la forma en que get le devuelve datos al llamador dejando libre su valor de retorno bool para reportar éxito o fracaso. Por último llama al ayudante ring_buffer_is_empty. Si el búfer está vacío salimos temprano y devolvemos false, avisándole al llamador que no se leyó ningún byte. Veremos cómo funciona is_empty en la siguiente sección. Si no está vacío, hacemos la lectura, y otra vez la sección anterior rinde frutos: rb->tail & rb->mask calcula el índice del arreglo con el AND a nivel de bits, envolviendo el tail de avance libre en una ranura válida. Leemos el byte e incrementamos tail en uno. Fíjate que get nunca borra nada. Lee el byte y mueve tail hacia adelante, y esa ranura cuenta como libre en el momento en que tail pasa por encima de ella. Los índices por sí solos deciden qué son datos y qué es espacio libre.

Las funciones is_empty, is_full y count

Estos tres ayudantes, is_empty, is_full y count, son en los que se apoyan put y get para decidir si pueden seguir adelante. Aquí es donde los índices de avance libre por fin se ganan su lugar. Empecemos con ring_buffer_is_empty:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_is_empty(const ring_buffer_t *rb) {
  return rb->head == rb->tail;
}

El búfer está vacío cuando head y tail tienen el mismo valor. Tiene sentido: tail persigue a head, y cuando lo alcanza por completo ya no queda nada por leer. Aquí está la parte sutil. En muchos diseños de búfer circular los índices se envuelven de regreso al rango válido, y entonces head == tail es ambiguo, porque significa tanto completamente vacío como completamente lleno, y no puedes distinguir cuál. Como nuestros índices avanzan libres y nunca se envuelven, head == tail solo puede significar vacío. En un momento veremos cómo se maneja el caso lleno sin esa ambigüedad.

Sigue ring_buffer_count, que es el corazón de todo esto:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_count(const ring_buffer_t *rb) {
  return rb->head - rb->tail;
}

Ambos índices solo aumentan. Cada put incrementa head, cada get incrementa tail, y ninguno se envuelve. Así que head siempre va adelante de tail por exactamente la cantidad de bytes que se han escrito pero todavía no se han leído, que es el nivel de llenado. La diferencia head - tail es la cuenta.

Lo bonito es lo que pasa cuando head finalmente se desborda. size_t tiene un máximo, y después de suficientes bytes head lo rebasa y da la vuelta hacia cero. Podrías esperar que head - tail se rompa en ese punto, pero no pasa. La resta sin signo da la vuelta igual que la suma sin signo, así que la diferencia sigue siendo correcta incluso a través del desbordamiento. Justo por esto head y tail son sin signo, y por esto el búfer puede funcionar indefinidamente sin ningún manejo especial para el desbordamiento.

Por último, ring_buffer_is_full:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_is_full(const ring_buffer_t *rb) {
  return ring_buffer_count(rb) == rb->capacity;
}

Una vez que tenemos count, lo de lleno es trivial: el búfer está lleno cuando contiene capacity bytes. Sin desperdiciar una ranura, sin un contador aparte que mantener sincronizado, sin ambigüedad con el caso vacío. Los índices de avance libre nos dan vacío (head == tail), lleno (count == capacity) y todo lo que hay en medio, todo a partir de dos números que solo cuentan hacia arriba.

Las funciones write y read

Estas funciones escriben y leen más de un byte a la vez. Empecemos con ring_buffer_write:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_write(ring_buffer_t *rb, const uint8_t *data, size_t len) {
  if (rb == NULL || data == NULL) {
    return 0u;
  }
  size_t written = 0u;
  while (written < len && ring_buffer_put(rb, data[written])) {
    written++;
  }
  return written;
}

Esta función devuelve la cantidad de bytes que realmente se escribieron, que puede ser menor a la que se pidió. Devuelve 0 en la salida temprana, cuando el búfer circular rb o el puntero de origen data son NULL. Si no, inicializamos written para llevar la cuenta de cuántos bytes hemos copiado de data al búfer. El ciclo se ejecuta con dos condiciones unidas por &&: written < len nos impide leer más allá del final de la entrada, y ring_buffer_put devuelve false en cuanto el búfer se llena. Mientras ambas se cumplan, seguimos copiando bytes e incrementando written. El ciclo se detiene en cuanto una de las dos falla, ya sea porque se nos acabó la entrada o porque se nos acabó el espacio. La cuenta que devolvemos le dice al llamador exactamente cuánto entró: todo, una parte, o cero si el búfer ya estaba lleno.

Sigue ring_buffer_read:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_read(ring_buffer_t *rb, uint8_t *out, size_t len) {
  if (rb == NULL || out == NULL) {
    return 0u;
  }
  size_t count = 0u;
  while (count < len && ring_buffer_get(rb, &out[count])) {
    count++;
  }
  return count;
}

Esta función también devuelve la cantidad de bytes que realmente se leyeron, que puede ser menor a la que se pidió. Devuelve 0 en la salida temprana, cuando el búfer circular rb o el puntero de destino out son NULL. Si no, inicializamos count para llevar la cuenta de cuántos bytes hemos leído del búfer hacia out. El ciclo se ejecuta con dos condiciones unidas por &&: count < len nos impide escribir más allá del final de la salida, y ring_buffer_get devuelve false en cuanto el búfer se vacía. Mientras ambas se cumplan, seguimos leyendo bytes e incrementando count. El ciclo se detiene en cuanto una de las dos falla, ya sea porque el búfer del llamador se llenó o porque el búfer circular se quedó seco. La cuenta que devolvemos le dice al llamador exactamente cuántos bytes recibió.

Seguridad con la rutina de servicio de interrupción (ISR)

Para quienes van empezando en embebidos, puede que no sea obvio por qué se considera seguro este diseño, ni cuáles son sus aplicaciones típicas. El uso principal de un búfer circular, como mencionamos antes, es la comunicación serial. Toma el ejemplo de dos microcontroladores hablando entre sí, cada uno ejecutando su propio firmware hecho a la medida de su tarea. No sabemos cuándo va a necesitar enviar datos ninguno de los dos, así que para asegurarnos de no perder un solo byte, montamos la ruta de recepción de datos (RX) usando la rutina de servicio de interrupción (Interrupt Service Routine, ISR) del microcontrolador. En cuanto llega el inicio de una transmisión, la ISR toma el control y captura cada byte.

Este es el lado productor del búfer. La ISR llama a put por cada byte que recibe. En otro lado, el bucle principal es el consumidor, llamando a get cuando tiene chance de procesar lo que llegó. Los dos se ejecutan en contextos distintos, y aquí está el detalle: la ISR puede dispararse en cualquier momento, entre cualesquiera dos instrucciones que esté ejecutando el bucle principal. Así que la pregunta justa es: si la interrupción cae a la mitad de un get, ¿pueden pisarse entre sí y corromper el búfer?

La respuesta es no, y la razón es que cada índice tiene exactamente un escritor. put es la única función que escribe head, y solo se ejecuta en la ISR. get es la única función que escribe tail, y solo se ejecuta en el bucle principal. Ninguno de los dos lados escribe el índice del otro. El productor lee tail para saber si el búfer está lleno, y el consumidor lee head para saber si está vacío, pero leer es seguro. Como ningún índice tiene dos escritores compitiendo por cambiarlo, no hay nada que corromper, y no necesitamos deshabilitar interrupciones ni recurrir a un candado. A esto se refiere la gente cuando habla de un solo productor y un solo consumidor, o SPSC por sus siglas en inglés.

Esa regla de un solo escritor también es el límite. En el momento en que tengas dos cosas llamando a put, o dos cosas llamando a get, la garantía se acaba y necesitas sincronización de verdad. Este búfer es seguro para exactamente un productor y un consumidor, ni uno más.

Hay un detalle más que lo hace funcionar, y es el orden que señalamos allá en put:

rb->buffer[rb->head & rb->mask] = byte; // 1. write the data
rb->head++; // 2. then publish it

Primero escribimos el byte en la ranura, y después incrementamos head. Ese orden no es accidente. head es la señal que le dice al consumidor que hay un byte nuevo disponible. Si incrementáramos head primero y el tiempo de la interrupción se acomodara mal, el consumidor podría ver el nuevo head, ir a leer esa ranura y sacar un byte que en realidad todavía no habíamos escrito. Al escribir la ranura antes de avanzar head, garantizamos que en el instante en que el consumidor puede ver el byte, el byte de verdad ya está ahí. La actualización del índice publica los datos, así que va al final. get hace el espejo: primero leemos el byte y después avanzamos tail, así nunca marcamos una ranura como libre antes de habernos llevado su contenido.

Un par de advertencias honestas para quien las quiera. Primero, volatile nos da visibilidad, no atomicidad. Este diseño asume que leer o escribir head y tail sucede en una sola operación de máquina ininterrumpible, lo cual es cierto cuando son del tamaño de palabra en el objetivo. En un MCU de 8 bits, donde size_t abarca varios bytes, la actualización de un índice podría partirse en varias instrucciones y quedar rota por una interrupción, y tendrías que tomarlo en cuenta. Segundo, en un microcontrolador de un solo núcleo con una ISR, volatile más el orden de escribir y luego publicar es suficiente. En un sistema multinúcleo con ordenamiento de memoria débil recurrirías a operaciones atómicas con semántica explícita de adquisición y liberación, para garantizar que la escritura de la ranura se vea antes que la del índice. Para el caso clásico de ISR y bucle principal, que es para el que está hecho este búfer, estamos en terreno firme.

Cierre

Eso es un búfer circular completo y funcional en un par de cientos de líneas de C. No hace asignación dinámica, da la vuelta con un solo AND a nivel de bits en lugar de una división, distingue lleno de vacío sin desperdiciar una ranura ni llevar un contador aparte, y es seguro llenarlo desde una interrupción mientras lo vaciamos desde el bucle principal. Para una estructura tan pequeña, trae metida una cantidad sorprendente de sutilezas.

Vale la pena ser honesto sobre lo que este diseño no hace, porque cada una de estas cosas es un intercambio deliberado, no un descuido:

La capacidad debe ser potencia de dos. Este es el precio de cambiar el módulo por una máscara. Si necesitas guardar exactamente 100 bytes, redondeas a 128 y desperdicias un poco de espacio. En un sistema embebido casi siempre es un intercambio que conviene.
Solo un productor y un consumidor. Un escritor por índice es lo que lo hace libre de candados. Dos ISR escribiendo, o dos contextos leyendo, y necesitas sincronización de verdad.
No hay modo de sobrescribir lo más viejo. Cuando el búfer está lleno, put rechaza el byte nuevo en lugar de descartar el más viejo. Algunas aplicaciones quieren lo contrario, conservar las muestras más recientes y tirar las viejas. Esa es una variante razonable, solo que no es esta.
Solo bytes. Este búfer guarda uint8_t. Guardar elementos más anchos, o structs arbitrarios, implica generalizar el tamaño del elemento, lo que cambia la aritmética de índices y el almacenamiento.

Ninguna de estas limitaciones es difícil de levantar. Son las preguntas que salen naturalmente, y varias de ellas se convierten en sus propios patrones más adelante en esta serie.

Y hablando de eso, el búfer circular es un cimiento, no un destino. Aparece por debajo de varios de los patrones que faltan: una cola de eventos es un búfer circular de mensajes en lugar de bytes, un filtro de promedio móvil es un búfer circular de muestras, y el despachador de comandos que construiremos lee su entrada directamente de uno. Lo que sigue en la serie es el pool de memoria. El búfer circular nos dio almacenamiento fijo para bytes; el pool de memoria nos da almacenamiento fijo para objetos, y es lo que permite que una cola de eventos guarde structs en lugar de datos crudos. Nos vemos ahí.

Common Embedded Patterns: Ring Buffer

Ilean Monterrubio Jr — Fri, 31 Jul 2026 00:00:00 +0000

This is the first part of a new series where I'll re-explore common embedded patterns, starting with the ring buffer. It's one of those patterns used in serial communication to make sure no frame of data is lost, and it's also a building block for other patterns we'll cover later.

Basic Concept

The ring buffer uses two indices, head and tail. To add data we put a byte at head and increment head by one. To remove data we get a byte from tail and increment tail by one. Both indices only move forward, the tail chases the head around the buffer.

This pattern can be implemented with a linked list or a fixed-length array. A linked list might be tempting, but on an embedded system you don't want dynamic allocation. On a modern computer with gigabytes of memory, calling malloc is a non-issue. On a microcontroller you have kilobytes, and three bigger problems: the heap fragments over a device that runs for months, allocation timing is non-deterministic, and you often need to add data from inside an interrupt where you can't afford either. A fixed array sidesteps all of it, the space is guaranteed at compile time.

That guaranteed space is what buys the consumer time: bytes arriving faster than you can process them sit safely in the buffer until you get to them, instead of being lost.

Wrapping around the array

An array does not loop. When you reach the end and try to go past it, it doesn't wrap around. You run beyond the allocated space, which can cause a segmentation fault, return a NULL pointer, or hand you garbage data.

Intuition

The intuitive way to loop back around is the modulo operator %, which returns the remainder after division.

Array of length/capacity: 10

Formula: index % capacity -> array index

- index 0: 0 % 10 = 0
- index 1: 1 % 10 = 1
- index 4: 4 % 10 = 4
- index 10: 10 % 10 = 0
- index 11: 11 % 10 = 1

Modulo lets us treat the fixed array as a ring, which makes it a great fit for a ring buffer. It works fine on a modern computer with multiple cores, high clock speeds, and a hardware divide unit. But modulo has a drawback. It requires division, and many microcontrollers have no hardware divide. The compiler emulates it in software, which is slow, and we pay that cost on every byte we move through the buffer.

Optimizing with a bitmask

There's a faster way to do exactly what the modulo operator does, with one restriction: the array length must be a power of two. That restriction is the key that lets us recreate modulo with a single bitwise operation. The formula is index = head & mask, where mask = capacity - 1. Let's walk through the math.

Array of length/capacity: 8 (power of two)

mask = 8 - 1 = 7 = 0b0111

- index 0: 0b0000 & 0b0111 = 0
- index 1: 0b0001 & 0b0111 = 1
- index 2: 0b0010 & 0b0111 = 2
- index 8: 0b1000 & 0b0111 = 0
- index 10: 0b1010 & 0b0111 = 2
- index 14: 0b1110 & 0b0111 = 6

Notice these are the same answers modulo would give: 8 % 8 = 0, 10 % 8 = 2, 14 % 8 = 6. That's not a coincidence. The mask 0b0111 keeps only the lowest three bits and clears everything above, and the lowest three bits of any number are exactly that number modulo 8. Keeping the low bits is taking the remainder. Because the capacity is a power of two, capacity - 1 is a clean run of ones, which is what makes the AND line up perfectly with modulo. Try this with a non power of two and it falls apart: 11 & 9 = 9, but 11 % 10 = 1.

Implementation

Ring buffer structure

We create a struct to keep all the data types together. This makes life easy, because with a single pointer to the data structure we can access: buffer, capacity, mask, head, and tail. It also makes the data easy to pass by pointer for any function that needs to add and read from it.

// modules/ring_buffer/ring_buffer.h
typedef struct {
  uint8_t *buffer;
  size_t capacity;
  size_t mask;
  volatile size_t head;
  volatile size_t tail;
} ring_buffer_t;

As you can see the struct uses a few different types, and each one is deliberate.

uint8_t: the buffer stores raw bytes. Whatever the source is, serial data from UART, I2C, or anything else, it arrives as octets, so a byte array is the natural storage for the queue.
size_t: capacity, mask, head, and tail are all size_t. It's an unsigned type sized to the platform (usually an alias for unsigned int or unsigned long), which keeps the index math portable across compilers and avoids signed-overflow issues. The unsignedness matters later, when we rely on head - tail wrapping cleanly.
volatile: head and tail are marked volatile so the compiler always reads them from memory instead of caching a stale copy in a register. The producer and consumer can run in different execution contexts (for example, an ISR filling the buffer while the main loop drains it), so a value cached in a register could miss the other side's update. Note that volatile only guarantees the read happens, it does not make the access atomic or thread-safe. We'll cover why this design is safe anyway in the section on interrupts.

Initialization and power of two functions

Let's start with init and its helper is_power_of_two. The init function sets up the data structure, and the power-of-two check is the first gate: if the caller asks for a capacity that isn't a power of two, we refuse, because the whole masking scheme depends on it. We'll start with the helper.

// modules/ring_buffer/ring_buffer.c
static bool is_power_of_two(size_t x) {
  return x != 0u && (x & (x - 1u)) == 0u;
}

This implementation does the following:

x != 0u: checks if x is not 0.
(x & (x - 1u)) == 0u: this is the part that checks for a single set bit. A power of two has exactly one bit set. Subtracting one flips that bit off and turns every bit below it on, so x and x - 1 share no bits and the AND comes out zero. Take x = 8: 8 - 1 = 7, and 0b1000 & 0b0111 = 0. Now take a number that isn't a power of two, x = 12: 12 - 1 = 11, and 0b1100 & 0b1011 = 0b1000, which is not zero. The leftover bit is the tell that x had more than one bit set. If both conditions are true then x is a power of two, so the function returns true if and only if x is a power of two. Now let's turn to the ring_buffer_init function.

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_init(ring_buffer_t *rb, uint8_t *storage, size_t capacity) {
  if (rb == NULL || storage == NULL || !is_power_of_two(capacity)) {
    return false;
  }

  rb->buffer = storage;
  rb->capacity = capacity;
  rb->mask = capacity - 1u;
  rb->head = 0u;
  rb->tail = 0u;
  return true;
}

init validates its inputs first: a null struct pointer, null storage, or a capacity that isn't a power of two all cause it to bail out and return false. Once the checks pass, it wires up the struct, precomputes mask = capacity - 1 so put and get never have to recompute it, and zeroes both indices.

Notice init doesn't allocate anything. The caller hands us the storage array, so the buffer can live in static or stack memory. This is the no-malloc principle from earlier, made concrete: there's no malloc in sight, and the space was guaranteed the moment the caller declared the array.

Put and get functions

These functions put and get a single byte at a time. We scope them to one byte because sometimes a single byte is all we need, and because the next section's write and read functions are built on top of them. Let's start with ring_buffer_put:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_put(ring_buffer_t *rb, uint8_t byte) {
  if (rb == NULL || ring_buffer_is_full(rb)) {
    return false;
  }
  rb->buffer[rb->head & rb->mask] = byte;
  rb->head++;
  return true;
}

The function starts by validating that rb isn't NULL, then calls the helper ring_buffer_is_full. If the buffer is full we exit early and return false, telling the caller no byte was stored. We'll see how is_full works in the next section. If there's room, we do the actual write, and this is where the previous section pays off: rb->head & rb->mask computes the array index using the bitwise AND, wrapping the free-running head back into a valid slot. We write the byte there, then increment head by one so the next put lands in the following slot. Notice the order: we write the slot first, then advance head. That ordering matters for interrupt safety, which we'll get to later. Now let's take a look at ring_buffer_get:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_get(ring_buffer_t *rb, uint8_t *out) {
  if (rb == NULL || out == NULL || ring_buffer_is_empty(rb)) {
    return false;
  }
  *out = rb->buffer[rb->tail & rb->mask];
  rb->tail++;
  return true;
}

The function also starts by validating that rb isn't NULL, then checks that out isn't NULL. This is the pointer where the byte we read gets stored, which is how get hands data back to the caller while keeping its bool return free to report success or failure. Finally it calls the helper ring_buffer_is_empty. If the buffer is empty we exit early and return false, telling the caller no byte was read. We'll see how is_empty works in the next section. If it's not empty, we do the read, and again the previous section pays off: rb->tail & rb->mask computes the array index with the bitwise AND, wrapping the free-running tail into a valid slot. We read the byte, then increment tail by one. Notice get never erases anything. It reads the byte and moves tail forward, and that slot counts as free again the moment tail passes it. The indices alone decide what's data and what's free space.

Is empty, is full, and count

These three helpers, is_empty, is_full, and count, are what put and get lean on to decide whether they can proceed. This is where the free-running indices finally earn their keep. Let's start with ring_buffer_is_empty:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_is_empty(const ring_buffer_t *rb) {
  return rb->head == rb->tail;
}

The buffer is empty when head and tail hold the same value. That makes sense: tail chases head, and when it catches all the way up there's nothing left to read. Here's the subtle part. In a lot of ring buffer designs the indices get wrapped back into range, and then head == tail is ambiguous, it means both completely empty and completely full, and you can't tell which. Because our indices run free and never wrap, head == tail can only ever mean empty. We'll see in a moment how full is handled without that ambiguity.

Next, ring_buffer_count, which is the heart of it:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_count(const ring_buffer_t *rb) {
  return rb->head - rb->tail;
}

Both indices only ever increase. Every put bumps head, every get bumps tail, and neither wraps. So head is always ahead of tail by exactly the number of bytes that have been written but not yet read, which is the fill level. The difference head - tail is the count.

The nice part is what happens when head eventually overflows. size_t has a maximum, and after enough bytes head wraps past it back toward zero. You might expect head - tail to break at that point, but it doesn't. Unsigned subtraction wraps the same way unsigned addition does, so the difference stays correct even across the overflow. This is exactly why head and tail are unsigned, and it's why the buffer can run indefinitely without any special handling for the wraparound.

Finally, ring_buffer_is_full:

// modules/ring_buffer/ring_buffer.c
bool ring_buffer_is_full(const ring_buffer_t *rb) {
  return ring_buffer_count(rb) == rb->capacity;
}

Once we have count, full is trivial: the buffer is full when it holds capacity bytes. No wasted slot, no separate counter to keep in sync, no ambiguity with the empty case. The free-running indices give us empty (head == tail), full (count == capacity), and everything in between, all from two numbers that only count upward.

Write and read functions

These functions write and read more than a single byte of data at a time. Let's start with ring_buffer_write:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_write(ring_buffer_t *rb, const uint8_t *data, size_t len) {
  if (rb == NULL || data == NULL) {
    return 0u;
  }
  size_t written = 0u;
  while (written < len && ring_buffer_put(rb, data[written])) {
    written++;
  }
  return written;
}

This function returns the number of bytes actually written, which may be fewer than requested. It returns 0 on the early exit when either the ring buffer rb or the source pointer data is NULL. Otherwise we initialize written to track how many bytes we've copied from data into the buffer. The loop runs on two conditions joined by &&: written < len keeps us from reading past the end of the input, and ring_buffer_put returns false the moment the buffer is full. As long as both hold, we keep copying bytes and incrementing written. The loop stops as soon as either one fails, whether we ran out of input or ran out of room. The count we return tells the caller exactly how much made it in: all of it, part of it, or zero if the buffer was already full.

Next, ring_buffer_read:

// modules/ring_buffer/ring_buffer.c
size_t ring_buffer_read(ring_buffer_t *rb, uint8_t *out, size_t len) {
  if (rb == NULL || out == NULL) {
    return 0u;
  }
  size_t count = 0u;
  while (count < len && ring_buffer_get(rb, &out[count])) {
    count++;
  }
  return count;
}

This function also returns the number of bytes actually read, which may be fewer than requested. It returns 0 on the early exit when either the ring buffer rb or the destination pointer out is NULL. Otherwise we initialize count to track how many bytes we've read from the buffer into out. The loop runs on two conditions joined by &&: count < len keeps us from writing past the end of the output, and ring_buffer_get returns false the moment the buffer is empty. As long as both hold, we keep reading bytes and incrementing count. The loop stops as soon as either one fails, whether the caller's buffer is full or the ring buffer ran dry. The count we return tells the caller exactly how many bytes they got.

Safety with the Interrupt Service Routine (ISR)

For those new to embedded, it might not be obvious why this design is considered safe, or what its typical applications are. The primary use for a ring buffer, as we mentioned earlier, is serial communication. Take the example of two microcontrollers talking to each other, each running its own firmware tailored to its own task. We don't know when either one will need to send data, so to make sure we don't miss a single byte, we set up the data receive (RX) path using the microcontroller's Interrupt Service Routine (ISR). As soon as the start of a transmission arrives, the ISR takes over and captures each byte.

This is the producer side of the buffer. The ISR calls put for every byte it receives. Somewhere else, the main loop is the consumer, calling get when it gets around to processing what came in. The two run in different execution contexts, and here's the catch: the ISR can fire at any moment, between any two instructions the main loop is running. So the fair question is, if the interrupt lands in the middle of a get, can the two step on each other and corrupt the buffer?

The answer is no, and the reason is that each index has exactly one writer. put is the only function that writes head, and it only ever runs in the ISR. get is the only function that writes tail, and it only ever runs in the main loop. Neither side writes the other's index. The producer reads tail to check whether the buffer is full, and the consumer reads head to check whether it's empty, but reading is safe. Since no index has two writers racing to change it, there's nothing to corrupt, and we don't need to disable interrupts or reach for a lock. This is what people mean by single-producer, single-consumer, or SPSC.

That single-writer rule is also the boundary. The moment you have two things calling put, or two things calling get, the guarantee is gone and you need real synchronization. This buffer is safe for exactly one producer and one consumer, no more.

One more detail makes it work, and it's the ordering we flagged back in put:

rb->buffer[rb->head & rb->mask] = byte; // 1. write the data
rb->head++; // 2. then publish it

We write the byte into the slot first, then increment head. That order is not an accident. head is the signal that tells the consumer a new byte is available. If we bumped head first and the interrupt timing worked out badly, the consumer could see the new head, go read that slot, and pull out a byte we hadn't actually written yet. By writing the slot before advancing head, we guarantee that the instant the consumer can see the byte, the byte is really there. The index update publishes the data, so it comes last. get mirrors this: we read the byte out first, then advance tail, so we never mark a slot free before we've taken its contents.

A couple of honest caveats for the readers who want them. First, volatile gets us visibility, not atomicity. This design assumes reading or writing head and tail happens in a single, uninterruptible machine operation, which is true when they're word-sized on the target. On an 8-bit MCU where size_t spans multiple bytes, an index update could be split across instructions and torn by an interrupt, and you'd need to account for that. Second, on a single-core microcontroller with an ISR, volatile plus the write-then-publish ordering is enough. On a multi-core system with weak memory ordering you'd reach for atomics with explicit acquire and release semantics to guarantee the slot write is seen before the index write. For the classic ISR-and-main-loop case this buffer is built for, we're on solid ground.

Wrap-up

That's a complete, working ring buffer in a couple hundred lines of C. It does no dynamic allocation, wraps with a single bitwise AND instead of a division, tells full from empty without wasting a slot or keeping a separate counter, and it's safe to fill from an interrupt while draining it from the main loop. For a structure this small, there's a surprising amount of nuance packed in.

It's worth being honest about what this design does not do, because every one of these is a deliberate trade, not an oversight:

Capacity must be a power of two. This is the price of replacing modulo with a mask. If you need to hold exactly 100 bytes you round up to 128 and waste a little space. On an embedded system that's almost always a trade worth making.
Single producer, single consumer only. One writer per index is what makes it lock-free. Two ISRs writing, or two contexts reading, and you need real synchronization.
No overwrite-oldest mode. When the buffer is full, put refuses the new byte rather than discarding the oldest one. Some applications want the opposite (keep the newest samples, drop the stale ones). That's a reasonable variant, just not this one.
Bytes only. This buffer stores uint8_t. Storing wider elements, or arbitrary structs, means generalizing the element size, which changes the index math and the storage. None of these are hard to lift. They're the natural next questions, and a few of them turn into their own patterns later in this series.

Speaking of which, the ring buffer is a foundation, not a destination. It shows up underneath several of the patterns still to come: an event queue is a ring buffer of messages instead of bytes, a moving-average filter is a ring buffer of samples, and the command dispatcher we'll build reads its input straight out of one. Next in the series we'll tackle the memory pool. The ring buffer gave us fixed storage for bytes; the memory pool gives us fixed storage for objects, and it's what lets an event queue hold structs instead of raw data. See you there.

Compendium: Reproducible Developer Environments in One Config

Ilean Monterrubio Jr — Mon, 18 May 2026 00:00:00 +0000

Why I Built It

Earlier this year I kept coming back to a project that had been on the back burner for a while. The original idea was an IDE with a built-in way to configure development environments, but the more I researched, the clearer it got that I was looking at a multi-year build. Not wanting to wait that long to ship something useful, I narrowed in on the feature I cared about most: the ability to configure and set up a development environment easily, without the IDE wrapped around it.

Throughout my career, setting up toolchains and development environments has always been a painful experience: embedded cross-compilers that only build cleanly on the maintainer's exact OS version, READMEs that promise five minutes and take three days. I've also spent weeks building containers to wall off the development environment, only to watch the image balloon every time another tool got added. The documentation goes stale almost as fast as it gets written, because the tools moved on and nobody updated it.

Why C and C++ First

For Compendium's first iteration I wanted to focus on the language where the setup pain runs deepest: C and C++. Every scripting language already has a version manager that works well enough. nvm handles Node, pyenv handles Python, asdf and mise cover most of the rest. None of them seriously handle GCC, clang, or arm-none-eabi-gcc. Embedded toolchains in particular are where I lose the most time, between USB drivers, OpenOCD configs, and compiler versions that have to match the linker script the project was tested against. Starting there meant solving the hardest case first. Adding Go, Python, and Node on top of that architecture turned out to be the easy part.

v0.1.1 Ships Today

v0.1.1 ships today. The CLI is a single Go binary, the config is a single TOML file, and everything installs under ~/.local/compendium/ without sudo. Rather than recap the docs here, I'll point you at them: compendium.ilean.me has the quick start, the full tool list, the config reference, and per-language guides for C/C++, Go, Python, Node, and embedded.

Tech Stack

CLI : Go (single static binary, no runtime dependencies)
Configuration : TOML
Registry : JSON manifests, hosted on GitHub
Platforms : macOS (Apple Silicon, Intel), Linux (x86_64, arm64)
License : GPL v3 (CLI), CC0 (registry)

Roadmap

v0.2 broadens C/C++ build system support to Autotools, adds Java and Rust, completes the embedded cross-compiler set with Xtensa for ESP32, and wires up the custom git hook runner. v0.3 introduces a Compendium-native C/C++ package manager. The full roadmap lives in the docs. If you want to follow along, contribute, or request a tool for the registry, GitHub issues and discussions are open.

Project Links

Compendium: entornos de desarrollo reproducibles en una sola configuración

Ilean Monterrubio Jr — Mon, 18 May 2026 00:00:00 +0000

Por qué lo construí

A principios de este año seguía volviendo a un proyecto que llevaba un buen rato en pausa. La idea original era un IDE con una forma integrada de configurar entornos de desarrollo, pero entre más investigaba, más claro me quedaba que estaba frente a un desarrollo de varios años. Como no quería esperar tanto para lanzar algo útil, me enfoqué en la funcionalidad que más me importaba: poder configurar y preparar un entorno de desarrollo con facilidad, sin el IDE alrededor.

A lo largo de mi carrera, configurar toolchains y entornos de desarrollo siempre ha sido una experiencia dolorosa: compiladores cruzados de embebidos que solo compilan limpiamente en la versión exacta del sistema operativo del mantenedor, READMEs que prometen cinco minutos y toman tres días. También he pasado semanas construyendo contenedores para aislar el entorno de desarrollo, solo para ver cómo la imagen se inflaba cada vez que se agregaba otra herramienta. La documentación queda obsoleta casi tan rápido como se escribe, porque las herramientas avanzaron y nadie la actualizó.

Por qué primero C y C++

Para la primera iteración de Compendium quise enfocarme en el lenguaje donde el dolor de la configuración es más profundo: C y C++. Todos los lenguajes de scripting ya tienen un gestor de versiones que funciona lo suficientemente bien. nvm maneja Node, pyenv maneja Python, asdf y mise cubren casi todo lo demás. Ninguno de ellos maneja en serio GCC, clang o arm-none-eabi-gcc. Los toolchains de embebidos en particular son donde más tiempo pierdo, entre drivers USB, configuraciones de OpenOCD y versiones de compilador que tienen que coincidir con el linker script contra el que se probó el proyecto. Empezar ahí significaba resolver primero el caso más difícil. Agregar Go, Python y Node sobre esa arquitectura resultó ser la parte fácil.

La v0.1.1 se lanza hoy

La v0.1.1 se lanza hoy. La CLI es un único binario de Go, la configuración es un único archivo TOML y todo se instala en ~/.local/compendium/ sin sudo. En lugar de repetir la documentación aquí, te dirijo a ella: compendium.ilean.me tiene la guía de inicio rápido, la lista completa de herramientas, la referencia de configuración y guías por lenguaje para C/C++, Go, Python, Node y embebidos.

Stack tecnológico

CLI : Go (un único binario estático, sin dependencias en tiempo de ejecución)
Configuración : TOML
Registro : manifiestos JSON, alojados en GitHub
Plataformas : macOS (Apple Silicon, Intel), Linux (x86_64, arm64)
Licencia : GPL v3 (CLI), CC0 (registro)

Hoja de ruta

La v0.2 amplía el soporte de sistemas de build de C/C++ a Autotools, agrega Java y Rust, completa el conjunto de compiladores cruzados para embebidos con Xtensa para el ESP32 y conecta el ejecutor de git hooks personalizados. La v0.3 introduce un gestor de paquetes de C/C++ nativo de Compendium. La hoja de ruta completa vive en la documentación. Si quieres seguir el avance, contribuir o solicitar una herramienta para el registro, los issues y las discusiones de GitHub están abiertos.

Enlaces del proyecto

How I Built a Low-Friction Blog Pipeline

Ilean Monterrubio Jr — Mon, 27 Apr 2026 00:00:00 +0000

Why Build a Pipeline?

I wanted to grow my online presence, a dedicated corner of the internet to showcase my projects and skills, point people to my GitHub, LinkedIn, and socials, and share my thoughts on things I was building or learning. Simple enough goal. The execution, though, turned out to be a learning process.

My first attempt at blogging was manual and messy. Write a post, publish it somewhere, copy it somewhere else, and hope people find it. I had set up the Dev.to RSS feed fetching early on, but that was about it. There was no real visibility into whether anyone was reading, and no reason to keep going. Unsurprisingly, I took a year-long gap between posts, not because I stopped having things to say, but because the friction was too high and life got in the way. When I started a new job, I focused on learning my new responsibilities and let the blog quietly go dormant.

When I came back to it, I wanted to do things differently. The goal was simple: write once, publish everywhere, no copy-pasting across platforms, no manual distribution, and some way to know if the work was actually reaching anyone. The RSS feed was already there but the imports were messy. The frontmatter in my blog posts didn't match the RSS schema, so every import came in inconsistent and making changes or adding new frontmatter fields meant manually fixing every post. What I did this time was get my Astro frontmatter to match the RSS schema properly, so imports were clean and uniform from the start. Now it was about connecting the remaining pieces into a proper pipeline.

The Stack

Astro Before launching my personal site, I had tried to build it with Next.js a year earlier. I didn't fully understand it at the time and kept running into hydration issues. At a local Code and Coffee meetup, I asked one of the attendees for advice and he pointed me to Astro. Within days of going through a tutorial, I had my site live for the first time. I paired it with Tailwind CSS to make theming easy to maintain and update down the road.

Pexels Every post needs a cover image. Pexels is my go-to for finding images, royalty-free stock photos and videos shared by creators. High quality, free to use, and no licensing headaches.

Dev.to This came much later in the process. After some digging I discovered that Astro can generate an rss.xml feed if set up correctly, and Dev.to can periodically pull from that feed to automatically import new posts. All I need to do is keep my frontmatter in sync with what Dev.to expects from the feed, no manual copying.

Umami I wanted visibility into who was actually reading. After some research I landed on Umami: privacy-friendly, no cookie banners, and a free hobby tier that covers up to 3 websites.

Mastodon After Twitter was acquired I decided to leave and delete my profile. Mastodon turned out to be a great fit, especially for the tech community, and the fediverse has a different energy that I appreciate.

LinkedIn Where I manually share each post to take advantage of how LinkedIn's algorithm circulates content to your network and extended network for a few days after publishing.

Setting Up Astro

Each blog post is written in Markdown format, which Astro handles exceptionally well out of the box. One of the keys to making everything work smoothly is Astro's content collections configuration, this is how you tell Astro the shape of your content so it can validate and query it consistently. For this project I have Markdown files for blog entries and JSON files to define my projects. The Astro content collections documentation is worth reading carefully to understand how to define your schema.

Before looking at the frontmatter, it helps to see the schema that enforces it. This lives in src/content.config.ts and uses Astro's content collections with Zod validation. If a frontmatter field is missing or the wrong type, Astro will throw an error at build time rather than silently generating a broken RSS feed:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    author: z.string(),
    image: z.string(),
    categories: z.array(z.string()),
  }),
});

export const collections = { blog };

Each blog post starts with a frontmatter block that drives everything downstream, from the RSS feed to Dev.to imports:

---
title: "Building a Terminal Text Editor: The View (Part 3)"
description: "In Part 3 of building wordNebula, I cover the View layer, why I chose FTXUI over ncurses..."
pubDate: 2026-04-05
author: "Ilean Monterrubio Jr"
image: '/src/content/images/pexels-markus-winkler-1430818-4065400.jpg'
categories:
  - 'cpp'
  - 'terminal'
  - 'architecture'
  - 'programming'
---

Keeping this frontmatter consistent and aligned with the RSS schema is what makes the rest of the pipeline work without any manual cleanup. This also makes the rss.xml.ts configuration straightforward to set up. All it needs to do is read the frontmatter content and it will generate the rss.xml file at build time.

Here is what a basic rss.xml.ts file looks like:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'Your Blog Name',
    description: 'Your blog description',
    site: context.site,
    items: posts.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      author: post.data.author,
      categories: post.data.categories,
      link: `/blog/${post.id}/`,
    })),
  });
}

The fields in the items map directly to the frontmatter fields you define. As long as the frontmatter is consistent, the RSS output will be clean and Dev.to will be able to import it without any issues. For additional information visit the Astro RSS documentation.

Auto-Importing to Dev.to via RSS

For this part you will need a Dev.to account. Once your website is live and the RSS feed URL is active, navigate to your Dev.to dashboard. On the left-hand sidebar you will find RSS Import Feeds.

From there, click + Add a Feed Source to expand the form. Enter your rss.xml URL in the RSS Feed URL field. A couple of settings worth paying attention to:

Mark the RSS source as canonical URL by default: keep this checked. This is one of the most important settings in the whole pipeline. It tells Dev.to that your personal site is the original source of the content, which means search engines will credit your site and not the Dev.to version. Get this wrong and Dev.to can end up outranking your own site for your own writing. Always leave this on.
Replace self-referential links with DEV Community-specific links: leave this unchecked unless you are migrating your entire blog to Dev.to permanently.

Once you click Add Feed Source , Dev.to will periodically check your feed and pull in any new posts. Imported posts land as drafts , so before publishing you will want to review each one and add a series name if it is part of a multi-part post, pick tags that match popular Dev.to tags for discoverability (for example: cpp, terminal, architecture, programming), and add a cover image sourced from Pexels. When you are ready to go live, open the post editor and flip published to true in the Dev.to frontmatter at the top of the post.

Mastodon Verification and Author Attribution

I wanted to establish a presence on Mastodon, and it turns out Astro makes it easy to connect your blog to the fediverse with just two small additions.

Verification with rel="me"

Mastodon uses the rel="me" link standard to verify that you own a website. Adding it to your Astro layout head tag gives you the green checkmark on your Mastodon profile:

<link rel="me" href="https://mastodon.social/@yourusername" />

Author Attribution with fediverse:creator

The fediverse:creator meta tag is a newer addition that connects your blog posts to your Mastodon identity. When someone shares one of your posts on Mastodon, it automatically credits your account:

<meta name="fediverse:creator" content="@yourusername@mastodon.social" />

Add this to your blog post layout so it only appears on post pages rather than every page on the site. Together these two tags make your blog a proper fediverse citizen, verified, attributable, and discoverable by the tech community that has made Mastodon their home.

Adding Privacy-Friendly Analytics with Umami

When I started getting posts out I wanted to know if anyone was actually reading them. Google Analytics was the obvious choice but it felt like overkill, heavy, cookie-dependent, and requiring a consent banner just to get started. After some digging I found Umami, a lightweight privacy-friendly alternative that ticked every box. The free hobby tier covers up to 3 websites, 100K events per month, and 6 months of data retention. No cookies, no consent banners, no tracking across sites.

Setup is straightforward. Once you create your Umami account and add your site, you get a script tag to drop into your Astro layout file:

<script
  defer
  src="https://cloud.umami.is/script.js"
  data-website-id="your-website-id">
</script>

Add this to your main Layout.astro file and it will be included on every page automatically. I also added a small notice in the footer to let visitors know the site uses privacy-friendly analytics with no cookies or personal data collected, a small but honest touch that sets the right expectations.

The Umami dashboard covers all the basics: visitors, page views, referrers, locations, devices, and bounce rate. It is everything you need to understand how your content is performing without compromising your readers' privacy.

The Publishing Workflow

I typically write about something I worked on professionally, a personal project, or a topic I consider myself an expert in. Here is the end-to-end process I follow from idea to published post:

1. Write the draft in Notion I started out using Google Docs but since returning to the blog I migrated to Notion. It handles code blocks and tables properly and exports to Markdown in a way that actually translates correctly, which makes the next step much smoother.

2. Generate the Astro-ready Markdown file with frontmatter Once the draft is ready I convert it into a Markdown file with the correct frontmatter fields — title, description, pubDate, author, image, and categories — making sure everything aligns with the RSS schema.

3. Deploy to ilean.me on Sunday morning Sunday is my publishing day. I push the new post and deploy the site.

4. Dev.to picks up via RSS Dev.to periodically polls the RSS feed URL, so the post will appear as a draft in my Dev.to dashboard within a few hours depending on when it last checked.

5. Post on Mastodon the same day I share the post on Mastodon with hashtags, typically the same ones used in the post frontmatter for consistency.

6. Schedule LinkedIn for Monday morning LinkedIn has a post scheduling feature which has been a game changer. I schedule it to go live Monday morning at 8-9 AM, when recruiters and professionals are most active, letting LinkedIn's algorithm circulate it to my network and extended network over the following days.

7. Review and publish the Dev.to draft Once it lands in Dev.to I review it, add a series name if it is part of a multi-part post, set the tags, add a cover image from Pexels, and flip published to true.

Results So Far

I revived the blog in February and March of 2026. On Dev.to, in February the most views I received in a single day was 16. Since then that number has climbed to 36 views in a single day. As of April 25th 2026 Dev.to shows 435 total views, though down 24% compared to the previous 7 days, a good reminder that consistency matters.

On ilean.me, Umami shows 48 unique visitors so far. What surprised me was the geographic spread. A large portion of visitors are coming from Asia, which makes sense given that embedded systems and C++ are a common stack there. The majority are from the US, with California showing up frequently, which tracks given the tech industry concentration there.

The numbers are small but the trend is encouraging. Search engine traffic compounds over time; every post indexed is another entry point for someone to find your work. The goal was never overnight virality, it was to slowly and consistently build an online presence, and the data shows that is exactly what is happening.

What I'd Do Differently

A few honest lessons from getting this pipeline up and running.

Double check your publication dates. One post did not show up on Dev.to on time and after some digging I realized the date in the frontmatter was off by a day. Dev.to pulls from the RSS feed based on the pubDate field, so if that is wrong the post gets skipped or delayed. Always verify the date before deploying.

Be patient with the RSS fetch timing. Dev.to does not poll your feed instantly. Depending on when it last checked, it could take several hours for a new post to appear as a draft. Do not panic and assume something is broken; just give it time.

Filter out your own visits. Early on I got excited seeing a visitor from Houston in Umami before realizing it was just me clicking my own links. The free Umami tier does not have a built-in way to exclude your own IP, so just keep that in mind when reading your early numbers and take them with a grain of salt.

Find your community. One thing I want to do going forward is find Houston based tech Discord servers with software engineers and developers to share my content in. Posting in relevant communities can accelerate growth in a way that passive RSS and social posts alone cannot.

Do not check analytics too often. It is tempting at the start but the numbers move slowly and checking constantly just creates unnecessary anxiety. Set a cadence, maybe once a week, and focus on writing the next post instead.

The whole point of building this pipeline was to remove friction, and it worked. There is no year-long gap waiting to happen again; there is just the next post.

Cómo construí un pipeline de blog sin fricciones

Ilean Monterrubio Jr — Mon, 27 Apr 2026 00:00:00 +0000

¿Por qué construir un pipeline?

Quería hacer crecer mi presencia en línea: un rincón propio de internet para mostrar mis proyectos y habilidades, dirigir a la gente a mi GitHub, LinkedIn y redes sociales, y compartir mis ideas sobre lo que estaba construyendo o aprendiendo. Un objetivo bastante sencillo. La ejecución, sin embargo, resultó ser todo un proceso de aprendizaje.

Mi primer intento de bloguear fue manual y desordenado. Escribir una entrada, publicarla en algún lado, copiarla a otro y esperar que la gente la encontrara. Había configurado la obtención del feed RSS de Dev.to desde el principio, pero hasta ahí llegaba. No había una visibilidad real de si alguien estaba leyendo, ni una razón para seguir. Como era de esperarse, dejé pasar un año entero entre entradas, no porque dejara de tener cosas que decir, sino porque la fricción era demasiado alta y la vida se atravesó. Cuando empecé un nuevo trabajo, me concentré en aprender mis nuevas responsabilidades y dejé que el blog quedara en silencio.

Cuando volví a retomarlo, quería hacer las cosas de otra manera. El objetivo era simple: escribir una vez, publicar en todas partes, sin copiar y pegar entre plataformas, sin distribución manual, y con alguna forma de saber si el trabajo realmente llegaba a alguien. El feed RSS ya estaba ahí, pero las importaciones eran un desorden. El frontmatter de mis entradas no coincidía con el esquema del RSS, así que cada importación llegaba inconsistente, y hacer cambios o agregar nuevos campos al frontmatter significaba corregir cada entrada a mano. Esta vez lo que hice fue lograr que el frontmatter de Astro coincidiera correctamente con el esquema del RSS, para que las importaciones fueran limpias y uniformes desde el inicio. Ahora se trataba de conectar las piezas restantes en un pipeline en forma.

El stack

Astro Antes de lanzar mi sitio personal, había intentado construirlo con Next.js un año antes. En ese momento no lo entendía del todo y me topaba constantemente con problemas de hidratación. En un meetup local de Code and Coffee le pedí consejo a uno de los asistentes y me recomendó Astro. A los pocos días de seguir un tutorial, tenía mi sitio en vivo por primera vez. Lo combiné con Tailwind CSS para que el manejo de temas fuera fácil de mantener y actualizar más adelante.

Pexels Cada entrada necesita una imagen de portada. Pexels es mi opción de cabecera para encontrar imágenes: fotos y videos de stock libres de regalías compartidos por creadores. De alta calidad, gratis y sin dolores de cabeza por licencias.

Dev.to Esto llegó mucho después en el proceso. Tras investigar un poco, descubrí que Astro puede generar un feed rss.xml si se configura correctamente, y que Dev.to puede consultar ese feed de forma periódica para importar automáticamente las nuevas entradas. Lo único que tengo que hacer es mantener mi frontmatter en sincronía con lo que Dev.to espera del feed, sin copiar nada a mano.

Umami Quería tener visibilidad de quién estaba leyendo realmente. Después de investigar, me decidí por Umami: respetuoso con la privacidad, sin banners de cookies y con un plan gratuito para aficionados que cubre hasta 3 sitios web.

Mastodon Después de que adquirieran Twitter, decidí irme y eliminar mi perfil. Mastodon resultó encajar muy bien, sobre todo para la comunidad tech, y el fediverso tiene una energía distinta que aprecio.

LinkedIn Donde comparto manualmente cada entrada para aprovechar cómo el algoritmo de LinkedIn hace circular el contenido por tu red y tu red extendida durante unos días después de publicar.

Configurando Astro

Cada entrada del blog está escrita en formato Markdown, que Astro maneja excepcionalmente bien desde el inicio. Una de las claves para que todo funcione sin problemas es la configuración de las content collections de Astro; así es como le dices a Astro la forma de tu contenido para que pueda validarlo y consultarlo de manera consistente. Para este proyecto tengo archivos Markdown para las entradas del blog y archivos JSON para definir mis proyectos. Vale la pena leer con atención la documentación de content collections de Astro para entender cómo definir tu esquema.

Antes de ver el frontmatter, ayuda conocer el esquema que lo hace cumplir. Vive en src/content.config.ts y usa las content collections de Astro con validación de Zod. Si falta un campo del frontmatter o es del tipo incorrecto, Astro lanzará un error en tiempo de compilación en lugar de generar en silencio un feed RSS roto:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    author: z.string(),
    image: z.string(),
    categories: z.array(z.string()),
  }),
});

export const collections = { blog };

Cada entrada del blog comienza con un bloque de frontmatter que impulsa todo lo que viene después, desde el feed RSS hasta las importaciones a Dev.to:

---
title: "Building a Terminal Text Editor: The View (Part 3)"
description: "In Part 3 of building wordNebula, I cover the View layer, why I chose FTXUI over ncurses..."
pubDate: 2026-04-05
author: "Ilean Monterrubio Jr"
image: '/src/content/images/pexels-markus-winkler-1430818-4065400.jpg'
categories:
  - 'cpp'
  - 'terminal'
  - 'architecture'
  - 'programming'
---

Mantener este frontmatter consistente y alineado con el esquema del RSS es lo que hace que el resto del pipeline funcione sin ninguna limpieza manual. Esto también hace que la configuración de rss.xml.ts sea sencilla de armar. Lo único que necesita hacer es leer el contenido del frontmatter y generará el archivo rss.xml en tiempo de compilación.

Así se ve un archivo rss.xml.ts básico:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'Your Blog Name',
    description: 'Your blog description',
    site: context.site,
    items: posts.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      author: post.data.author,
      categories: post.data.categories,
      link: `/blog/${post.id}/`,
    })),
  });
}

Los campos del items se corresponden directamente con los campos del frontmatter que definas. Mientras el frontmatter sea consistente, la salida del RSS será limpia y Dev.to podrá importarlo sin ningún problema. Para más información, visita la documentación de RSS de Astro.

Importación automática a Dev.to vía RSS

Para esta parte necesitarás una cuenta de Dev.to. Una vez que tu sitio web esté en vivo y la URL del feed RSS esté activa, ve a tu panel de Dev.to. En la barra lateral izquierda encontrarás RSS Import Feeds.

Desde ahí, haz clic en + Add a Feed Source para desplegar el formulario. Ingresa la URL de tu rss.xml en el campo RSS Feed URL. Un par de ajustes a los que vale la pena prestar atención:

Mark the RSS source as canonical URL by default: déjalo activado. Este es uno de los ajustes más importantes de todo el pipeline. Le indica a Dev.to que tu sitio personal es la fuente original del contenido, lo que significa que los motores de búsqueda darán crédito a tu sitio y no a la versión de Dev.to. Si te equivocas en esto, Dev.to puede terminar posicionándose por encima de tu propio sitio con tus propios textos. Déjalo siempre activado.
Replace self-referential links with DEV Community-specific links: déjalo desactivado, a menos que estés migrando todo tu blog a Dev.to de forma permanente.

Una vez que hagas clic en Add Feed Source , Dev.to revisará tu feed periódicamente e importará cualquier entrada nueva. Las entradas importadas llegan como borradores , así que antes de publicar conviene revisar cada una y agregar un nombre de serie si forma parte de una entrada de varias partes, elegir etiquetas que coincidan con las etiquetas populares de Dev.to para que sea más fácil de descubrir (por ejemplo: cpp, terminal, architecture, programming) y agregar una imagen de portada tomada de Pexels. Cuando estés listo para publicar, abre el editor de la entrada y cambia published a true en el frontmatter de Dev.to al inicio de la entrada.

Verificación con Mastodon y atribución de autoría

Quería establecer una presencia en Mastodon, y resulta que Astro facilita conectar tu blog al fediverso con solo dos pequeñas adiciones.

Verificación con rel="me"

Mastodon usa el estándar de enlace rel="me" para verificar que eres dueño de un sitio web. Agregarlo a la etiqueta head de tu layout de Astro te da la palomita verde en tu perfil de Mastodon:

<link rel="me" href="https://mastodon.social/@yourusername" />

Atribución de autoría con fediverse:creator

La meta etiqueta fediverse:creator es una adición más reciente que conecta las entradas de tu blog con tu identidad de Mastodon. Cuando alguien comparte una de tus entradas en Mastodon, le da crédito a tu cuenta automáticamente:

<meta name="fediverse:creator" content="@yourusername@mastodon.social" />

Agrégalo al layout de tus entradas para que solo aparezca en las páginas de las entradas y no en todas las páginas del sitio. Juntas, estas dos etiquetas convierten a tu blog en un ciudadano del fediverso en forma: verificado, atribuible y fácil de descubrir por la comunidad tech que ha hecho de Mastodon su hogar.

Agregando analíticas respetuosas con la privacidad con Umami

Cuando empecé a sacar entradas, quería saber si alguien las estaba leyendo de verdad. Google Analytics era la opción obvia, pero se sentía excesivo: pesado, dependiente de cookies y que requería un banner de consentimiento solo para empezar. Tras investigar un poco encontré Umami, una alternativa ligera y respetuosa con la privacidad que cumplía con todo. El plan gratuito para aficionados cubre hasta 3 sitios web, 100 mil eventos al mes y 6 meses de retención de datos. Sin cookies, sin banners de consentimiento, sin rastreo entre sitios.

La configuración es sencilla. Una vez que creas tu cuenta de Umami y agregas tu sitio, obtienes una etiqueta de script para colocar en el archivo de layout de Astro:

<script
  defer
  src="https://cloud.umami.is/script.js"
  data-website-id="your-website-id">
</script>

Agrégalo a tu archivo principal Layout.astro y se incluirá automáticamente en cada página. También agregué un pequeño aviso en el pie de página para que los visitantes sepan que el sitio usa analíticas respetuosas con la privacidad, sin cookies ni recolección de datos personales; un detalle pequeño pero honesto que establece las expectativas correctas.

El panel de Umami cubre todo lo básico: visitantes, vistas de página, referencias, ubicaciones, dispositivos y tasa de rebote. Es todo lo que necesitas para entender cómo está funcionando tu contenido sin comprometer la privacidad de tus lectores.

El flujo de publicación

Normalmente escribo sobre algo en lo que trabajé profesionalmente, un proyecto personal o un tema en el que me considero experto. Este es el proceso de principio a fin que sigo desde la idea hasta la entrada publicada:

1. Escribir el borrador en Notion Empecé usando Google Docs, pero desde que retomé el blog me migré a Notion. Maneja bien los bloques de código y las tablas, y exporta a Markdown de una forma que realmente se traduce correctamente, lo que hace que el siguiente paso sea mucho más fluido.

2. Generar el archivo Markdown listo para Astro con frontmatter Una vez que el borrador está listo, lo convierto en un archivo Markdown con los campos de frontmatter correctos —title, description, pubDate, author, image y categories— asegurándome de que todo se alinee con el esquema del RSS.

3. Desplegar en ilean.me el domingo por la mañana El domingo es mi día de publicación. Subo la nueva entrada y despliego el sitio.

4. Dev.to la recoge vía RSS Dev.to consulta periódicamente la URL del feed RSS, así que la entrada aparecerá como borrador en mi panel de Dev.to en unas horas, dependiendo de cuándo revisó por última vez.

5. Publicar en Mastodon el mismo día Comparto la entrada en Mastodon con hashtags, normalmente los mismos que uso en el frontmatter de la entrada para mantener la consistencia.

6. Programar LinkedIn para el lunes por la mañana LinkedIn tiene una función para programar publicaciones que ha sido un cambio total. La programo para que salga el lunes por la mañana entre las 8 y 9 AM, cuando los reclutadores y profesionales están más activos, dejando que el algoritmo de LinkedIn la haga circular por mi red y mi red extendida durante los días siguientes.

7. Revisar y publicar el borrador de Dev.to Una vez que llega a Dev.to, lo reviso, agrego un nombre de serie si forma parte de una entrada de varias partes, configuro las etiquetas, agrego una imagen de portada de Pexels y cambio published a true.

Resultados hasta ahora

Reviví el blog en febrero y marzo de 2026. En Dev.to, en febrero la mayor cantidad de vistas que recibí en un solo día fue 16. Desde entonces ese número subió a 36 vistas en un solo día. Al 25 de abril de 2026, Dev.to muestra 435 vistas totales, aunque con una baja del 24 % respecto a los 7 días anteriores, un buen recordatorio de que la consistencia importa.

En ilean.me, Umami muestra 48 visitantes únicos hasta ahora. Lo que me sorprendió fue la distribución geográfica. Una buena parte de los visitantes viene de Asia, lo cual tiene sentido dado que los sistemas embebidos y C++ son un stack común allá. La mayoría viene de Estados Unidos, con California apareciendo con frecuencia, lo que cuadra dada la concentración de la industria tecnológica ahí.

Los números son pequeños, pero la tendencia es alentadora. El tráfico de los motores de búsqueda se acumula con el tiempo; cada entrada indexada es otro punto de entrada para que alguien encuentre tu trabajo. El objetivo nunca fue volverse viral de la noche a la mañana, sino construir una presencia en línea de forma lenta y constante, y los datos muestran que es exactamente lo que está pasando.

Qué haría diferente

Algunas lecciones honestas de poner este pipeline en marcha.

Verifica dos veces tus fechas de publicación. Una entrada no apareció a tiempo en Dev.to y, tras investigar un poco, me di cuenta de que la fecha en el frontmatter estaba desfasada por un día. Dev.to toma del feed RSS según el campo pubDate, así que si está mal, la entrada se omite o se retrasa. Verifica siempre la fecha antes de desplegar.

Ten paciencia con los tiempos de obtención del RSS. Dev.to no consulta tu feed al instante. Dependiendo de cuándo revisó por última vez, una entrada nueva puede tardar varias horas en aparecer como borrador. No entres en pánico ni asumas que algo está roto; solo dale tiempo.

Filtra tus propias visitas. Al principio me emocioné al ver un visitante de Houston en Umami, antes de darme cuenta de que era yo haciendo clic en mis propios enlaces. El plan gratuito de Umami no tiene una forma integrada de excluir tu propia IP, así que tenlo en cuenta al leer tus primeros números y tómalos con cautela.

Encuentra tu comunidad. Algo que quiero hacer de aquí en adelante es encontrar servidores de Discord tech de Houston con ingenieros de software y desarrolladores donde compartir mi contenido. Publicar en comunidades relevantes puede acelerar el crecimiento de una forma que el RSS pasivo y las publicaciones en redes por sí solos no pueden.

No revises las analíticas con demasiada frecuencia. Es tentador al principio, pero los números se mueven despacio y revisarlos constantemente solo genera ansiedad innecesaria. Establece una frecuencia, tal vez una vez por semana, y mejor concéntrate en escribir la siguiente entrada.

Todo el propósito de construir este pipeline era eliminar la fricción, y funcionó. Ya no hay un hueco de un año esperando a repetirse; solo está la siguiente entrada.

Building a Terminal Text Editor: The View (Part 3)

Ilean Monterrubio Jr — Mon, 06 Apr 2026 00:00:00 +0000

Recap

In Part 1, I talked about the origin of this project, the early architectural decisions, and why I picked the GapBuffer with IBuffer as the contract for all future buffer implementations. In Part 2, we got into the details of the Presenter, how it wires the components together, handles user input, manages state, and keeps the Model and View in sync. Now we can move on to the View.

What is the View?

The View is the component that the user interacts with directly. All user inputs are collected and passed to the Presenter, the View doesn't decide what to do with them. It is also responsible for rendering the text the user types, along with any warnings, statistics like word count, and whether the file is unsaved. The View doesn't calculate any of this, it just displays whatever the Presenter sends it. Another example of how all three parts of the Model-View-Presenter separate concerns.

Why FTXUI instead of ncurses

In the proof of concept testing, I used ncurses, the de facto standard library for building terminal interfaces. It worked well for the initial testing, and I see a lot of projects still using it; it's tried and true. While ncurses would have been a great choice, I did a bit more research and found FTXUI, a modern C++ library with components to build interactive terminal user interfaces. I wanted to leverage that it uses modern C++, matching the project's early defined specification of targeting C++20.

The IView Interface

While implementing the other components (Model and Presenter), I mocked up a thin interface for the View, IView. At first, it was only taking character input and not accounting for special characters, and it didn't handle rendering any data. The proof of concept View just took the input, sent it to the Presenter, which would send it to the buffer and log it so I could see the data was actually flowing through the system.

I was thinking of removing it, but after doing more research, I decided to expand the interface instead. Keeping IView as an abstract class means that if someone wants to write their own View for an OS that isn't supported by FTXUI, they can implement the interface and plug it in without touching the Presenter or Model.

class IView {
  public:
    virtual ~IView() = default;

    virtual void run(std::function<void(const InputEvent &)> onInput) = 0;
    virtual void render(const ViewState &state) = 0;
    virtual void exit() = 0;
    virtual std::pair<int, int> getTerminalSize() const = 0;
    virtual void showMessage(const std::string &message, bool isError = false) = 0;
};

A quick explanation, run() starts the event loop and takes a callback for handling input, this is what the Presenter calls in its main loop. render() takes the ViewState we saw in Part 2 and draws it to the screen. exit() and getTerminalSize() do what they say, and showMessage() is how the Presenter displays warnings like the "unsaved changes" prompt from the exit flow.

Rendering the UI

As we showed in Part 2, the ViewState struct defines the contract for how the Presenter sends data to the View:

struct ViewState {
    // Content
    std::string visibleText; // Text currently visible in viewport
    int cursorPosition; // Linear position of cursor in visibleText

    // Status bar information
    int wordCount; // Total word count (primary metric for writers)
    std::string filename; // Current file name (or "Untitled")
    bool isDirty; // Unsaved changes indicator

    // UI state
    std::string statusMessage; // Temporary status message (e.g., "Saved", "Error: ...")
    bool showHelp; // Whether to show help overlay
};

There are three major types of data in the ViewState contract: Content , which tells us the cursorPosition and the visibleText. Status bar information : wordCount, filename, and isDirty which indicates whether the file is unsaved. Finally, the UI state : statusMessage and showHelp.

One of the biggest challenges was how to deal with the cursor, how to move it, and be able to add more to the buffer when the cursor moves. One of the simplest solutions is to break the visibleText into three components: beforeCursor, cursor, and afterCursor.

ftxui::Element FtxuiView::renderEditor() {
    const auto &text = currentState.visibleText;
    const size_t pos = static_cast<size_t>(currentState.cursorPosition);

    auto before = ftxui::text(text.substr(0, pos));

    // Character at cursor with cyan background
    std::string cursorChar = pos < text.size() ? std::string(1, text[pos]) : " ";
    auto cursor = ftxui::text(cursorChar) | ftxui::bgcolor(ftxui::Color::Cyan) | ftxui::color(ftxui::Color::Black);

    auto after = pos + 1 < text.size() ? ftxui::text(text.substr(pos + 1)) : ftxui::text("");

    return ftxui::hbox({before, cursor, after});
}

The cursor is highlighted with a cyan background so the user can see where they are in the text. This challenge existed in both ncurses and FTXUI, neither library gives you a built-in cursor for a custom text editor. You have to simulate it yourself.

Translating Keyboard Input

The View is also responsible for translating raw keyboard events into the InputEvent structs that the Presenter understands. FTXUI has its own event system, so the View needs a translation layer between what FTXUI gives us and what our Presenter expects. The translateEvent() method handles this mapping:

InputEvent FtxuiView::translateEvent(const ftxui::Event &event) {
    if (event == ftxui::Event::ArrowLeft)
        return {InputEvent::Type::ARROW_LEFT};
    if (event == ftxui::Event::ArrowRight)
        return {InputEvent::Type::ARROW_RIGHT};
    if (event == ftxui::Event::Backspace)
        return {InputEvent::Type::BACKSPACE};
    if (event == ftxui::Event::Return)
        return {InputEvent::Type::ENTER};
    if (event == ftxui::Event::CtrlQ)
        return {InputEvent::Type::CTRL_Q};
    if (event == ftxui::Event::CtrlS)
        return {InputEvent::Type::CTRL_S};

    // Printable character
    if (event.is_character()) {
        InputEvent ie{InputEvent::Type::CHARACTER};
        ie.character = event.character()[0];
        return ie;
    }

    return {InputEvent::Type::UNKNOWN};
}

The pattern is straightforward, each FTXUI event maps to one of our InputEvent types. If it's a printable character, we extract the character value. If we don't recognize the event, it returns UNKNOWN and gets ignored. This is the same translation layer that would need to be reimplemented if someone wrote a new View using a different library, another benefit of the IView interface.

What the View Can Do So Far

The View works well for the current state of the project. It renders text as the user types, displays the status bar with the filename, word count, and unsaved changes indicator, captures all input events and routes them to the Presenter, and toggles the help overlay with F1. It is not perfect, newlines don't render yet and the arrow keys can't fully navigate up and down through the text. But for Phase 1, it does its job as the passive layer in the MVP pattern.

Wrapping Up the Series

This wraps up the three-part series on building wordNebula's Phase 1. Across these posts, we went from the origin of the project and why I chose Model-View-Presenter, through the Model with the GapBuffer and IBuffer interface, the Presenter that orchestrates everything and manages state, and finally the View that renders it all to the terminal.

Building each layer independently and connecting them through contracts like IBuffer and IView made the project manageable. I could work on one piece at a time without worrying about breaking the others. That separation is the whole point of MVP, and it paid off.

Phase 1 is complete but far from finished. There's more to build, but for now I'm stepping away to focus on other projects. If you want to explore the code, check out the project on GitHub.

Construyendo un editor de texto de terminal: la Vista (Parte 3)

Ilean Monterrubio Jr — Sun, 05 Apr 2026 00:00:00 +0000

Resumen

En la Parte 1 hablé del origen de este proyecto, las primeras decisiones de arquitectura y por qué elegí el GapBuffer con IBuffer como el contrato para todas las futuras implementaciones de búfer. En la Parte 2 entramos en los detalles del Presentador, cómo conecta los componentes, maneja la entrada del usuario, gestiona el estado y mantiene el Modelo y la Vista sincronizados. Ahora podemos pasar a la Vista.

¿Qué es la Vista?

La Vista es el componente con el que el usuario interactúa directamente. Todas las entradas del usuario se recopilan y se pasan al Presentador; la Vista no decide qué hacer con ellas. También es responsable de renderizar el texto que el usuario escribe, junto con cualquier advertencia, estadísticas como el conteo de palabras y si el archivo está sin guardar. La Vista no calcula nada de esto, solo muestra lo que el Presentador le envía. Otro ejemplo de cómo las tres partes de Modelo-Vista-Presentador separan las responsabilidades.

Por qué FTXUI en lugar de ncurses

En las pruebas de la prueba de concepto usé ncurses, la biblioteca estándar de facto para construir interfaces de terminal. Funcionó bien para las pruebas iniciales, y veo muchos proyectos que todavía la usan; es confiable y probada. Aunque ncurses habría sido una gran elección, investigué un poco más y encontré FTXUI, una biblioteca de C++ moderna con componentes para construir interfaces de usuario de terminal interactivas. Quería aprovechar que usa C++ moderno, en línea con la especificación que definí al inicio del proyecto de apuntar a C++20.

La interfaz IView

Mientras implementaba los otros componentes (el Modelo y el Presentador), armé una interfaz ligera para la Vista, IView. Al principio solo tomaba la entrada de caracteres y no contemplaba los caracteres especiales, ni se encargaba de renderizar dato alguno. La Vista de la prueba de concepto solo tomaba la entrada, la enviaba al Presentador, que la mandaba al búfer y la registraba para que yo pudiera ver que los datos realmente fluían por el sistema.

Pensaba en eliminarla, pero después de investigar más, decidí más bien expandir la interfaz. Mantener IView como una clase abstracta significa que, si alguien quiere escribir su propia Vista para un sistema operativo que FTXUI no soporta, puede implementar la interfaz y conectarla sin tocar el Presentador ni el Modelo.

class IView {
  public:
    virtual ~IView() = default;

    virtual void run(std::function<void(const InputEvent &)> onInput) = 0;
    virtual void render(const ViewState &state) = 0;
    virtual void exit() = 0;
    virtual std::pair<int, int> getTerminalSize() const = 0;
    virtual void showMessage(const std::string &message, bool isError = false) = 0;
};

Una explicación rápida: run() inicia el bucle de eventos y recibe un callback para manejar la entrada; esto es lo que el Presentador llama en su bucle principal. render() toma el ViewState que vimos en la Parte 2 y lo dibuja en la pantalla. exit() y getTerminalSize() hacen lo que dicen, y showMessage() es la forma en que el Presentador muestra advertencias como el aviso de "cambios sin guardar" del flujo de salida.

Renderizando la interfaz

Como mostramos en la Parte 2, la estructura ViewState define el contrato de cómo el Presentador envía datos a la Vista:

struct ViewState {
    // Content
    std::string visibleText; // Text currently visible in viewport
    int cursorPosition; // Linear position of cursor in visibleText

    // Status bar information
    int wordCount; // Total word count (primary metric for writers)
    std::string filename; // Current file name (or "Untitled")
    bool isDirty; // Unsaved changes indicator

    // UI state
    std::string statusMessage; // Temporary status message (e.g., "Saved", "Error: ...")
    bool showHelp; // Whether to show help overlay
};

Hay tres grandes tipos de datos en el contrato de ViewState: Contenido , que nos dice la cursorPosition y el visibleText. Información de la barra de estado : wordCount, filename e isDirty, que indica si el archivo está sin guardar. Por último, el estado de la interfaz : statusMessage y showHelp.

Uno de los mayores retos fue cómo lidiar con el cursor, cómo moverlo y poder agregar más al búfer cuando el cursor se mueve. Una de las soluciones más simples es dividir el visibleText en tres componentes: beforeCursor, cursor y afterCursor.

ftxui::Element FtxuiView::renderEditor() {
    const auto &text = currentState.visibleText;
    const size_t pos = static_cast<size_t>(currentState.cursorPosition);

    auto before = ftxui::text(text.substr(0, pos));

    // Character at cursor with cyan background
    std::string cursorChar = pos < text.size() ? std::string(1, text[pos]) : " ";
    auto cursor = ftxui::text(cursorChar) | ftxui::bgcolor(ftxui::Color::Cyan) | ftxui::color(ftxui::Color::Black);

    auto after = pos + 1 < text.size() ? ftxui::text(text.substr(pos + 1)) : ftxui::text("");

    return ftxui::hbox({before, cursor, after});
}

El cursor se resalta con un fondo cian para que el usuario pueda ver dónde está en el texto. Este reto existía tanto en ncurses como en FTXUI; ninguna biblioteca te da un cursor integrado para un editor de texto personalizado. Tienes que simularlo tú mismo.

Traduciendo la entrada del teclado

La Vista también es responsable de traducir los eventos crudos del teclado a las estructuras InputEvent que el Presentador entiende. FTXUI tiene su propio sistema de eventos, así que la Vista necesita una capa de traducción entre lo que FTXUI nos da y lo que nuestro Presentador espera. El método translateEvent() se encarga de este mapeo:

InputEvent FtxuiView::translateEvent(const ftxui::Event &event) {
    if (event == ftxui::Event::ArrowLeft)
        return {InputEvent::Type::ARROW_LEFT};
    if (event == ftxui::Event::ArrowRight)
        return {InputEvent::Type::ARROW_RIGHT};
    if (event == ftxui::Event::Backspace)
        return {InputEvent::Type::BACKSPACE};
    if (event == ftxui::Event::Return)
        return {InputEvent::Type::ENTER};
    if (event == ftxui::Event::CtrlQ)
        return {InputEvent::Type::CTRL_Q};
    if (event == ftxui::Event::CtrlS)
        return {InputEvent::Type::CTRL_S};

    // Printable character
    if (event.is_character()) {
        InputEvent ie{InputEvent::Type::CHARACTER};
        ie.character = event.character()[0];
        return ie;
    }

    return {InputEvent::Type::UNKNOWN};
}

El patrón es sencillo: cada evento de FTXUI se mapea a uno de nuestros tipos InputEvent. Si es un carácter imprimible, extraemos el valor del carácter. Si no reconocemos el evento, devuelve UNKNOWN y se ignora. Esta es la misma capa de traducción que habría que reimplementar si alguien escribiera una nueva Vista usando una biblioteca distinta, otro beneficio de la interfaz IView.

Lo que la Vista puede hacer hasta ahora

La Vista funciona bien para el estado actual del proyecto. Renderiza el texto conforme el usuario escribe, muestra la barra de estado con el nombre del archivo, el conteo de palabras y el indicador de cambios sin guardar, captura todos los eventos de entrada y los enruta al Presentador, y alterna la superposición de ayuda con F1. No es perfecta: los saltos de línea todavía no se renderizan y las teclas de flecha no pueden navegar del todo hacia arriba y hacia abajo por el texto. Pero para la Fase 1, cumple su trabajo como la capa pasiva del patrón MVP.

Cerrando la serie

Con esto cerramos la serie de tres partes sobre la construcción de la Fase 1 de wordNebula. A lo largo de estas entradas fuimos desde el origen del proyecto y por qué elegí Modelo-Vista-Presentador, pasando por el Modelo con el GapBuffer y la interfaz IBuffer, el Presentador que orquesta todo y gestiona el estado, y finalmente la Vista que lo renderiza todo en la terminal.

Construir cada capa de forma independiente y conectarlas mediante contratos como IBuffer e IView hizo que el proyecto fuera manejable. Podía trabajar en una pieza a la vez sin preocuparme por romper las demás. Esa separación es justamente el propósito de MVP, y valió la pena.

La Fase 1 está completa pero lejos de estar terminada. Hay más por construir, pero por ahora me alejo para enfocarme en otros proyectos. Si quieres explorar el código, échale un vistazo al proyecto en GitHub.

DEV Community: Ilean Monterrubio Jr

Common Embedded Patterns: Finite State Machine

Patrones embebidos comunes: máquina de estados finitos

Common Embedded Patterns: Memory Pool

Basic Concept

A Quick Look at malloc() and free()

Keeping track of the available blocks

Implementation

Memory pool structure

Round-up function

Read next and write next functions

Reset function

Initialization function

Allocate and free functions

Memory pool owns memory address

Capacity function

Helper functions

Example usage

Double-free edge case

Wrap-up

Patrones embebidos comunes: pool de memoria

Concepto básico

Un repaso rápido a malloc() y free()

Llevar el registro de los bloques disponibles

Implementación

Estructura del pool de memoria

Función de redondeo hacia arriba

Funciones de lectura y escritura del siguiente

Función de reinicio (reset)

Función de inicialización

Funciones de reserva y liberación

El pool es dueño de la dirección de memoria

Función de capacidad

Funciones auxiliares

Ejemplo de uso

Caso límite: doble liberación

Cierre

Patrones embebidos comunes: búfer circular

Concepto básico

Dar la vuelta dentro del arreglo

La intuición

Optimizando con una máscara de bits

Implementación

La estructura del búfer circular

Las funciones de inicialización y de potencia de dos

Las funciones put y get

Las funciones is_empty, is_full y count

Las funciones write y read

Seguridad con la rutina de servicio de interrupción (ISR)

Cierre

Common Embedded Patterns: Ring Buffer

Basic Concept

Wrapping around the array

Intuition

Optimizing with a bitmask

Implementation

Ring buffer structure

Initialization and power of two functions

Put and get functions

Is empty, is full, and count

Write and read functions

Safety with the Interrupt Service Routine (ISR)

Wrap-up

Compendium: Reproducible Developer Environments in One Config

Why I Built It

Why C and C++ First

v0.1.1 Ships Today

Tech Stack

Roadmap

Project Links

Compendium: entornos de desarrollo reproducibles en una sola configuración

Por qué lo construí

Por qué primero C y C++

La v0.1.1 se lanza hoy

Stack tecnológico

Hoja de ruta

Enlaces del proyecto

How I Built a Low-Friction Blog Pipeline

Why Build a Pipeline?

The Stack

A Quick Look at `malloc()` and `free()`

Un repaso rápido a `malloc()` y `free()`