# Töövoo tühistamine

Töövooge saab tühistada programmiliselt või funktsiooni CLI kaudu. Töövoo tühistamisel seab Queuety selle olekuks `cancelled`, matab kõik ootel või töötlemisel olevad tööd ning käivitab valikulise puhastuskäitleja.

## Puhastuskäitleja registreerimine

Kasuta töövoo koostajal `on_cancel()`, et registreerida klass, mis käivitub töövoo tühistamisel. Käitlejaklass peab rakendama meetodi `handle( array $state ): void`.

```php
use Queuety\Queuety;

Queuety::workflow( 'import_data' )
    ->then( FetchDataHandler::class )
    ->then( TransformDataHandler::class )
    ->then( LoadDataHandler::class )
    ->on_cancel( ImportCleanupHandler::class )
    ->dispatch( [ 'source_url' => $url ] );
```

Puhastuskäitleja saab avaliku töövoo oleku (kõik võtmed, mis ei alga märgiga `_`):

```php
class ImportCleanupHandler {

    public function handle( array $state ): void {
        // Clean up any partial imports.
        if ( isset( $state['temp_table'] ) ) {
            global $wpdb;
            $wpdb->query( "DROP TABLE IF EXISTS {$state['temp_table']}" );
        }

        // Notify the user.
        wp_mail(
            $state['notify_email'] ?? '',
            'Import cancelled',
            'Your data import was cancelled.'
        );
    }
}
```

## Tühistamine funktsiooni PHP kaudu

Kutsu välja `Queuety::cancel_workflow()` koos töövoo ID-ga:

```php
Queuety::cancel_workflow( $workflow_id );
```

See meetod teeb järgmist:

1. Lukustab töövoo rea
2. Seab töövoo olekuks `cancelled`
3. Matab kõik töövoo ootel ja töötlemisel olevad tööd sõnumiga "Töövoog tühistatud"
4. Logib sündmuse `workflow_cancelled` ja kinnitab muudatused
5. Käivitab lõpetatud sammude kompensatsioonid vastupidises järjekorras (kui need on registreeritud funktsiooniga `compensate_with()`)
6. Käivitab puhastuskäitleja `on_cancel` (kui see on registreeritud)

Kui töövoog on juba olekus `completed` või `cancelled`, visatakse `RuntimeException`.

## Tühistamine funktsiooni CLI kaudu

```bash
wp queuety workflow cancel <id>
```

| Suvand | Kirjeldus |
|---|---|
| `<id>` | Tühistatava töövoo ID (nõutav) |

```bash
wp queuety workflow cancel 42
```

## Mis juhtub tühistamisel

Töövoo tühistamisel:

- **Olek** muutub olekuks `cancelled`
- **Sammude kompensatsioonid** käivitatakse lõpetamise järjekorra pöördjärjestuses, kui lisasid need funktsiooniga `compensate_with()`
- **Puhastuskäitleja** käivitub pärast töövoo rea olekusse `cancelled` märkimist
- Töövoo **ootel tööd** maetakse kohe
- Töövoo **töötlemisel olevad tööd** maetakse; kui pooleli olev käitleja lõpetab, visatakse selle väljund ära ja töövoog ei jätku
- Varasemate sammude **lõpetatud tööd** jäävad muutmata
- Salvestatakse **logikirje** sündmusega `workflow_cancelled`

## Tühistatud ja nurjunud töövoog

| Aspekt | Nurjunud | Tühistatud |
|---|---|---|
| Käivitaja | Samm ammendab korduskatsed | Otsene `cancel_workflow()` väljakutse |
| Olek | `failed` | `cancelled` |
| Kas saab uuesti proovida | Jah, funktsiooniga `retry_workflow()`, välja arvatud juhul, kui töövoo kompensatsioonid on juba käivitatud | Ei |
| Puhastuskäitleja | Ei käivitata | Käivitatakse, kui see on registreeritud funktsiooniga `on_cancel()` |
| Logisündmus | `workflow_failed` | `workflow_cancelled` |

## Näide: tühistamine kinnitusega

Levinud muster on kontrollida enne tühistamist töövoo olekut:

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

if ( null === $status ) {
    throw new \RuntimeException( 'Workflow not found.' );
}

if ( 'running' === $status->status->value || 'paused' === $status->status->value ) {
    Queuety::cancel_workflow( $workflow_id );
}
```