Plano de Estudos Rust: Nível Sênior (18+ Meses)

use std::alloc::{self, Layout};
use std::ptr;

/// Um buffer circular thread-safe implementado com unsafe
/// para máxima performance
pub struct RingBuffer<T> {
    buffer: *mut T,
    capacidade: usize,
    leitura: usize,
    escrita: usize,
    tamanho: usize,
}

impl<T> RingBuffer<T> {
    pub fn new(capacidade: usize) -> Self {
        assert!(capacidade > 0, "Capacidade deve ser maior que zero");
        assert!(
            capacidade.is_power_of_two(),
            "Capacidade deve ser potência de 2 para otimização de módulo"
        );

        let layout = Layout::array::<T>(capacidade).unwrap();
        // SAFETY: layout tem tamanho > 0 (garantido pelo assert acima)
        let buffer = unsafe { alloc::alloc(layout) as *mut T };

        if buffer.is_null() {
            alloc::handle_alloc_error(layout);
        }

        RingBuffer {
            buffer,
            capacidade,
            leitura: 0,
            escrita: 0,
            tamanho: 0,
        }
    }

    pub fn push(&mut self, valor: T) -> Result<(), T> {
        if self.tamanho == self.capacidade {
            return Err(valor);
        }

        // SAFETY: escrita está sempre dentro dos limites do buffer
        // porque usamos máscara de bits (capacidade é potência de 2)
        unsafe {
            let pos = self.escrita & (self.capacidade - 1);
            ptr::write(self.buffer.add(pos), valor);
        }

        self.escrita = self.escrita.wrapping_add(1);
        self.tamanho += 1;
        Ok(())
    }

    pub fn pop(&mut self) -> Option<T> {
        if self.tamanho == 0 {
            return None;
        }

        // SAFETY: leitura está dentro dos limites e aponta para
        // um valor válido inicializado por push()
        let valor = unsafe {
            let pos = self.leitura & (self.capacidade - 1);
            ptr::read(self.buffer.add(pos))
        };

        self.leitura = self.leitura.wrapping_add(1);
        self.tamanho -= 1;
        Some(valor)
    }

    pub fn len(&self) -> usize {
        self.tamanho
    }

    pub fn is_empty(&self) -> bool {
        self.tamanho == 0
    }
}

impl<T> Drop for RingBuffer<T> {
    fn drop(&mut self) {
        // SAFETY: precisamos dropar todos os elementos restantes
        while let Some(_) = self.pop() {}

        let layout = Layout::array::<T>(self.capacidade).unwrap();
        // SAFETY: buffer foi alocado com o mesmo layout em new()
        unsafe {
            alloc::dealloc(self.buffer as *mut u8, layout);
        }
    }
}

// SAFETY: RingBuffer é Send se T é Send, pois possui os dados exclusivamente
unsafe impl<T: Send> Send for RingBuffer<T> {}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn operacoes_basicas() {
        let mut rb = RingBuffer::new(4);
        assert!(rb.push(1).is_ok());
        assert!(rb.push(2).is_ok());
        assert!(rb.push(3).is_ok());
        assert!(rb.push(4).is_ok());
        assert!(rb.push(5).is_err()); // cheio

        assert_eq!(rb.pop(), Some(1));
        assert_eq!(rb.pop(), Some(2));

        assert!(rb.push(5).is_ok()); // agora tem espaço
        assert!(rb.push(6).is_ok());
    }

    #[test]
    fn wraparound() {
        let mut rb = RingBuffer::new(4);
        for i in 0..100 {
            rb.push(i).unwrap();
            assert_eq!(rb.pop(), Some(i));
        }
    }
}

# Rodar testes com Miri para detectar UB
rustup component add miri
cargo +nightly miri test

// Chamando código C a partir de Rust
use std::ffi::{CStr, CString};
use std::os::raw::{c_char, c_int};

// Declarando funções externas de uma biblioteca C
extern "C" {
    fn strlen(s: *const c_char) -> usize;
    fn strcmp(s1: *const c_char, s2: *const c_char) -> c_int;
    fn getenv(name: *const c_char) -> *const c_char;
}

fn tamanho_cstring(s: &str) -> usize {
    let c_str = CString::new(s).expect("String contém null byte");
    // SAFETY: c_str é uma string C válida terminada em null
    unsafe { strlen(c_str.as_ptr()) }
}

fn ler_variavel_ambiente(nome: &str) -> Option<String> {
    let c_nome = CString::new(nome).ok()?;
    // SAFETY: getenv retorna null ou ponteiro para string válida
    let ptr = unsafe { getenv(c_nome.as_ptr()) };
    if ptr.is_null() {
        None
    } else {
        // SAFETY: ptr não é null e aponta para string C válida
        Some(unsafe { CStr::from_ptr(ptr) }.to_string_lossy().into_owned())
    }
}

