注釈
このコマンドは実験的な機能です。
バージョン 4.0.9 で追加.
request_cancel コマンドは実行中のリクエストをキャンセルします。
いくつか制限があります。
リクエストIDはユーザーが管理する必要があります。(各リクエストに一意のキーを割り当てる必要があります。)
キャンセルリクエストは無視されることもあります。(同じリクエストIDに対して何度も request_cancel コマンドを送信することができます。)
マルチスレッド型のGroongaサーバーのみサポートしています。( groonga executable file ベースのサーバーでは使えますが、 groonga-httpd では使えません。)
リクエストIDについては リクエストID を参照してください。
リクエストがキャンセルされたら、キャンセルされたリクエストの リターンコード は -5 ( GRN_INTERRUPTED_FUNCTION_CALL )になります。
以下は 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, ...], ...]
このセクションでは request_cancel の引数について説明します。
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 になります。