README

Event Loop assíncrono ultra-otimizado baseado em PHP Fibers nativos com suporte completo a TCP, timers, streams e operações de I/O não-bloqueantes em arquitetura reativa.

⚡ Zero dependências externas | 🔥 Performance máxima (1.500+ req/s) | 🎯 API limpa e intuitiva | 🧬 Fibers nativos do PHP 8.1+ | 📊 Observabilidade integrada

📋 Índice

• O que é?
• Características
• Comparação de Performance
• Requisitos
• Instalação
• Início Rápido
• Guia Completo
  • Timers e Scheduling
  • TCP Streams
  • Leitura de Arquivos
  • Fibers e Concorrência
  • Gerenciamento de Erros
  • Otimizações de Performance
• Exemplos Práticos
• API Reference Completa
• Troubleshooting
• Contribuindo
• Licença

O que é?

FiberEventLoop é uma biblioteca de event loop reativa escrita em PHP puro que implementa o padrão Reactor com suporte nativo a PHP Fibers (introduzidos no PHP 8.1).

Diferente de callbacks tradicionais, o FiberEventLoop permite escrever código assíncrono com sintaxe síncrona, mantendo a legibilidade e facilitando o debugging.

Quando usar?

✅ Ideal para:

• Servidores TCP/HTTP assincronos
• Scrapers web em alta escala
• Processamento de streams
• Task schedulers (cron-like)
• Monitoramento em tempo real
• Microserviços
• WebSockets e conexões long-lived

❌ Não é ideal para:

• Aplicações síncronas simples (use Laravel/Symfony)
• Processamento pesado de CPU (use Swoole com workers)

Características

🎯 Core Features

🚀 Performance

┌─────────────────────────────────────────────────┐
│ Benchmark em Intel i7 16GB RAM / PHP 8.2        │
├─────────────────────────────────────────────────┤
│ Timers simultâneos:   50,000/s   (<0.1ms)      │
│ Conexões TCP:         10,000/s   (<1ms)        │
│ Requisições HTTP:      1,500/s   (~5ms)        │
│ Leitura de arquivos:   5,000/s   (<2ms)        │
│ Iterações idle:      1,000,000/s (adaptativo)  │
└─────────────────────────────────────────────────┘

🛠️ Arquitetura

• Modular: Traits especializadas (FiberManagerTrait, StreamManagerTrait, TimerManagerTrait)
• Extensível: Fácil adicionar novos tipos de operações
• Type-safe: Strict types, PHPDoc completo
• Observável: Métricas e logging de erros

Comparação de Performance

Comparação com outras soluções PHP:

*Swoole é uma extensão C compilada, não PHP puro. FiberEventLoop é a solução mais rápida em PHP puro.

Requisitos

• PHP 8.2 ou superior (8.1+ com FiberEventLoop v1.x)
• Extensão sockets (habilitada por padrão na maioria dos servidores)
• SO: Linux, macOS, Windows

Verificar instalação

# Verificar versão do PHP
php -v

# Verificar se sockets está disponível
php -m | grep sockets

Instalação

Via Composer (recomendado)

composer require omegaalfa/fiber-event-loop

Instalação Manual

git clone https://github.com/omegaalfa/FiberEventLoop.git
cd FiberEventLoop
composer install

Verificar instalação

<?php
require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

echo "✅ FiberEventLoop instalado com sucesso!\n";
echo "Versão do PHP: " . PHP_VERSION . "\n";

Início Rápido

1️⃣ Hello World Assíncrono

<?php

require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

$loop = new FiberEventLoop();

// Executa após 1 segundo
$loop->after(function() {
    echo "Hello, async world! 🚀\n";
}, 1.0);

$loop->run();

Output:
Hello, async world! 🚀

2️⃣ Timer Recorrente

<?php

require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

$loop = new FiberEventLoop();
$count = 0;

// Executa a cada 500ms por 5 vezes
$loop->repeat(0.5, function() use (&$count) {
    echo "Tick #" . (++$count) . " em " . date('H:i:s.u') . "\n";
}, times: 5);

// Para o loop após 3 segundos
$loop->after(fn() => $loop->stop(), 3.0);

$loop->run();

3️⃣ TCP Echo Server