// Expondo Rust para ser chamado por C
#[no_mangle]
pub extern "C" fn rust_somar(a: c_int, b: c_int) -> c_int {
    a + b
}

#[no_mangle]
pub extern "C" fn rust_fibonacci(n: c_int) -> c_int {
    match n {
        0 => 0,
        1 => 1,
        _ => {
            let mut a = 0;
            let mut b = 1;
            for _ in 2..=n {
                let temp = b;
                b = a + b;
                a = temp;
            }
            b
        }
    }
}

# Cargo.toml
[build-dependencies]
bindgen = "0.69"

// build.rs
fn main() {
    println!("cargo:rerun-if-changed=wrapper.h");

    let bindings = bindgen::Builder::default()
        .header("wrapper.h")
        .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
        .generate()
        .expect("Falha ao gerar bindings");

    let out_path = std::path::PathBuf::from(std::env::var("OUT_DIR").unwrap());
    bindings
        .write_to_file(out_path.join("bindings.rs"))
        .expect("Falha ao escrever bindings");
}

# Visualizar MIR de uma função
RUSTFLAGS="--emit=mir" cargo build

# Ou usar o Rust Playground com a opção MIR

# Visualizar LLVM IR
RUSTFLAGS="--emit=llvm-ir" cargo build

# Visualizar assembly
RUSTFLAGS="--emit=asm" cargo build

// Exemplo: entendendo como o compilador otimiza
// Esta função é eliminada pelo compilador (zero-cost abstraction)
fn somar_iterador(nums: &[i32]) -> i32 {
    nums.iter().sum()
}

// Gera assembly praticamente idêntico a:
fn somar_loop(nums: &[i32]) -> i32 {
    let mut total = 0;
    for &n in nums {
        total += n;
    }
    total
}

// O MIR mostra que ambas são reduzidas
// à mesma sequência de operações

// Benchmarking com criterion
// Cargo.toml:
// [dev-dependencies]
// criterion = { version = "0.5", features = ["html_reports"] }
// [[bench]]
// name = "meu_benchmark"
// harness = false

use criterion::{black_box, criterion_group, criterion_main, Criterion, BenchmarkId};

fn busca_linear(dados: &[i32], alvo: i32) -> Option<usize> {
    dados.iter().position(|&x| x == alvo)
}

fn busca_binaria(dados: &[i32], alvo: i32) -> Option<usize> {
    dados.binary_search(&alvo).ok()
}

fn benchmark_busca(c: &mut Criterion) {
    let mut grupo = c.benchmark_group("busca");

    for tamanho in [100, 1_000, 10_000, 100_000].iter() {
        let dados: Vec<i32> = (0..*tamanho).collect();
        let alvo = tamanho / 2;

        grupo.bench_with_input(
            BenchmarkId::new("linear", tamanho),
            tamanho,
            |b, _| b.iter(|| busca_linear(black_box(&dados), black_box(alvo))),
        );

        grupo.bench_with_input(
            BenchmarkId::new("binaria", tamanho),
            tamanho,
            |b, _| b.iter(|| busca_binaria(black_box(&dados), black_box(alvo))),
        );
    }

    grupo.finish();
}

criterion_group!(benches, benchmark_busca);
criterion_main!(benches);

# perf (Linux)
cargo build --release
perf record -g ./target/release/meu_programa
perf report

# Flamegraph
cargo install flamegraph
cargo flamegraph --release

# Valgrind / Cachegrind (análise de cache)
valgrind --tool=cachegrind ./target/release/meu_programa
cg_annotate cachegrind.out.*

# Heaptrack (análise de alocação)
heaptrack ./target/release/meu_programa
heaptrack_gui heaptrack.*.gz

use std::borrow::Cow;

// Ruim: aloca desnecessariamente
fn processar_nome_ruim(nome: &str) -> String {
    if nome.contains(' ') {
        nome.replace(' ', "_")
    } else {
        nome.to_string() // alocação desnecessária
    }
}

// Bom: usa Cow para evitar alocação quando possível
fn processar_nome_bom(nome: &str) -> Cow<'_, str> {
    if nome.contains(' ') {
        Cow::Owned(nome.replace(' ', "_"))
    } else {
        Cow::Borrowed(nome) // zero alocação
    }
}

