# groonga - オープンソースのカラムストア機能付き全文検索エンジン

- English page

# 7.3.26. `request_cancel`

## 7.3.26.1. 概要

注釈

`request_cancel` コマンドは実験的な機能です。

バージョン 4.0.9 で追加.

`request_cancel` command cancels a running request.

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

> - Request ID must be managed by user. (You need to assign unique key for each request.)
> - Cancel request may be ignored. (You can send `request_cancel` command multiple times for the same request ID.)
> - Only multithreading type Groonga server is supported. (You can use with groongaコマンド based server but can't use with groonga-httpd.)

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

If request is canceled, the canceled request has `-5` (`GRN_INTERRUPTED_FUNCTION_CALL`) as リターンコード.

## 7.3.26.2. 構文

`request_cancel` コマンドの引数は1つだけです。

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

    request_cancel id

## 7.3.26.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"

Assume that the first `select` command takes a long time. `unique-id-1` request ID is assigned to the `select` command by `request_id=unique-id-1` parameter.

The second `request_cancel` command passes `id=unique-id-1` parameter. `unique-id-1` is the same request ID passed in `select` command.

The `select` command may not be canceled immediately. And the cancel request may be ignored.

You can send cancel request for the same request ID multiple times. If the target request is canceled or finished, `"canceled"` value is changed to `false` from `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": 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")

If the `select` command is canceled, response of the `select` command has `-5` (`GRN_INTERRUPTED_FUNCTION_CALL`) as リターンコード:

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

## 7.3.26.4. 引数

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

### 7.3.26.4.1. 必須引数

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

#### 7.3.26.4.1.1. `id`

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

## 7.3.26.5. 戻り値

`request_cancel` command returns the result of the cancel request:

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

`HEADER`

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

`ID`

> The ID of the target request.

`CANCEL_REQUEST_IS_ACCEPTED_OR_NOT`

> If the cancel request is accepted, this is `true`, otherwise this is `false`.

> Note that "cancel request is accepted" doesn't means that "the target request is canceled". It just means "cancel request is notified to the target request but the cancel request may be ignored by the target request".

> If request assigned with the request ID doesn't exist, this is `false`.

## 7.3.26.6. 参考

- リクエストID