<?php

require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

$loop = new FiberEventLoop();

// Cria servidor TCP
$server = stream_socket_server('tcp://0.0.0.0:8080', $errno, $errstr);
if (!$server) {
    die("Erro: $errstr ($errno)\n");
}

stream_set_blocking($server, false);

echo "🚀 Servidor echo em tcp://0.0.0.0:8080\n";
echo "Teste com: nc localhost 8080\n\n";

// Aceita conexões
$loop->listen($server, function($client) use ($loop) {
    $remoteAddr = stream_socket_get_name($client, true);
    echo "✅ Nova conexão de $remoteAddr\n";
    
    // Lê dados do cliente
    $loop->onReadable($client, function($data) use ($client, $loop, $remoteAddr) {
        if ($data === '') {
            // Conexão fechada
            fclose($client);
            echo "❌ Conexão fechada de $remoteAddr\n";
            return;
        }
        
        echo "📨 Recebido de $remoteAddr: " . trim($data) . "\n";
        
        // Echo de volta
        $loop->onWritable($client, "Echo: $data", function($written, $total) use ($remoteAddr) {
            echo "📤 Enviado para $remoteAddr: $written/$total bytes\n";
        });
    });
});

$loop->run();
fclose($server);

Guia Completo

Timers e Scheduling

after(callable $callback, float|int $seconds): int

Executa um callback uma única vez após o tempo especificado.

// Timeout simples
$timerId = $loop->after(function() {
    echo "Executado após 2.5 segundos\n";
}, 2.5);

// Pode ser cancelado antes de executar
if ($someCondition) {
    $loop->cancel($timerId);
}

// Retorna o ID para referência
echo "Timer ID: $timerId\n";

Casos de uso:

• Timeouts em operações
• Agendamentos únicos
• Delays entre ações

repeat(float|int $interval, callable $callback, ?int $times = null): int

Executa um callback repetidamente em intervalos regulares.

// Infinitamente
$repeatId = $loop->repeat(1.0, function() {
    echo "Executado a cada 1 segundo\n";
});

// Número limitado de vezes
$loop->repeat(0.5, function() {
    echo "Executado 10 vezes\n";
}, times: 10);

// Pode ser cancelado
$loop->after(fn() => $loop->cancel($repeatId), 5.0);

Exemplo: Monitoramento de saúde

$loop->repeat(30.0, function() {
    $health = checkSystemHealth();
    
    if (!$health['ok']) {
        logAlert("Sistema degradado: " . $health['message']);
    }
    
    echo "[" . date('H:i:s') . "] Status: " . ($health['ok'] ? 'OK' : 'ERRO') . "\n";
});

sleep(float|int $seconds): void

Sleep não-bloqueante que suspende a Fiber atual sem bloquear o event loop.

⚠️ Importante: Só funciona dentro de uma Fiber (via repeat(), onWritable(), onReadFile() ou dentro de um contexto de Fiber).

// ❌ NÃO FUNCIONA (não está em uma Fiber)
$loop->sleep(1.0);
echo "Isso não executa!\n";

// ✅ FUNCIONA (está em um repeat())
$loop->repeat(5.0, function() use ($loop) {
    echo "Iniciando operação...\n";
    $loop->sleep(2.0); // Suspende por 2s sem bloquear
    echo "Operação completa!\n";
});

Exemplo: Retry com backoff exponencial

$loop->defer(function() use ($loop, $apiUrl) {
    for ($attempt = 1; $attempt <= 3; $attempt++) {
        try {
            $response = fetchFromAPI($apiUrl);
            echo "✅ Sucesso na tentativa $attempt\n";
            return;
        } catch (Exception $e) {
            if ($attempt < 3) {
                $wait = pow(2, $attempt); // 2s, 4s
                echo "⏳ Tentativa $attempt falhou, aguardando ${wait}s...\n";
                $loop->sleep($wait);
            } else {
                echo "❌ Todas as tentativas falharam\n";
                throw $e;
            }
        }
    }
});

TCP Streams

listen(resource $server, callable $callback): int

Monitora um socket servidor para aceitar novas conexões TCP.

