diff --git a/README.md b/README.md index 412b8e2..d18dd9b 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ algoritmos o low-level. **Nivel:** intermedio-avanzado. **Prerequisitos:** Rust básico, ownership, complejidad algorítmica y nociones de arquitectura de computadores. -## Temas Planeados +## Temas Del Curso - Diseño de benchmarks y líneas base reproducibles. - Profiling y lectura crítica de perfiles. @@ -55,9 +55,9 @@ cargo test --doc ## Gobernanza -- La estructura sigue RFC-0001 §15; los capítulos seguirán §14 y §16. -- Antes de iniciar desarrollo se crearán plan, GitHub Project, milestones e - issues asignados a `jeresoftx`. +- La estructura sigue RFC-0001 §15 y los capítulos aplican §14 y §16. +- El plan, GitHub Project, milestones e issues asignados a `jeresoftx` ya + proporcionan trazabilidad de cada slice educativo. - El avance operativo vive en el [GitHub Project](https://github.com/users/jeresoftx/projects/19). - Cada PR deberá pertenecer al mismo GitHub Project que su issue, conforme a RFC-0002. diff --git a/ROADMAP.md b/ROADMAP.md index 0afadca..7bd2e2f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -9,8 +9,9 @@ registra dirección y calidad, no una carrera por terminar (RFC-0001 §1). La fundación y el plan operativo están listos. El [plan versionado](docs/superpowers/plans/2026-07-29-rust-performance-course.md) se ejecuta mediante el [GitHub Project](https://github.com/users/jeresoftx/projects/19), -milestones e issues. La investigación completa de rendimiento está en `draft`; -queda `#34`: cierre editorial, glosario y auditoría de enlaces. +milestones e issues. Los diez capítulos, ruta de lectura, glosario, ejemplos y +plantilla de informe están en `draft`. La revisión humana transversal decide +qué contenido puede pasar después a `reviewed` o `published`. ## Dirección Técnica diff --git a/docs/00-ruta-de-lectura.md b/docs/00-ruta-de-lectura.md new file mode 100644 index 0000000..59bb51e --- /dev/null +++ b/docs/00-ruta-de-lectura.md @@ -0,0 +1,43 @@ +# Ruta de lectura + +**Estado del curso:** draft completo; pendiente de revisión humana transversal. + +Este libro se recorre en orden porque cada capítulo reutiliza el contrato de +evidencia del anterior. No es una lista de trucos para acelerar código: es una +práctica para decidir qué medir, qué representa una mejora y qué límite debe +acompañar una conclusión. + +## Recorrido recomendado + +1. **[Evidencia y contrato de medición](01-evidencia-y-contrato-de-medicion.md):** + empieza por hipótesis, línea base y amenazas a validez. +2. **[Benchmarks reproducibles](02-benchmarks-reproducibles.md)** y + **[Profiling y hot paths](03-profiling-y-hot-paths.md):** aprende a producir + muestras y a convertir una observación en una pregunta medible. +3. **[Caché y localidad](04-cache-y-localidad.md)**, + **[Ramas y layout orientado a datos](05-ramas-y-layout.md)** y + **[Asignaciones y costo de propiedad](06-asignaciones-y-propiedad.md):** + relaciona representación, CPU y trabajo de memoria. +4. **[Arenas seguras y ciclos de vida](07-arenas-seguras-y-ciclos-de-vida.md)** + y **[Zero-copy, buffers y serialización](08-zero-copy-y-buffers.md):** + estudia ownership y movimiento de datos sin ocultar sus contratos. +5. **[SIMD y límites de vectorización](09-simd-y-limites-de-vectorizacion.md):** + compara lanes explícitos con una referencia escalar y con límites de + portabilidad. +6. **[Investigación completa de rendimiento](10-investigacion-completa-de-rendimiento.md):** + integra los pasos en un informe de evidencia local. + +## Atajos conscientes + +- Para diseñar un benchmark nuevo, vuelve a los capítulos 01 y 02 antes de + reutilizar un ejemplo de memoria o SIMD. +- Para diagnosticar una ruta observada, usa el capítulo 03 y formula después + una hipótesis que el capítulo 02 pueda contrastar. +- Para cambiar representación o ownership, compara capítulos 04 a 08 y + conserva los mismos resultados observables antes de medir tiempos. +- Para comunicar resultados, usa el capítulo 10 y su + [plantilla de informe](reports/10-investigacion-simd.md); un resultado local + no cambia el estado `draft` del curso. + +Consulta el [glosario](11-glosario.md) cuando un término de medición, +arquitectura u ownership aparezca por primera vez. diff --git a/docs/11-glosario.md b/docs/11-glosario.md new file mode 100644 index 0000000..3720def --- /dev/null +++ b/docs/11-glosario.md @@ -0,0 +1,23 @@ +# Glosario + +**Estado:** draft + +| Término | Definición operativa | Primera lectura | +|---|---|---| +| Amenaza a validez | Condición que puede explicar una diferencia observada sin que la candidata sea la causa. | [01](01-evidencia-y-contrato-de-medicion.md) | +| Benchmark | Procedimiento repetible que recolecta muestras para responder una pregunta acotada. | [02](02-benchmarks-reproducibles.md) | +| Calentamiento | Ejecuciones previas que no se incluyen en las muestras reportadas. | [02](02-benchmarks-reproducibles.md) | +| Hot path | Ruta donde un perfil observó trabajo relevante bajo una carga concreta. | [03](03-profiling-y-hot-paths.md) | +| Línea base | Implementación o estado contra el cual se contrasta una candidata. | [01](01-evidencia-y-contrato-de-medicion.md) | +| Localidad | Probabilidad de reutilizar datos cercanos en tiempo o posición de memoria. | [04](04-cache-y-localidad.md) | +| Layout | Organización física de campos y colecciones que condiciona los accesos. | [05](05-ramas-y-layout.md) | +| Asignación | Obtención de memoria para un valor; su costo depende de carga, allocator y vida útil. | [06](06-asignaciones-y-propiedad.md) | +| Arena segura | Colección que comparte ciclo de vida y usa handles verificables sin punteros crudos. | [07](07-arenas-seguras-y-ciclos-de-vida.md) | +| Zero-copy | Interfaz que reutiliza un buffer mediante préstamos en vez de copiar cada campo. | [08](08-zero-copy-y-buffers.md) | +| SIMD | Operación aplicada a varios datos independientes mediante lanes. | [09](09-simd-y-limites-de-vectorizacion.md) | +| Cola | Elementos que no llenan un grupo SIMD y requieren un recorrido complementario. | [09](09-simd-y-limites-de-vectorizacion.md) | +| Evidencia local | Resultado válido para la carga y entorno declarados, sin garantía de generalización. | [10](10-investigacion-completa-de-rendimiento.md) | + +El glosario facilita la lectura, pero no reemplaza los invariantes ni límites de +cada capítulo. Cuando un término condicione una decisión, sigue el enlace y +revisa su contexto completo. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 420dc60..03ef78f 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,5 +1,7 @@ # Summary +- [Ruta de lectura](00-ruta-de-lectura.md) + # Parte I: Disciplina de medición - [Evidencia y contrato de medición](01-evidencia-y-contrato-de-medicion.md) @@ -21,3 +23,7 @@ # Parte IV: Investigación integradora y cierre - [Investigación completa de rendimiento](10-investigacion-completa-de-rendimiento.md) + +# Referencia + +- [Glosario](11-glosario.md) diff --git a/docs/superpowers/plans/2026-07-29-rust-performance-course.md b/docs/superpowers/plans/2026-07-29-rust-performance-course.md index d241ee6..480fe8d 100644 --- a/docs/superpowers/plans/2026-07-29-rust-performance-course.md +++ b/docs/superpowers/plans/2026-07-29-rust-performance-course.md @@ -1,6 +1,6 @@ # Plan de implementación de Rust Performance -**Estado:** activo · **Actualizado:** 2026-07-29 · **Repositorio:** +**Estado:** completo en draft · **Actualizado:** 2026-07-29 · **Repositorio:** [`jeresoftx/rust-performance`](https://github.com/jeresoftx/rust-performance) ## Fuente de verdad @@ -158,7 +158,7 @@ su dependencia. ### Cierre editorial -- [ ] #34 Completar ruta de lectura, glosario, referencias cruzadas y auditoría. +- [x] #34 Completar ruta de lectura, glosario, referencias cruzadas y auditoría. ## Dependencias y blockers @@ -212,5 +212,6 @@ principal → 1 PR → checks → squash merge`. El PR debe agregarse y verifica en Project #19 conforme a RFC-0002; los items solo pasan a `Done` tras merge y sincronización de `main`. -Siguiente bloque recomendado: `#2 → #3 → #4`, capítulo 01. No requiere -dependencias externas y establece la metodología del resto del curso. +Siguiente paso recomendado: revisión humana transversal del contenido `draft`. +Esa revisión decide por separado qué capítulos pueden pasar a `reviewed` o +`published`; no forma parte de esta ejecución autónoma.