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になります。