// Cria um servidor TCP
$server = stream_socket_server('tcp://0.0.0.0:9000', $errno, $errstr);
if (!$server) {
    throw new Exception("Erro: $errstr ($errno)");
}

// Monitora o servidor
$loop->listen($server, function($client) {
    $remoteAddr = stream_socket_get_name($client, true);
    echo "Nova conexão de: $remoteAddr\n";
    
    // $client é um recurso stream já não-bloqueante
});

Exemplo: Multi-cliente com controle

$clients = new \SplObjectStorage();

$loop->listen($server, function($client) use ($loop, $clients) {
    $clients->attach($client, [
        'addr' => stream_socket_get_name($client, true),
        'created_at' => time(),
    ]);
    
    echo "Total de clientes: " . count($clients) . "\n";
    
    // Monitora para leitura
    $loop->onReadable($client, function($data) use ($client, $clients, $loop) {
        if ($data === '') {
            $info = $clients[$client];
            $clients->detach($client);
            fclose($client);
            echo "Cliente desconectou: " . $info['addr'] . "\n";
            return;
        }
        
        // ... processar dados
    });
});

onReadable(resource $stream, callable $callback, int $length = 8192): int

Monitora um stream para ler dados quando disponível.

$loop->onReadable($client, function($data) {
    if ($data === '') {
        // String vazia = EOF (conexão fechada)
        fclose($client);
        echo "Conexão fechada\n";
        return;
    }
    
    echo "Dados: " . strlen($data) . " bytes\n";
    echo "Conteúdo: " . substr($data, 0, 100) . "\n";
}, length: 4096);

O callback recebe:

• $data (string): Dados lidos
  • String vazia = EOF
  • Até $length bytes por chamada

Exemplo: Protocolo simples (CRLF-terminated)

static $buffer = '';

$loop->onReadable($client, function($data) use ($client, $loop) {
    global $buffer;
    
    if ($data === '') {
        fclose($client);
        return;
    }
    
    $buffer .= $data;
    
    // Processa linhas completas
    while (($pos = strpos($buffer, "\r\n")) !== false) {
        $line = substr($buffer, 0, $pos);
        $buffer = substr($buffer, $pos + 2);
        
        echo "Linha: $line\n";
        
        // Responde
        $loop->onWritable($client, "OK\r\n", fn() => null);
    }
});

onWritable(resource $stream, string $data, callable $callback, bool $blocking = false): int

Escreve dados em um stream de forma assíncrona e eficiente.

$loop->onWritable($client, "Dados para enviar", function($written, $total) {
    echo "Progresso: $written/$total bytes\n";
    
    if ($written === $total) {
        echo "Envio completado!\n";
    }
});

O callback recebe:

• $written (int): Bytes escritos nesta iteração
• $total (int): Total de bytes para escrever

Exemplo: Envio de arquivo grande

$filePath = 'large-file.bin';
$fileSize = filesize($filePath);

// Lê o arquivo em chunks
$data = file_get_contents($filePath);

// Envia para o cliente
$loop->onWritable($client, $data, function($written, $total) use ($client) {
    $percent = round(($written / $total) * 100, 2);
    echo "Transferência: $percent% ($written/$total bytes)\n";
    
    if ($written === $total) {
        echo "✅ Arquivo transferido com sucesso\n";
    }
});

Leitura de Arquivos

onReadFile(string $filename, callable $callback, bool $blocking = false, int $length = 8192): int

Lê um arquivo assincronamente em chunks sem bloquear o loop.

$loop->onReadFile('data.csv', function($chunk) {
    echo "Chunk: " . strlen($chunk) . " bytes\n";
    // Processa o chunk
}, length: 16384);

O callback recebe:

• $chunk (string): Até $length bytes do arquivo
• Última chamada: $chunk pode ser menor

Exemplo: Processamento de CSV gigante

$rows = [];
$totalSize = 0;
$startTime = microtime(true);

$loop->onReadFile('data.csv', function($chunk) use (&$rows, &$totalSize) {
    static $buffer = '';
    
    $buffer .= $chunk;
    $totalSize += strlen($chunk);
    
    // Processa linhas completas
    $lines = explode("\n", $buffer);
    
    for ($i = 0; $i < count($lines) - 1; $i++) {
        $rows[] = str_getcsv(trim($lines[$i]));
    }
    
    // Mantém última linha incompleta
    $buffer = $lines[count($lines) - 1];
    
    echo "Processadas " . count($rows) . " linhas...\n";
}, length: 65536); // 64KB chunks

