2.8. Requests

Each asynchronous operation on a database is done using a request. Every request represents one operation.

A request has a processed flag which is initially false. This flag is set to true when the operation associated with the request has been executed.

A request is said to be processed when its processed flag is true.

A request has a done flag which is initially false. This flag is set to true when the result of the operation associated with the request is available.

A request has a source object.

A request has a result and an error, neither of which are accessible until its done flag is true.

A request has a transaction which is initially null. This will be set when a request is placed against a transaction using the steps to asynchronously execute a request.

When a request is made, a new request is returned with its done flag set to false. If a request completes successfully, its done flag is set to true, its result is set to the result of the request, and an event with type success is fired at the request.

If an error occurs while performing the operation, the request’s done flag is set to true, the request’s error is set to the error, and an event with type error is fired at the request.

A request‘s get the parent algorithm returns the request’s transaction.

Requests are not typically re-used, but there are exceptions. When a cursor is iterated, the success of the iteration is reported on the same request object used to open the cursor. And when an upgrade transaction is necessary, the same open request is used for both the upgradeneeded event and final result of the open operation itself. In some cases, the request’s done flag will be set to false, then set to true again, and the result can change or error could be set instead.

2.8.1. Open requests

An open request is a special type of request used when opening a connection or deleting a database. In addition to success and error events, blocked and upgradeneeded events may be fired at an open request to indicate progress.

The source of an open request is always null.

The transaction of an open request is null unless an upgradeneeded event has been fired.

An open request‘s get the parent algorithm returns null.

Open requests are processed in a connection queue. The queue contains all open requests associated with an origin and a name. Requests added to the connection queue processed in order and each request must run to completion before the next request is processed. An open request may be blocked on other connections, requiring those connections to close before the request can complete and allow further requests to be processed.

A connection queue is not a task queue associated with an event loop, as the requests are processed outside any specific browsing context. The delivery of events to completed open request still goes through a task queue associated with the event loop of the context where the request was made.