# Töövoogude tähtajad

Töövoogudele saab määrata tähtaja. Kui töötav töövoog ei jõua määratud aja jooksul lõpule, märgib Queuety selle nurjunuks ja kutsub soovi korral välja käsitleja. Peatatud töövood ning signaali või teiste töövoogude ootel töövood ei aegu ootamise ajal. Tähtaegu kontrollib umbes kord minutis kaua töötav `wp queuety work` protsess, mitte `--once` töötajad ega WP-Cron tagavarakäitlus. See toimib kaua töötavate töövoogude katkestina, et need ei töötaks lõputult.

## Tähtaja määramine

Kasuta töövoo koostajal `must_complete_within()`, et määrata maksimaalne lubatud kestus. Kasuta `on_deadline()`, et registreerida käsitleja, mis käivitub tähtaja ületamisel.

```php
use Queuety\Queuety;

Queuety::workflow( 'data_import' )
    ->then( FetchDataHandler::class )
    ->then( TransformDataHandler::class )
    ->then( LoadDataHandler::class )
    ->must_complete_within( hours: 24 )
    ->on_deadline( ImportTimeoutHandler::class )
    ->dispatch( [ 'source' => $url ] );
```

Meetod `must_complete_within()` võtab vastu nimelised parameetrid, mille väärtused liidetakse kokku:

```php
->must_complete_within( hours: 2, minutes: 30 )  // 2.5 hours
->must_complete_within( days: 1 )                 // 24 hours
->must_complete_within( seconds: 3600 )           // 1 hour
->must_complete_within( days: 1, hours: 12 )      // 36 hours
```

## Tähtaja käsitleja

Käsitlejaklass `on_deadline()` peab rakendama meetodi `handle( array $state ): void`. See saab töövoo avaliku oleku (kõik võtmed, mis ei alga märgiga `_`).

```php
class ImportTimeoutHandler {

    public function handle( array $state ): void {
        // Alert the team.
        wp_mail(
            'ops@example.com',
            'Import workflow timed out',
            'Workflow for source ' . ( $state['source'] ?? 'unknown' ) . ' exceeded its deadline.'
        );

        // Clean up partial work.
        if ( isset( $state['temp_file'] ) ) {
            unlink( $state['temp_file'] );
        }
    }
}
```

Tähtaja käsitleja on valikuline. Kui soovid, et töövoog lihtsalt nurjuks ilma kohandatud loogikat käivitamata, kasuta `must_complete_within()` ilma parameetrita `on_deadline()`.

## Kuidas tähtaja kontrollimine toimib

Töötaja kontrollib aegunud tähtaegu iga 60 sekundi järel töötlemistsükli käigus. Kui ta leiab töövoo, mille `status` on endiselt `running` ja mille `deadline_at` on minevikus, kutsub ta registreeritud `on_deadline` käsitleja, märgib töövoo nurjunuks veateatega `Deadline exceeded` ning salvestab `workflow_deadline_exceeded` logisündmuse. Tähtaeg talletatakse töövoo rea ajatemplina `deadline_at` ja arvutatakse töö käivitamisel seadistatud kestuse põhjal.

## Mis juhtub tähtaja saabumisel

Tähtaja ületamisel muutub töövoo olekuks `failed`, veateateks määratakse `Deadline exceeded`, registreeritud tähtaja käsitleja käivitatakse sünkroonselt ning salvestatakse `workflow_deadline_exceeded` logikirje. Töötavaid töid ei katkestata keset käivitamist, kuid töövoog ei liigu aegunud sammu piirist edasi. Kui tähtaja käsitleja ise tekitab erindi, püütakse see vaikselt kinni ja töövoog jääb siiski nurjunuks.

## WorkflowBuilderi meetodid

| Meetod | Kirjeldus |
|---|---|
| `must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | Määrab maksimaalse lubatud kestuse. Kõik parameetrid liidetakse kokku. |
| `on_deadline( string $handler_class )` | Registreerib käsitleja, mis kutsutakse välja tähtaja ületamisel. |

## Näide: tähtaja järel uuesti proovimine

Tähtaja ületamise tõttu nurjunud töövoogu tasub harva uuesti proovida. `retry_workflow()` lähtestab selle olekusse `running` ja lisab nurjunud sammu uuesti järjekorda, kuid ei tühjenda ega pikenda tähtaega, nii et järgmine tähtajakontroll nurjab selle umbes minuti jooksul uuesti. Käivita selle asemel uus töövoog.

```php
$status = Queuety::workflow_status( $workflow_id );

if ( 'failed' === $status->status->value ) {
    // Check if it was a deadline failure.
    // You may want to dispatch a new workflow instead of retrying.
    Queuety::retry_workflow( $workflow_id );
}
```

## Tähtaeg ja ooteviivitused

Tähtaeg kehtib kogu töövoo kestusele. Ooteviivitused (`->delay()`) peatavad töövoo kindlaks ajaks osana selle sammujadast. Ühetunnise ooteviivituse ja kahetunnise tähtajaga töövoog nurjub, kui unevälised sammud kestavad kokku üle ühe tunni.