$loop->after(function() use (&$rows, &$totalSize, $startTime) {
    $elapsed = microtime(true) - $startTime;
    $throughput = $totalSize / 1024 / 1024 / $elapsed;
    
    echo "✅ Processamento completo!\n";
    echo "Linhas: " . count($rows) . "\n";
    echo "Throughput: " . round($throughput, 2) . " MB/s\n";
}, 0.1);

$loop->run();

Fibers e Concorrência

defer(callable $callback): int

Agenda um callback simples para próxima iteração (máxima performance).

// Ultra-rápido para operações triviais
$loop->defer(function() {
    echo "Executado na próxima iteração\n";
});

// Múltiplas operações defer
for ($i = 1; $i <= 1000; $i++) {
    $loop->defer(fn() => processItem($i));
}

Quando usar defer vs repeat:

• defer(): Operações que não precisam ser repetidas
• repeat(): Operações periódicas ou que usam sleep()

cancel(int $id): void

Cancela uma operação agendada (timer, stream, etc).

// Agenda uma operação
$timerId = $loop->after(fn() => echo "Nunca executa\n", 10.0);

// Cancela antes de executar
$loop->after(function() use ($loop, $timerId) {
    $loop->cancel($timerId);
    echo "Timer cancelado!\n";
}, 1.0);

Operações que podem ser canceladas:

• ✅ Timers (after, repeat)
• ✅ Streams (listen, onReadable, onWritable)
• ✅ Arquivos (onReadFile)
• ✅ Deferred callbacks

Gerenciamento de Erros

getErrors(): array

Retorna todos os erros capturados durante a execução.

$loop->run();

$errors = $loop->getErrors();

foreach ($errors as $id => $errorMessage) {
    echo "Erro ID $id: $errorMessage\n";
}

Exemplo: Error logging

$loop->repeat(5.0, function() {
    // Operação que pode falhar
    throw new Exception("Algo deu errado!");
});

$loop->after(function() use ($loop) {
    $loop->stop();
}, 6.0);

try {
    $loop->run();
} finally {
    $errors = $loop->getErrors();
    
    if (!empty($errors)) {
        echo "⚠️ Erros detectados durante execução:\n";
        foreach ($errors as $id => $error) {
            echo "  [$id] $error\n";
        }
    }
}

Otimizações de Performance

setOptimizationLevel(string $level): void

Ajusta o comportamento do loop para diferentes cenários.

// Latência mínima (máximo CPU)
$loop->setOptimizationLevel('latency');

// Throughput máximo (equilibrado)
$loop->setOptimizationLevel('throughput');

// Economia de CPU
$loop->setOptimizationLevel('efficient');

// Balanceado (padrão)
$loop->setOptimizationLevel('balanced');

// Otimizado para benchmarks
$loop->setOptimizationLevel('benchmark');

Comparação de modos:

getMetrics(): array

Obtém métricas de performance do loop.

$loop->run();

$metrics = $loop->getMetrics();

echo "Iterações totais: " . $metrics['iterations'] . "\n";
echo "Iterações ociosas: " . $metrics['empty_iterations'] . "\n";
echo "Ciclos com trabalho: " . $metrics['work_cycles'] . "\n";
echo "Tempo médio por ciclo: " . $metrics['last_work_time'] . "s\n";

Exemplos Práticos

1. Chat Server Multi-Cliente

<?php

require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

$loop = new FiberEventLoop();
$clients = [];

$server = stream_socket_server('tcp://0.0.0.0:9999');
stream_set_blocking($server, false);

echo "💬 Chat Server em tcp://0.0.0.0:9999\n";
echo "Teste com: nc localhost 9999\n\n";

