1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
.. -*- rst -*-
``request_cancel``
==================
Summary
-------
.. versionadded:: 4.0.9
``request_cancel`` command cancels a running request.
There are some limitations:
* 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 :doc:`/reference/executables/groonga` based server but can't
use with :doc:`/reference/executables/groonga-httpd`.)
See :doc:`/reference/command/request_id` about request ID.
If the request is canceled, a :doc:`/reference/command/return_code` of the canceled request as below.
* ``-5`` (``GRN_INTERRUPTED_FUNCTION_CALL``) (Groonga version 6.0.1 before)
* ``-77`` (``GRN_CANCEL``) (Groonga version 6.0.1 or later)
Syntax
------
This command takes only one required parameter::
request_cancel id
Usage
-----
Here is an example of ``request_cancel`` command::
$ 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`` in return value::
$ 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
:doc:`/reference/command/return_code`::
$ curl 'http://localhost:10041/d/select?table=LargeTable&filter=true&request_id=unique-id-1' &
[[-5, ...], ...]
Parameters
----------
This section describes parameters of ``request_cancel``.
Required parameters
^^^^^^^^^^^^^^^^^^^
There is required parameter, ``id``.
``id``
""""""
Specifies the ID for the target request.
Return value
------------
``request_cancel`` command returns the result of the cancel request::
[
HEADER,
{
"id": ID,
"canceled": CANCEL_REQUEST_IS_ACCEPTED_OR_NOT
}
]
``HEADER``
See :doc:`/reference/command/output_format` about ``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``.
See also
--------
* :doc:`/reference/command/request_id`
|
