Architettura Async\Pool ​

Questo articolo descrive la progettazione interna del pool di risorse universale. Se stai cercando una guida all'uso, vedi Async\Pool. Per il livello specifico PDO, vedi Architettura PDO Pool.

Struttura Dati ​

Il pool è implementato in due livelli: una struttura ABI pubblica nel core PHP e una struttura interna estesa nell'estensione async.

Due Percorsi di Creazione ​

Un pool può essere creato dal codice PHP (tramite il costruttore Async\Pool) o da un'estensione C (tramite l'API interna).

La differenza sta in handler_flags. Quando il flag è impostato, il pool chiama la funzione C direttamente, bypassando l'overhead della chiamata di un callable PHP attraverso zend_call_function().

Acquire: Ottenere una Risorsa ​

Attesa di una Risorsa ​

Quando tutte le risorse sono occupate e max_size è raggiunto, la coroutine si sospende tramite ZEND_ASYNC_SUSPEND(). Il meccanismo di attesa è simile ai canali:

1. Viene creata una struttura zend_async_pool_waiter_t
2. Il waiter viene aggiunto alla coda FIFO waiters
3. Viene registrato un callback per il risveglio
4. Se è impostato un timeout -- viene registrato un timer
5. ZEND_ASYNC_SUSPEND() -- la coroutine cede il controllo

Il risveglio avviene quando un'altra coroutine chiama release().

Release: Restituire una Risorsa ​

Healthcheck: Monitoraggio in Background ​

Se healthcheckInterval > 0, viene avviato un timer periodico quando il pool viene creato. Il timer è integrato con il reactor tramite ZEND_ASYNC_NEW_TIMER_EVENT.

L'healthcheck verifica solo le risorse libere. Le risorse occupate non sono interessate. Se, dopo la rimozione delle risorse morte, il conteggio totale scende sotto min, il pool crea sostituzioni.

Buffer Circolare ​

Le risorse libere sono memorizzate in un buffer circolare -- un ring buffer con capacità fissa. La capacità iniziale è di 8 elementi, espandibile secondo necessità.

Le operazioni push e pop vengono eseguite in O(1). Il buffer utilizza due puntatori (head e tail), consentendo l'aggiunta e l'estrazione efficienti delle risorse senza spostare elementi.

Integrazione con il Sistema di Eventi ​

Il pool eredita da zend_async_event_t e implementa un set completo di handler per gli eventi:

Questo consente:

• Sospendere e riprendere le coroutine tramite callback degli eventi
• Integrare il timer di healthcheck con il reactor
• Rilasciare correttamente le risorse attraverso la disposizione degli eventi

Garbage Collection ​

Il wrapper PHP del pool (async_pool_obj_t) implementa un get_gc personalizzato che registra tutte le risorse dal buffer idle come radici GC. Questo previene la raccolta prematura delle risorse libere che non hanno riferimenti espliciti dal codice PHP.

Circuit Breaker ​

Il pool implementa l'interfaccia CircuitBreaker con tre stati:

Le transizioni possono essere manuali o automatiche tramite CircuitBreakerStrategy:

• reportSuccess() viene chiamato su un release riuscito (la risorsa ha passato beforeRelease)
• reportFailure() viene chiamato quando beforeRelease ha restituito false
• La strategia decide quando cambiare stato

Close: Chiusura del Pool ​

Quando il pool viene chiuso:

1. L'evento del pool viene contrassegnato come CLOSED
2. Il timer di healthcheck viene fermato
3. Tutte le coroutine in attesa vengono svegliate con una PoolException
4. Tutte le risorse libere vengono distrutte tramite destructor
5. Le risorse occupate continuano a vivere -- verranno distrutte al release

API C per le Estensioni ​

Le estensioni (PDO, Redis, ecc.) utilizzano il pool attraverso macro:

Tutte le macro chiamano puntatori a funzione registrati dall'estensione async al momento del caricamento. Questo garantisce l'isolamento: il core PHP non dipende dall'implementazione specifica del pool.

Sequenza: Ciclo Completo Acquire-Release ​

Prossimi Passi ​

• Async\Pool: Guida -- come usare il pool
• Architettura PDO Pool -- livello specifico PDO
• Coroutine -- come funzionano le coroutine