$loop->listen($server, function($client) use ($loop, &$clients) {
    $id = (int)$client;
    $addr = stream_socket_get_name($client, true);
    $clients[$id] = ['client' => $client, 'addr' => $addr];
    
    echo "✅ [{$addr}] conectado. Total: " . count($clients) . "\n";
    
    // Broadcast de entrada
    broadcastToAll("[$addr entrou no chat]\n", $clients, $id);
    
    // Monitora mensagens
    $loop->onReadable($client, function($data) use ($id, $addr, &$clients, $loop) {
        if ($data === '') {
            // Desconexão
            fclose($clients[$id]['client']);
            unset($clients[$id]);
            
            echo "❌ [{$addr}] desconectado. Total: " . count($clients) . "\n";
            broadcastToAll("[$addr saiu do chat]\n", $clients);
            return;
        }
        
        $msg = trim($data);
        echo "💬 [{$addr}] {$msg}\n";
        
        // Broadcast para todos
        broadcastToAll("[$addr] $msg\n", $clients, $id, $loop);
    });
});

function broadcastToAll($msg, &$clients, $except = null, $loop = null) {
    foreach ($clients as $clientId => $info) {
        if ($clientId !== $except) {
            if ($loop) {
                $loop->onWritable($info['client'], $msg, fn() => null);
            } else {
                fwrite($info['client'], $msg);
            }
        }
    }
}

$loop->run();

2. HTTP Server Básico

<?php

require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

$loop = new FiberEventLoop();
$requestCount = 0;

$server = stream_socket_server('tcp://0.0.0.0:8000');
stream_set_blocking($server, false);

echo "🌐 HTTP Server em http://0.0.0.0:8000\n";
echo "Teste com: curl http://localhost:8000\n\n";

$loop->listen($server, function($client) use ($loop, &$requestCount) {
    $buffer = '';
    $headersParsed = false;
    
    $loop->onReadable($client, function($data) use (&$buffer, &$headersParsed, $client, $loop, &$requestCount) {
        if ($data === '') {
            fclose($client);
            return;
        }
        
        $buffer .= $data;
        
        // Verifica se recebeu headers completos
        if (!$headersParsed && strpos($buffer, "\r\n\r\n") !== false) {
            $headersParsed = true;
            
            // Parse da requisição
            $lines = explode("\r\n", $buffer);
            $requestLine = $lines[0];
            list($method, $path) = explode(' ', $requestLine);
            
            $requestCount++;
            
            // Monta resposta HTTP
            $body = json_encode([
                'status' => 'ok',
                'request_count' => $requestCount,
                'timestamp' => date('c'),
                'method' => $method,
                'path' => $path,
            ], JSON_PRETTY_PRINT);
            
            $response = "HTTP/1.1 200 OK\r\n";
            $response .= "Content-Type: application/json\r\n";
            $response .= "Content-Length: " . strlen($body) . "\r\n";
            $response .= "Connection: close\r\n";
            $response .= "\r\n";
            $response .= $body;
            
            // Envia resposta
            $loop->onWritable($client, $response, function($written, $total) use ($client) {
                if ($written === $total) {
                    fclose($client);
                }
            });
        }
    });
});

// Mostra estatísticas a cada 10 segundos
$loop->repeat(10.0, function() use (&$requestCount) {
    echo "[" . date('H:i:s') . "] Requisições: " . $requestCount . "\n";
});

$loop->run();

3. Task Scheduler (Cron-like)

<?php

require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

$loop = new FiberEventLoop();

class TaskScheduler {
    private FiberEventLoop $loop;
    private array $tasks = [];
    
    public function __construct(FiberEventLoop $loop) {
        $this->loop = $loop;
    }
    
    public function schedule($name, $interval, callable $callback, $times = null) {
        $this->tasks[$name] = $this->loop->repeat($interval, function() use ($name, $callback) {
            echo "[" . date('Y-m-d H:i:s') . "] Executando: $name\n";
            try {
                $callback();
            } catch (Exception $e) {
                echo "❌ Erro em $name: " . $e->getMessage() . "\n";
            }
        }, $times);
    }
    
    public function stop($name) {
        if (isset($this->tasks[$name])) {
            $this->loop->cancel($this->tasks[$name]);
            unset($this->tasks[$name]);
        }
    }
}

$scheduler = new TaskScheduler($loop);

// Tarefas agendadas
$scheduler->schedule('Backup', 300.0, function() {
    // Executa backup a cada 5 minutos
    echo "  💾 Backup realizado\n";
});

