5.0 KiB
HTTP Interface for Async Results Management
@NAVIGATE_HttpJob @EMBEDTOC{HttpJobTOC}
Request Execution
ArangoDB provides various methods of executing client requests. Clients can choose the appropriate method on a per-request level based on their throughput, control flow, and durability requirements.
Blocking execution
ArangoDB is a multi-threaded server, allowing the processing of multiple client requests at the same time. Communication handling and the actual work can be performed by multiple worker threads in parallel.
Though multiple clients can connect and send their requests in parallel to ArangoDB, clients may need to wait for their requests to be processed.
By default, the server will fully process an incoming request and then return the result to the client. The client must wait for the server's response before it can send additional requests over the connection. For clients that are single-threaded or not event-driven, waiting for the full server response may be non-optimal.
Fire and Forget
To mitigate client blocking issues, ArangoDB since version 1.4. offers a generic mechanism
for non-blocking requests: if clients add the HTTP header x-arango-async: true to their
requests, ArangoDB will put the request into an in-memory task queue and return an HTTP 202
(accepted) response to the client instantly. The server will execute the tasks from
the queue asynchronously, decoupling the client requests and the actual work.
This allows for much higher throughput than if clients would wait for the server's response. The downside is that the response that is sent to the client is always the same (a generic HTTP 202) and clients cannot make a decision based on the actual operation's result. In fact, the operation might have not even been executed at the time the generic response has reached the client. Clients can thus not rely on their requests having been processed successfully.
The asynchronous task queue on the server is not persisted, meaning not-yet processed tasks from the queue might be lost in case of a crash.
Clients should thus not send the extra header when they have strict durability requirements or if they rely on result of the sent operation for further actions.
The maximum number of queued tasks is determined by the startup option
-scheduler.maximal-queue-size. If more than this number of tasks are already queued,
the server will reject the request with an HTTP 500 error.
Async Execution and later Result Retrieval
By adding the HTTP header x-arango-async: store to a request, clients can instruct
the ArangoDB server to execute the operation asynchronously as @ref HttpJobFireForget
"above", but also store the operation result in memory for a later retrieval. The
server will return a job id in the HTTP response header x-arango-async-id. The client
can use this id in conjunction with the HTTP API at /_api/job, which is described in
detail in this manual.
Clients can ask the ArangoDB server via the async jobs API which results are ready for retrieval, and which are not. Clients can also use the async jobs API to retrieve the original results of an already executed async job by passing it the originally returned job id. The server will then return the job result as if the job was executed normally.
ArangoDB will keep all results of jobs initiated with the x-arango-async: store
header. Results are removed from the server only if a client explicitly asks the
server for a specific result.
The async jobs API also provides methods for garbage collection that clients can use to get rid of "old" not fetched results. Clients should call this method periodically because ArangoDB does not artifically limit the number of not-yet-fetched results.
It is thus a client responsibility to store only as many results as needed and to fetch available results as soon as possible, or at least to clean up not fetched results from time to time.
The job queue and the results are kept in memory only on the server, so they might be lost in case of a crash.
Async Execution and Authentication
If a request requires authentication, the authentication procedure is run before queueing. The request will only be queued if it valid credentials and the authentication succeeds. If the request does not contain valid credentials, it will not be queued but rejected instantly in the same way as a "regular", non-queued request.
Managing Async Results via HTTP
@anchor HttpJobPut @copydetails triagens::admin::RestJobHandler::putJob
@CLEARPAGE @anchor HttpJobDelete @copydetails triagens::admin::RestJobHandler::deleteJob
@CLEARPAGE @anchor HttpJobGet @copydetails triagens::admin::RestJobHandler::getJob