Kouhei Sutou
null+****@clear*****
Mon Dec 29 15:36:46 JST 2014
Kouhei Sutou 2014-12-29 15:36:46 +0900 (Mon, 29 Dec 2014) New Revision: a2a7cc66e2e1db208a4446546d7695bc97144cf8 https://github.com/groonga/groonga/commit/a2a7cc66e2e1db208a4446546d7695bc97144cf8 Message: doc: document about request ID and request_cancel Added files: doc/source/reference/command/request_id.rst doc/source/reference/commands/request_cancel.rst Modified files: doc/source/reference/command.rst Modified: doc/source/reference/command.rst (+1 -0) =================================================================== --- doc/source/reference/command.rst 2014-12-29 15:25:27 +0900 (c311e8a) +++ doc/source/reference/command.rst 2014-12-29 15:36:46 +0900 (b4fb6c2) @@ -16,5 +16,6 @@ This section describes about command and built-in commands. command/command_version command/output_format + command/request_id command/return_code commands/* Added: doc/source/reference/command/request_id.rst (+39 -0) 100644 =================================================================== --- /dev/null +++ doc/source/reference/command/request_id.rst 2014-12-29 15:36:46 +0900 (4017417) @@ -0,0 +1,39 @@ +.. -*- rst -*- + +.. highlightlang:: none + +Request ID +========== + +Summary +------- + +You can assign ID to each request. + +The ID can be used by canceling the request. See also +:doc:`/reference/commands/request_cancel` for details about canceling +a request. + +Request ID should be managed by user. If you assign the same ID for +some running requests, you can't cancel the request. + +The simplest ID sequence is incremented numbers such as ``1``, +``2`` , ``...``. + +A request ID is a string. The maximum request ID size is 4096 byte. + +How to assign ID to request +--------------------------- + +All commands accept ``request_id`` parameter. You can assign ID to +request by adding ``request_id`` parameter. + +Here is an example to assign ``id-1`` ID to a request:: + + select Users --request_id id-1 + +See also +-------- + +* :doc:`/reference/commands/request_cancel` + Added: doc/source/reference/commands/request_cancel.rst (+126 -0) 100644 =================================================================== --- /dev/null +++ doc/source/reference/commands/request_cancel.rst 2014-12-29 15:36:46 +0900 (8730748) @@ -0,0 +1,126 @@ +.. -*- rst -*- + +.. highlightlang:: none + +``request_cancel`` +================== + +Summary +------- + +.. note:: + ``request_cancel`` command is an experimental feature. + +``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. + +Syntax +------ + +``request_cancel`` command takes only one parameter. + +The required parameter is only ``id``:: + + 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``:: + + $ 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") + +Parameters +---------- + +This section describes parameters of ``request_cancel``. + +Required parameter +^^^^^^^^^^^^^^^^^^ + +There is required parameter, ``id``. + +``id`` +"""""" + +It 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` -------------- next part -------------- HTML����������������������������...下载
