Skip to content

BUFFER_POOL_OPTIMIZATION.md

Latest commit

 

History

History
362 lines (289 loc) · 9.54 KB

BUFFER_POOL_OPTIMIZATION.md

File metadata and controls

362 lines (289 loc) · 9.54 KB

JsonBufferPool Optimization - Guia Completo v1.1.4+

🎯 Visão Geral

O JsonBufferPool otimizado em PivotPHP v1.1.4+ introduz um sistema inteligente de threshold que automaticamente decide quando usar pooling para maximizar performance.

🧠 Sistema de Threshold Inteligente

Como Funciona

// Dados pequenos (<256 bytes) - usa json_encode() direto
$smallData = ['id' => 1, 'name' => 'John'];
$json = JsonBufferPool::encodeWithPool($smallData); // Usa json_encode()

// Dados grandes (≥256 bytes) - usa pooling automático
$largeData = array_fill(0, 100, ['id' => 1, 'name' => 'User', 'email' => 'user@example.com']);
$json = JsonBufferPool::encodeWithPool($largeData); // Usa pooling

Lógica de Decisão

private static function shouldUsePooling(mixed $data): bool
{
    // Threshold: 256 bytes
    $estimatedSize = self::estimateDataSize($data);
    
    return $estimatedSize >= 256;
}

⚡ Performance Comparativa

Dados Pequenos (<256 bytes)

// ✅ OTIMIZADO: Usa json_encode() direto (sem overhead)
$smallData = ['status' => 'ok', 'count' => 42];

// Performance: 500K+ ops/sec
// Overhead: ~0ms (zero)
// Uso: Responses simples, status, small payloads

Dados Médios (256 bytes - 10KB)

// ✅ OTIMIZADO: Usa pooling automático
$mediumData = array_fill(0, 20, [
    'id' => $i, 
    'name' => "User {$i}", 
    'email' => "user{$i}@example.com"
]);

// Performance: 119K+ ops/sec
// Ganho: 15-30% vs json_encode()
// Uso: Lists, user data, API responses

Dados Grandes (>10KB)

// ✅ OTIMIZADO: Pooling com buffers grandes
$largeData = array_fill(0, 1000, [
    'id' => $i,
    'profile' => [...], // Objeto complexo
    'metadata' => [...]
]);

// Performance: 214K+ ops/sec 
// Ganho: 98%+ vs json_encode()
// Uso: Complex objects, large datasets, reports

🔧 Configuração e Uso

Uso Automático (Recomendado)

// Zero configuração - funciona automaticamente
$app->get('/api/users', function($req, $res) {
    $users = User::all();
    
    // JsonBufferPool decide automaticamente:
    // - Poucos users: json_encode() direto
    // - Muitos users: pooling automático
    return $res->json($users);
});

Configuração Manual (Avançado)

use PivotPHP\Core\Json\Pool\JsonBufferPool;

// Configurar thresholds personalizados
JsonBufferPool::configure([
    'threshold_bytes' => 512,      // Limite personalizado: 512 bytes
    'max_pool_size' => 200,        // Máximo de buffers no pool
    'default_capacity' => 8192,    // Tamanho padrão dos buffers
    'size_categories' => [
        'small' => 2048,   // 2KB
        'medium' => 8192,  // 8KB  
        'large' => 32768,  // 32KB
        'xlarge' => 131072 // 128KB
    ]
]);

Controle Manual

// Forçar uso de pooling
$json = JsonBufferPool::encodeWithPool($data);

// Usar json_encode() tradicional
$json = json_encode($data);

// Verificar se usou pooling
$stats = JsonBufferPool::getStatistics();
if ($stats['reuses'] > 0) {
    echo "Pooling ativo!";
}

📊 Monitoramento e Métricas

Estatísticas em Tempo Real

$stats = JsonBufferPool::getStatistics();

echo "Reuses: {$stats['reuses']}\n";           // Buffers reutilizados
echo "Allocations: {$stats['allocations']}\n"; // Novos buffers criados
echo "Efficiency: " . ($stats['reuses'] / ($stats['reuses'] + $stats['allocations']) * 100) . "%\n";

Métricas de Performance

$app->get('/metrics/json-pool', function($req, $res) {
    $stats = JsonBufferPool::getStatistics();
    
    return $res->json([
        'pool_efficiency' => round($stats['reuse_rate'], 2),
        'total_operations' => $stats['total_operations'],
        'memory_saved_mb' => round($stats['memory_saved'] / 1024 / 1024, 2),
        'performance_gain' => $stats['performance_multiplier'] . 'x faster',
        'recommendations' => $stats['efficiency'] > 80 
            ? 'Pool working optimally' 
            : 'Consider adjusting threshold'
    ]);
});

🎯 Casos de Uso Otimizados

1. API REST com Lists

$app->get('/api/users', function($req, $res) {
    $users = User::paginate(50); // ~50 users
    
    // AUTOMÁTICO: Pool usado se >5-10 users
    return $res->json([
        'users' => $users,
        'pagination' => [...],
        'meta' => [...]
    ]);
});

// Performance: 119K ops/sec típico (vs 67K sem pool)

2. Complex Object Serialization