$scheduler->schedule('Email', 60.0, function() {
    // Verifica emails a cada 1 minuto
    echo "  📧 Verificação de emails\n";
});

$scheduler->schedule('Cleanup', 3600.0, function() {
    // Limpeza a cada 1 hora
    echo "  🧹 Limpeza de cache\n";
});

$scheduler->schedule('Health Check', 30.0, function() {
    // Verifica saúde a cada 30s
    echo "  ❤️ Health check OK\n";
});

echo "⏰ Task Scheduler iniciado\n";
$loop->run();

4. File Watcher

<?php

require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

$loop = new FiberEventLoop();
$watched = [];
$lastModified = [];

function getFileHash($file) {
    return md5(file_get_contents($file));
}

$loop->repeat(1.0, function() use (&$watched, &$lastModified, $loop) {
    $files = glob('src/**/*.php');
    
    foreach ($files as $file) {
        $mtime = filemtime($file);
        $hash = getFileHash($file);
        
        if (!isset($lastModified[$file])) {
            $lastModified[$file] = $hash;
            $watched[] = $file;
            continue;
        }
        
        if ($hash !== $lastModified[$file]) {
            echo "🔄 Modificado: $file\n";
            $lastModified[$file] = $hash;
            
            // Executa ação (ex: testes)
            $loop->defer(function() use ($file) {
                echo "  ▶️ Executando testes...\n";
                // exec('phpunit --filter "FileTest"');
            });
        }
    }
});

echo "👁️ File Watcher ativo\n";
$loop->run();

5. Scrapy de URLs em Paralelo

<?php

require 'vendor/autoload.php';

use Omegaalfa\FiberEventLoop\FiberEventLoop;

$loop = new FiberEventLoop();
$loop->setOptimizationLevel('throughput');

$urls = [
    'https://example.com',
    'https://github.com',
    'https://php.net',
    // ... mais URLs
];

$results = [];
$completed = 0;
$startTime = microtime(true);

foreach ($urls as $url) {
    $loop->defer(function() use ($url, $loop, &$results, &$completed) {
        try {
            $context = stream_context_create([
                'http' => [
                    'timeout' => 10,
                    'method' => 'GET',
                    'user_agent' => 'Mozilla/5.0 (FiberEventLoop)',
                ]
            ]);
            
            $content = @file_get_contents($url, false, $context);
            $size = strlen($content ?? '');
            
            preg_match('/<title>(.*?)<\/title>/i', $content ?? '', $matches);
            $title = $matches[1] ?? 'N/A';
            
            $results[$url] = [
                'status' => 'ok',
                'size' => $size,
                'title' => $title,
            ];
            
            echo "✅ {$url}\n";
        } catch (Exception $e) {
            $results[$url] = [
                'status' => 'error',
                'error' => $e->getMessage(),
            ];
            
            echo "❌ {$url}: " . $e->getMessage() . "\n";
        }
        
        $completed++;
    });
}

// Para o loop quando todos terminar
$loop->repeat(0.1, function() use ($loop, &$completed, $urls, &$startTime) {
    $percent = round(($completed / count($urls)) * 100);
    $elapsed = microtime(true) - $startTime;
    
    echo "\r📊 Progresso: {$percent}% ({$completed}/" . count($urls) . ") em {$elapsed}s    ";
    
    if ($completed === count($urls)) {
        $loop->stop();
    }
});

$loop->run();

// Exibe resultados
echo "\n\n=== Resultados ===\n\n";
foreach ($results as $url => $result) {
    if ($result['status'] === 'ok') {
        echo "✅ {$url}\n";
        echo "   Título: {$result['title']}\n";
        echo "   Tamanho: " . number_format($result['size'], 0) . " bytes\n";
    } else {
        echo "❌ {$url}\n";
        echo "   Erro: {$result['error']}\n";
    }
}

echo "\n⏱️ Total: " . round(microtime(true) - $startTime, 2) . "s\n";

API Reference Completa

FiberEventLoop

class FiberEventLoop
{
    // ============ TIMERS ============
    
    /**
     * Executa callback uma vez após N segundos
     */
    public function after(callable $callback, float|int $seconds): int;
    