// Reutilizando buffers em loops
fn processar_dados_otimizado(dados: &[Vec<u8>]) -> Vec<String> {
    let mut buffer = String::new(); // alocado uma vez
    let mut resultados = Vec::with_capacity(dados.len()); // pré-alocado

    for item in dados {
        buffer.clear(); // reutiliza a memória alocada
        for &byte in item {
            buffer.push(byte as char);
        }
        resultados.push(buffer.clone());
    }

    resultados
}

// Usando SmallVec para vetores pequenos (stack allocation)
// use smallvec::SmallVec;
// let mut nums: SmallVec<[i32; 8]> = SmallVec::new();
// Para 8 ou menos elementos, fica na stack

// Arena allocation para muitas alocações pequenas de mesma lifetime
// use bumpalo::Bump;
// let arena = Bump::new();
// let s = arena.alloc_str("texto na arena");
// Tudo liberado de uma vez quando arena é droppada

// Processamento vetorial com SIMD
// Nota: requer nightly ou std::simd quando estabilizado

// Abordagem portável: confiar no auto-vetorização do LLVM
fn soma_quadrados_autovec(dados: &[f32]) -> f32 {
    dados.iter().map(|x| x * x).sum()
}

// Para o compilador vetorizar eficientemente:
// 1. Use slices contíguos (não linked lists)
// 2. Evite branches dentro de loops
// 3. Use tipos alinhados
// 4. Processe em blocos de tamanho fixo

fn dot_product_otimizado(a: &[f32], b: &[f32]) -> f32 {
    assert_eq!(a.len(), b.len());

    // Processamento em chunks para auto-vetorização
    let mut soma = 0.0f32;
    let chunks = a.len() / 4;

    for i in 0..chunks {
        let offset = i * 4;
        soma += a[offset] * b[offset]
            + a[offset + 1] * b[offset + 1]
            + a[offset + 2] * b[offset + 2]
            + a[offset + 3] * b[offset + 3];
    }

    // Processar elementos restantes
    for i in (chunks * 4)..a.len() {
        soma += a[i] * b[i];
    }

    soma
}

// Dicas de compilação para performance:
// RUSTFLAGS="-C target-cpu=native" cargo build --release
// Isso habilita instruções SIMD específicas da CPU

// Ruim: Array of Structs (AoS) - pobre localidade de cache
struct ParticleAoS {
    x: f64,
    y: f64,
    z: f64,
    mass: f64,
    vx: f64,
    vy: f64,
    vz: f64,
    name: String,  // 24 bytes desnecessários para cálculo de posição
}

// Bom: Struct of Arrays (SoA) - excelente localidade de cache
struct ParticlesSoA {
    x: Vec<f64>,
    y: Vec<f64>,
    z: Vec<f64>,
    mass: Vec<f64>,
    vx: Vec<f64>,
    vy: Vec<f64>,
    vz: Vec<f64>,
    names: Vec<String>,
}

impl ParticlesSoA {
    fn atualizar_posicoes(&mut self, dt: f64) {
        // Acessa apenas os dados necessários - cache friendly
        for i in 0..self.x.len() {
            self.x[i] += self.vx[i] * dt;
            self.y[i] += self.vy[i] * dt;
            self.z[i] += self.vz[i] * dt;
        }
    }
}

// Alinhamento de dados para SIMD
#[repr(C, align(64))]  // Alinhado ao tamanho de cache line
struct AlgoritmoBuffer {
    dados: [f64; 8],
}

// Ordenação de campos para minimizar padding
// Ruim: desperdiça bytes com padding
struct PaddinRuim {
    a: u8,      // 1 byte + 7 padding
    b: u64,     // 8 bytes
    c: u8,      // 1 byte + 3 padding
    d: u32,     // 4 bytes
}               // Total: 24 bytes

// Bom: campos ordenados por tamanho decrescente
struct PaddingBom {
    b: u64,     // 8 bytes
    d: u32,     // 4 bytes
    a: u8,      // 1 byte
    c: u8,      // 1 byte + 2 padding
}               // Total: 16 bytes (33% menor!)

use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;

// Contadores atômicos lock-free
struct Metricas {
    requisicoes_total: AtomicU64,
    requisicoes_erro: AtomicU64,
    bytes_processados: AtomicU64,
}

impl Metricas {
    fn new() -> Self {
        Metricas {
            requisicoes_total: AtomicU64::new(0),
            requisicoes_erro: AtomicU64::new(0),
            bytes_processados: AtomicU64::new(0),
        }
    }

    fn registrar_requisicao(&self, bytes: u64, sucesso: bool) {
        self.requisicoes_total.fetch_add(1, Ordering::Relaxed);
        self.bytes_processados.fetch_add(bytes, Ordering::Relaxed);
        if !sucesso {
            self.requisicoes_erro.fetch_add(1, Ordering::Relaxed);
        }
    }

