7.3.54. `request_cancel`#

7.3.54.1. 概要#

Added in version 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.54.2. 構文#

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

request_cancel id

7.3.54.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.54.4. 引数#

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

7.3.54.4.1. 必須引数#

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

7.3.54.4.1.1. `id`#

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

7.3.54.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.54.6. 参考#

リクエストID

7.3.54. request_cancel#