    /**
     * Executa callback repetidamente a cada N segundos
     */
    public function repeat(
        float|int $interval, 
        callable $callback, 
        ?int $times = null
    ): int;
    
    /**
     * Sleep não-bloqueante (apenas em Fibers)
     */
    public function sleep(float|int $seconds): void;
    
    // ============ STREAMS TCP ============
    
    /**
     * Monitora servidor para aceitar conexões
     */
    public function listen(mixed $server, callable $callback): int;
    
    /**
     * Monitora stream para leitura de dados
     */
    public function onReadable(
        mixed $stream, 
        callable $callback, 
        int $length = 8192
    ): int;
    
    /**
     * Escreve dados em stream (não-bloqueante)
     */
    public function onWritable(
        mixed $stream, 
        string $data, 
        callable $callback, 
        bool $blocking = false
    ): int;
    
    // ============ FILE I/O ============
    
    /**
     * Lê arquivo assincronamente
     */
    public function onReadFile(
        string $filename, 
        callable $callback, 
        bool $blocking = false, 
        int $length = 8192
    ): int;
    
    // ============ CONTROL ============
    
    /**
     * Agenda callback para próxima iteração
     */
    public function defer(callable $callback): int;
    
    /**
     * Cancela operação por ID
     */
    public function cancel(int $id): void;
    
    /**
     * Inicia event loop (bloqueia até terminar)
     */
    public function run(): void;
    
    /**
     * Para o event loop gracefully
     */
    public function stop(): void;
    
    // ============ OBSERVABILITY ============
    
    /**
     * Retorna erros capturados durante execução
     */
    public function getErrors(): array;
    
    /**
     * Retorna métricas de performance
     */
    public function getMetrics(): array;
    
    /**
     * Ajusta otimizações de performance
     * 'latency', 'throughput', 'efficient', 'balanced', 'benchmark'
     */
    public function setOptimizationLevel(string $level): void;
}

Troubleshooting

❓ "Fatal error: Uncaught Fiber::suspend() outside of a Fiber"

Causa: Tentando usar sleep() fora de uma Fiber.

Solução:

// ❌ Errado
$loop->sleep(1.0);

// ✅ Correto
$loop->repeat(5.0, function() use ($loop) {
    $loop->sleep(1.0);
});

// ✅ Também funciona
$loop->onWritable($client, $data, function() {
    // Está automaticamente em uma Fiber
});

❓ "Resource warning: stream closed"

Causa: Tentando usar stream após fechamento.

Solução:

// ❌ Errado
fclose($client);
$loop->onReadable($client, function($data) {}); // Erro!

// ✅ Correto
$loop->onReadable($client, function($data) use ($client) {
    if ($data === '') {
        fclose($client); // Fecha no callback
        return;
    }
});

❓ "Loop não para ou trava"

Causa: Operações infinitas sem yield.

Solução:

// ❌ Errado - Loop infinito
$loop->defer(function() {
    while (true) {
        // Bloqueia o loop!
    }
});

// ✅ Correto
$loop->repeat(1.0, function() {
    // Executa a cada 1 segundo
});

❓ "Alto uso de CPU"

Causa: Idle adaptativo desabilitado ou threshold muito alto.

Solução:

// Modo eficiente (reduz CPU)
$loop->setOptimizationLevel('efficient');

// Ou manual
$loop->setOptimizationLevel('balanced');

Contribuindo

Contribuições são bem-vindas! Siga os passos:

1. Fork o repositório
2. Crie uma branch (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -m 'Add: nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um PR com descrição detalhada

Diretrizes

• ✅ Siga PSR-12
• ✅ Adicione testes para novas features
• ✅ Documente com PHPDoc
• ✅ Mantenha compatibilidade com PHP 8.2+
• ✅ Rode composer test antes de fazer commit

Licença

Este projeto está licenciado sob a Licença MIT. Veja LICENSE para detalhes.

📞 Suporte & Links

• 🐛 Issues: GitHub Issues
• 💬 Discussões: GitHub Discussions
• 📚 Docs: PHP Fibers
• 🔗 Composer: Packagist

Feito com ❤️ por OmegaAlfa

_{⭐ Se este projeto foi útil, considere dar uma estrela!}