    fn snapshot(&self) -> (u64, u64, u64) {
        (
            self.requisicoes_total.load(Ordering::Relaxed),
            self.requisicoes_erro.load(Ordering::Relaxed),
            self.bytes_processados.load(Ordering::Relaxed),
        )
    }
}

// Processamento paralelo com Rayon
// use rayon::prelude::*;
//
// fn processar_paralelo(dados: &mut [f64]) {
//     dados.par_iter_mut().for_each(|x| {
//         *x = (*x * 2.0).sin().abs();
//     });
// }
//
// fn soma_paralela(dados: &[f64]) -> f64 {
//     dados.par_iter().sum()
// }

# .cargo/config.toml compartilhado pelo time
[build]
rustflags = [
    "-D", "warnings",
    "-W", "clippy::pedantic",
    "-W", "clippy::nursery",
    "-A", "clippy::module_name_repetitions",
]

[alias]
ci = "clippy --all-targets --all-features -- -D warnings"

## Checklist de Review para Código Rust

### Correção
- [ ] O código faz o que deveria?
- [ ] Todos os edge cases são tratados?
- [ ] Erros são propagados corretamente?

### Segurança
- [ ] Unsafe está minimizado e documentado com SAFETY?
- [ ] Sem race conditions ou data races?
- [ ] Input validation adequada?

### Performance
- [ ] Alocações desnecessárias?
- [ ] Clones que poderiam ser referências?
- [ ] Algoritmo adequado para o tamanho dos dados?

### Manutenabilidade
- [ ] Código auto-documentado com nomes descritivos?
- [ ] Testes adequados?
- [ ] Documentação atualizada?

## ADR-001: Escolha do framework web

### Contexto
Precisamos de um framework web para nosso novo serviço de API.

### Opções Consideradas

| Critério | Axum | Actix-web | Rocket |
|----------|------|-----------|--------|
| Performance | Excelente | Excelente | Boa |
| Ecossistema Tower | Nativo | Parcial | Não |
| Facilidade de teste | Alta | Média | Média |
| Comunidade | Grande e crescente | Grande | Média |
| Compatibilidade Tokio | Nativa | Próprio runtime | Tokio |

### Decisão
Escolhemos Axum pelos seguintes motivos:
1. Integração nativa com o ecossistema Tower
2. Melhor testabilidade através de extractors
3. Alinhamento com a direção do ecossistema async Rust

### Consequências
- Time precisa aprender Tower middleware
- Migramos endpoints existentes de Actix gradualmente

# Configurando o ambiente para contribuir com rustc
git clone https://github.com/rust-lang/rust.git
cd rust
cp config.example.toml config.toml

# Edite config.toml para configurar:
# [llvm]
# download-ci-llvm = true  # Baixa LLVM pré-compilado (muito mais rápido)
#
# [rust]
# debug = true
# incremental = true

# Compilar
./x.py build library
./x.py test library/std

- Feature Name: meu_feature
- Start Date: 2026-02-27
- RFC PR: (preenchido depois)
- Rust Issue: (preenchido depois)

# Resumo
Uma explicação de um parágrafo do feature proposto.

# Motivação
Por que estamos fazendo isso? Quais casos de uso ele suporta?
Qual é o resultado esperado?

# Guia de Referência
Explique o feature como se estivesse ensinando para outro
desenvolvedor Rust. Use exemplos de código.

# Referência Detalhada
Especificação técnica precisa.

# Desvantagens
Por que NÃO deveríamos fazer isso?

# Alternativas
Que outros designs foram considerados e por que não foram escolhidos?

# Questões Não Resolvidas
Pontos que precisam ser esclarecidos durante o processo de RFC.

# Trabalho Futuro
Extensões possíveis que não fazem parte desta proposta.

# Cargo.toml completo para publicação
[package]
name = "minha-crate"
version = "0.1.0"
edition = "2021"
rust-version = "1.70"
authors = ["Seu Nome <email@exemplo.com>"]
description = "Descrição concisa da funcionalidade"
documentation = "https://docs.rs/minha-crate"
repository = "https://github.com/usuario/minha-crate"
license = "MIT OR Apache-2.0"
keywords = ["keyword1", "keyword2", "keyword3"]
categories = ["development-tools"]
readme = "README.md"
exclude = ["tests/fixtures/*", ".github/*"]

[badges]
maintenance = { status = "actively-developed" }

# GitHub Actions CI para crate
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        rust: [stable, beta, nightly, "1.70"]
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ matrix.rust }}
      - run: cargo test --all-features
      - run: cargo clippy -- -D warnings
      - run: cargo doc --no-deps