`Ctrl`+`K`

# 7.3.53. `request_cancel`

## 7.3.53.1. 概要

バージョン 4.0.9 で追加.

`request_cancel` コマンドは実行中のリクエストをキャンセルします。

いくつか制限があります。

> - リクエストIDはユーザーが管理する必要があります。（各リクエストに一意のキーを割り当てる必要があります。）

> - キャンセルリクエストは無視されることもあります。（同じリクエストIDに対して何度も `request_cancel` コマンドを送信することができます。）

> - マルチスレッド型のGroongaサーバーのみサポートしています。（ groonga 実行ファイル ベースのサーバーでは使えますが、 groonga-httpd では使えません。）

リクエストIDについては リクエストID を参照してください。

リクエストがキャンセルされたら、キャンセルされたリクエストの リターンコード は、以下のようになります。

> - `-5` (`GRN_INTERRUPTED_FUNCTION_CALL`) (Groonga version 6.0.1 より前)

> - `-77` (`GRN_CANCEL`) (Groonga version 6.0.1 以降)

## 7.3.53.2. 構文

このコマンドの引数は1つで必須です:

    request_cancel id

## 7.3.53.3. 使い方

以下は `request_cancel` コマンドの使用例です:

    $ curl 'http://localhost:10041/d/select?table=LargeTable&filter=true&request_id=unique-id-1' &
    # The above "select" takes a long time...
    # Point: "request_id=unique-id-1"
    $ curl 'http://localhost:10041/d/request_cancel?id=unique-id-1'
    [[...], {"id": "unique-id-1", "canceled": true}]
    # Point: "id=unique-id-1"

最初の `select` コマンドが長時間かかると仮定します。 `request_id=unique-id-1` パラメーターを指定することで `unique-id-1` というリクエストIDをこの `select` コマンドに割り当てます。

2つめの `request_cancel` コマンドで `id=unique-id-1` パラメーターを指定しています。 `unique-id-1` は `select` コマンドに渡したリクエストIDと同じリクエストIDです。

この `select` コマンドはすぐにはキャンセルされないかもしれません。また、このキャンセルリクエストは無視されることもあります。

同じリクエストIDに対するキャンセルリクエストを複数回送ることができます。もし、対象のリクエストがキャンセルされたか終了した場合は戻り値の中の `"canceled"` の値が `true` から `false` に変わります。

    $ curl 'http://localhost:10041/d/request_cancel?id=unique-id-1'
    [[...], {"id": "unique-id-1", "canceled": true}]
    # "select" is still running... ("canceled" is "true")
    $ curl 'http://localhost:10041/d/request_cancel?id=unique-id-1'
    [[...], {"id": "unique-id-1", "canceled": true}]
    # "select" is still running... ("canceled" is "true")
    $ curl 'http://localhost:10041/d/request_cancel?id=unique-id-1'
    [[...], {"id": "unique-id-1", "canceled": false}]
    # "select" is canceled or finished. ("canceled" is "false")

もし、この `select` コマンドがキャンセルされたら、 `select` コマンドの リターンコード は `-5` （ `GRN_INTERRUPTED_FUNCTION_CALL` ）になります。:

    $ curl 'http://localhost:10041/d/select?table=LargeTable&filter=true&request_id=unique-id-1' &
    [[-5, ...], ...]

## 7.3.53.4. 引数

このセクションでは `request_cancel` の引数について説明します。

### 7.3.53.4.1. 必須引数

`id` だけが必須の引数です。

#### 7.3.53.4.1.1. `id`

対象リクエストのIDを指定します。

## 7.3.53.5. 戻り値

`request_cancel` コマンドはキャンセルリクエストの結果を返します。:

    [
      HEADER,
      {
        "id":       ID,
        "canceled": CANCEL_REQUEST_IS_ACCEPTED_OR_NOT
      }
    ]

`HEADER`

> `HEADER` については 出力形式 を参照してください。

`ID`

> 対象のリクエストのIDです。

`CANCEL_REQUEST_IS_ACCEPTED_OR_NOT`

> もし、このキャンセルリクエストが受け付けられたら `true` 、そうでなければ `false` になります。

> 「キャンセルリクエストが受け付けられた」というのは「対象リクエストがキャンセルされた」という意味ではないことに注意してください。これは「キャンセルリクエストは対象リクエストに通知したが、対象リクエストはそのキャンセルリクエストを無視するかもしれない」という意味です。

> 指定したリクエストIDが割り当てられているリクエストが存在しなければ `false` になります。

## 7.3.53.6. 参考

- リクエストID