$app->get('/api/reports/:id', function($req, $res) {
    $report = Report::findWithRelations($req->param('id'));
    
    // AUTOMÁTICO: Pool usado para objetos complexos
    return $res->json([
        'report' => $report->toArray(),      // Dados principais  
        'analytics' => $report->analytics,   // Métricas complexas
        'attachments' => $report->files,     // Arquivos relacionados
        'history' => $report->history        // Histórico de mudanças
    ]);
});

// Performance: 214K ops/sec típico (vs 19K sem pool)

3. Streaming de Dados

$app->get('/api/stream/events', function($req, $res) {
    $res->header('Content-Type', 'application/x-ndjson');
    
    foreach (EventStream::read() as $event) {
        // AUTOMÁTICO: Pool reutilizado para cada event
        $json = JsonBufferPool::encodeWithPool($event);
        $res->write($json . "\n");
    }
    
    return $res->end();
});

// Performance: Pool reusa buffers, zero alocações extras

🔍 Troubleshooting

Problema: Pool não está sendo usado

// Verificar tamanho dos dados
$data = ['small' => 'data'];
$size = JsonBufferPool::estimateDataSize($data);
echo "Size: {$size} bytes\n";

if ($size < 256) {
    echo "Dados muito pequenos - pool não necessário\n";
}

Problema: Performance pior com pool

// Isso pode acontecer com dados muito pequenos
$stats = JsonBufferPool::getStatistics();

if ($stats['efficiency'] < 20) {
    echo "Pool ineficiente - considere aumentar threshold\n";
    
    // Ajustar threshold
    JsonBufferPool::configure(['threshold_bytes' => 512]);
}

Problema: Memory usage alto

// Verificar tamanho do pool
$stats = JsonBufferPool::getStatistics();

if ($stats['current_usage'] > 50 * 1024 * 1024) { // 50MB
    echo "Pool usando muita memória\n";
    
    // Reduzir tamanho máximo
    JsonBufferPool::configure(['max_pool_size' => 50]);
    
    // Ou limpar pool
    JsonBufferPool::clearPool();
}

🧪 Testing e Benchmarks

Benchmark Simples

function benchmarkJsonPool() {
    $data = array_fill(0, 100, ['id' => 1, 'name' => 'Test']);
    $iterations = 10000;
    
    // Sem pool
    $start = microtime(true);
    for ($i = 0; $i < $iterations; $i++) {
        json_encode($data);
    }
    $timeWithout = microtime(true) - $start;
    
    // Com pool
    $start = microtime(true);
    for ($i = 0; $i < $iterations; $i++) {
        JsonBufferPool::encodeWithPool($data);
    }
    $timeWith = microtime(true) - $start;
    
    $improvement = ($timeWithout - $timeWith) / $timeWithout * 100;
    echo "Improvement: {$improvement}%\n";
}

Unit Test Example

public function testJsonPoolThreshold()
{
    // Dados pequenos
    $smallData = ['id' => 1];
    $this->assertFalse(JsonBufferPool::shouldUsePooling($smallData));
    
    // Dados grandes
    $largeData = array_fill(0, 50, ['id' => 1, 'data' => str_repeat('x', 100)]);
    $this->assertTrue(JsonBufferPool::shouldUsePooling($largeData));
}

📈 Performance Guidelines

Quando o Pool é Mais Eficiente

✅ IDEAL para:

  • Arrays com 10+ elementos
  • Objetos com 5+ propriedades
  • Strings >1KB
  • Operações repetitivas
  • APIs com alta carga

❌ EVITAR para:

  • Dados <256 bytes
  • Operações únicas
  • Micro-responses
  • Simple status responses

Otimizações de Produção

// Configuração para alta performance
JsonBufferPool::configure([
    'threshold_bytes' => 128,        // Mais agressivo
    'max_pool_size' => 1000,         // Pool maior
    'enable_statistics' => false,    // Desabilitar stats em produção
    'warm_up_pool' => true          // Pre-allocate buffers
]);

🔗 Integração com Framework

Uso Automático em Responses

// O framework usa automaticamente JsonBufferPool::encodeWithPool()
// em todos os $res->json() quando detecta dados grandes

class Response {
    public function json($data, int $status = 200): ResponseInterface 
    {
        // AUTOMÁTICO: Usa pooling inteligente
        $json = JsonBufferPool::encodeWithPool($data);
        
        return $this->status($status)
                    ->header('Content-Type', 'application/json')
                    ->write($json);
    }
}

Middleware para Logging

$app->use(function($req, $res, $next) {
    $before = JsonBufferPool::getStatistics();
    
    $response = $next($req, $res);
    
    $after = JsonBufferPool::getStatistics();
    $operations = $after['total_operations'] - $before['total_operations'];
    
    if ($operations > 0) {
        error_log("JSON operations: {$operations}, Pool efficiency: {$after['reuse_rate']}%");
    }
    
    return $response;
});

🎯 Conclusão

O JsonBufferPool otimizado v1.1.4+ oferece:

  • ✅ Performance inteligente - Usa pool apenas quando benéfico
  • ✅ Zero configuração - Funciona automaticamente
  • ✅ Monitoramento integrado - Estatísticas em tempo real
  • ✅ Compatibilidade total - Drop-in replacement para json_encode()
  • ✅ Production-ready - Testado e validado em alta carga

Próximos passos: