Skip to content

Commit

Permalink
git squash commit for manualcommit.
Browse files Browse the repository at this point in the history 
461db42e966892b49eb9f689c20d1e4fcde0f618
Initial sketch of manual commit

fix/add 'new in this edition' hints

version history

invert flag check

don't let tx go inactive

post-rebase cleanup

6fbe9e5f5221c00700c1b2e2a0707249177f4414
bangbang
  • Loading branch information
@inexorabletash
inexorabletash committed Apr 13, 2023
1 parent a6a3acc commit d669216
Showing 1 changed file with 124 additions and 16 deletions.
140 changes: 124 additions & 16 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -929,6 +929,8 @@ following:
instead is created automatically when an
{{IDBOpenDBRequest/upgradeneeded!!event}} event is fired.

A [=/transaction=] has an <dfn>manual commit flag</dfn>, which is initially false. By default, transactions commit automatically when all outstanding requests have been processed. This can be behavior can be modified by options set when creating the transaction.

A [=/transaction=] has a <dfn>durability hint</dfn>. This is a hint to the user agent of whether to prioritize performance or durability when committing the transaction. The [=transaction/durability hint=] is one of the following:

: "{{IDBTransactionDurability/strict}}"
Expand Down Expand Up @@ -1036,10 +1038,11 @@ The <dfn>lifetime</dfn> of a
</aside>

1. When each [=/request=] associated with a transaction is [=request/processed=],
a {{IDBRequest/success!!event}} or {{IDBRequest/error!!event}} [=event=] will be
fired. While the event is being [=dispatched=], the transaction
a {{IDBRequest/success!!event}} or {{IDBRequest/error!!event}} [=event=] will be fired.
If the transaction's [=transaction/manual commit flag=] is false (the default), then
while the event is being [=dispatched=], the transaction
[=transaction/state=] is set to [=transaction/active=], allowing
additional requests to be made against the transaction. Once the
additional requests to be made against the transaction; once the
event dispatch is complete, the transaction's
[=transaction/state=] is set to [=transaction/inactive=] again.

Expand All @@ -1058,11 +1061,12 @@ The <dfn>lifetime</dfn> of a
[=/object stores=] as well as additions and removals of [=/object
stores=] and [=/indexes=].

1. The implementation must attempt to <dfn lt="commit|committed">commit</dfn>
a transaction when all [=/requests=] placed against the
1. If a transaction's [=transaction/manual commit flag=] is false, then
the implementation must attempt to <dfn lt="commit|committed">commit</dfn>
it when all [=/requests=] placed against the
transaction have completed and their returned results handled, no
new requests have been placed against the transaction, and the
transaction has not been [=transaction/aborted=]
transaction has not been [=transaction/aborted=].

An explicit call to {{IDBTransaction/commit()}} will initiate a
[=transaction/commit=] without waiting for request results to be
Expand Down Expand Up @@ -1099,7 +1103,7 @@ They will return true if any transactions were cleaned up, or false otherwise.
1. For each [=/transaction=] |transaction| with [=transaction/cleanup event loop=]
matching the current [=/event loop=]:

1. Set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
1. If |transaction|'s [=transaction/manual commit flag=] is false, then set |transaction|'s [=transaction/state=] to [=transaction/inactive=].

1. Clear |transaction|'s [=transaction/cleanup event loop=].

Expand All @@ -1120,6 +1124,78 @@ a [=/transaction=] that has successfully [=transaction/committed=].
An event with type <dfn event for=IDBTransaction>abort</dfn> is fired at
a [=/transaction=] that has [=transaction/aborted=].


<aside class=example id=example-transaction-autocommit>

The following example uses requests within a transaction to increment a counter value.
Event handlers log various state changes during the request and transaction lifecycles.

```js
const transaction = connection.transaction('my_data', 'readwrite');
const store = transaction.objectStore('my_data');
const get_request = store.get('counter');
get_request.onerror = e => {
console.warn(`get failed: ${get_request.error}`);
};
get_request.onsuccess = e => {
console.log(`get succeeded`);
const old_value = get_request.result;
const put_request = store.put(old_value + 1, 'counter');
put_request.onerror = e => {
console.warn(`get failed: ${put_request.error}`);
};
put_request.onsuccess = {
console.log(`put succeeded`);
// No more requests are made, so the transaction will autocommit.
};
};

transaction.onabort = e => {
console.warn(`transaction aborted: ${transaction.error}`);
};

transaction.oncomplete = e => {
console.log(`transaction committed`);
};
```
</aside>

<aside class=example id=example-transaction-manualcommit>

The following example uses requests within a transaction to atomically
update a record's value using an asynchronous network fetch. A manually
committing transaction is necessary.

```js
const transaction = connection.transaction(
'my_records, 'readwrite', {manualCommit: true});

const store = transaction.objectStore('my_records);
store.get('key').onsuccess = async e => {
try {
const record = e.target.result;

// Make an asynchronous network request. If the transaction
// was not set to manual commit, it would autocommit here
// because there were no outstanding requests.
const response = await fetch(record.url);

// Update the record.
record.status = response.status;
store.put(record, 'key');

// Commit the transaction, once the request has completed.
// If the request fails, the transaction will abort instead.
transaction.commit();
} catch (ex) {
// If the fetch() fails, abort the transaction.
transaction.abort();
}
});
```
</aside>


<!-- ============================================================ -->
### Transaction scheduling ### {#transaction-scheduling}
<!-- ============================================================ -->
Expand Down Expand Up @@ -2429,6 +2505,7 @@ interface IDBDatabase : EventTarget {
enum IDBTransactionDurability { "default", "strict", "relaxed" };

dictionary IDBTransactionOptions {
boolean manualCommit = false;
IDBTransactionDurability durability = "default";
};

Expand Down Expand Up @@ -2622,9 +2699,13 @@ instance on which it was called.
Returns a new [=/transaction=] with the given
|scope| (which can be a single [=/object store=] [=object-store/name=] or an array of [=object-store/names=]),
|mode| ("{{IDBTransactionMode/readonly}}" or "{{IDBTransactionMode/readwrite}}"),
and additional |options| including {{IDBTransactionOptions/durability}} ("{{IDBTransactionDurability/default}}", "{{IDBTransactionDurability/strict}}" or "{{IDBTransactionDurability/relaxed}}").
and additional |options| including
{{IDBTransactionOptions/manualCommit}} (true or false), and
{{IDBTransactionOptions/durability}} ("{{IDBTransactionDurability/default}}", "{{IDBTransactionDurability/strict}}" or "{{IDBTransactionDurability/relaxed}}").

The default |mode| is "{{IDBTransactionMode/readonly}}" and the default {{IDBTransactionOptions/durability}} is "{{IDBTransactionDurability/default}}".
The default |mode| is "{{IDBTransactionMode/readonly}}".
The default {{IDBTransactionOptions/manualCommit}} is false.
The default {{IDBTransactionOptions/durability}} is "{{IDBTransactionDurability/default}}".

: |connection| . {{IDBDatabase/close()|close}}()
::
Expand Down Expand Up @@ -2655,7 +2736,11 @@ The <dfn method for=IDBDatabase>transaction(|storeNames|, |mode|, |options|)</df
1. If |mode| is not "{{IDBTransactionMode/readonly}}" or "{{IDBTransactionMode/readwrite}}",
[=exception/throw=] a {{TypeError}}.

1. Let |transaction| be a newly [=transaction/created=] [=/transaction=] with this [=/connection=], |mode|, |options|' {{IDBTransactionOptions/durability}} member, and the set of [=/object stores=] named in |scope|.
1. Let |transaction| be a newly [=transaction/created=] [=/transaction=] with this [=/connection=], |mode|, and the set of [=/object stores=] named in |scope|.

1. Set |transaction|'s [=transaction/manual commit flag=] to |options|' {{IDBTransactionOptions/manualCommit}} member.

1. Set |transaction|'s [=transaction/durability hint=] to |options|' {{IDBTransactionOptions/durability}} member.

1. Set |transaction|'s [=transaction/cleanup event loop=] to the
current [=/event loop=].
Expand All @@ -2664,6 +2749,12 @@ The <dfn method for=IDBDatabase>transaction(|storeNames|, |mode|, |options|)</df

</div>

<aside class=advisement>
&#x1F6A7;
The {{IDBTransactionOptions/manualCommit}} option is new in this edition.
&#x1F6A7;
</aside>

<aside class=advisement>
&#x1F6A7;
The {{IDBTransactionOptions/durability}} option is new in this edition.
Expand Down Expand Up @@ -4719,6 +4810,7 @@ the contents of the database.
interface IDBTransaction : EventTarget {
readonly attribute DOMStringList objectStoreNames;
readonly attribute IDBTransactionMode mode;
readonly attribute boolean manualCommit;
readonly attribute IDBTransactionDurability durability;
[SameObject] readonly attribute IDBDatabase db;
readonly attribute DOMException? error;
Expand Down Expand Up @@ -4753,6 +4845,10 @@ enum IDBTransactionMode {
("{{IDBTransactionMode/readonly}}" or "{{IDBTransactionMode/readwrite}}"), or "{{IDBTransactionMode/versionchange}}" for
an [=/upgrade transaction=].

: |transaction| . {{IDBTransaction/manualCommit}}
::
Returns true if the transaction was created with {{IDBTransactionOptions/manualCommit}}: `true` and false otherwise.

: |transaction| . {{IDBTransaction/durability}}
::
Returns the [=transaction/durability hint=] the transaction was created with
Expand Down Expand Up @@ -4788,6 +4884,14 @@ The <dfn attribute for=IDBTransaction>objectStoreNames</dfn> getter steps are:
The <dfn attribute for=IDBTransaction>mode</dfn> getter steps are to
return [=/this=]'s [=transaction/mode=].

The <dfn attribute for=IDBTransaction>manualCommit</dfn> attribute's getter must return [=/this=]'s [=transaction/manual commit flag=].

<aside class=advisement>
&#x1F6A7;
The {{IDBTransaction/manualCommit}} attribute is new in this edition.
&#x1F6A7;
</aside>

The <dfn attribute for=IDBTransaction>durability</dfn> getter steps are to return [=/this=]'s [=transaction/durability hint=].

<aside class=advisement>
Expand All @@ -4797,7 +4901,6 @@ The <dfn attribute for=IDBTransaction>durability</dfn> getter steps are to retur
&#x1F6A7;
</aside>


The <dfn attribute for=IDBTransaction>db</dfn> getter steps are to
return [=/this=]'s [=transaction/connection=]'s associated [=/database=].

Expand Down Expand Up @@ -4835,6 +4938,9 @@ none.
transaction to quickly finish, without waiting for pending requests to fire
{{IDBRequest/success!!event}} events before attempting to commit normally.

If the transaction was created with `manualCommit: true` then this method
<span class=allow-2119>must</span> be called to commit the transaction.

The transaction will abort if a pending request fails, for example due to a
constraint error. The {{IDBRequest/success!!event}} events for successful requests
will still fire, but throwing an exception in an event handler will not abort
Expand Down Expand Up @@ -4891,7 +4997,8 @@ The <dfn method for=IDBTransaction>abort()</dfn> method steps are:

The <dfn method for=IDBTransaction>commit()</dfn> method steps are:

1. If [=/this=]'s [=transaction/state=] is not [=transaction/active=],
1. If [=/this=]'s [=transaction/manual commit flag=] is false,
and [=/this=]'s [=transaction/state=] is not [=transaction/active=],
then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.

1. Run [=commit a transaction=] with [=/this=].
Expand Down Expand Up @@ -5480,14 +5587,14 @@ To <dfn>fire a success event</dfn> at a |request|, run these steps:
1. If |transaction|'s [=transaction/state=] is [=transaction/active=],
then:

1. Set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
1. If |transaction|'s [=transaction/manual commit flag=] is false, then set |transaction|'s [=transaction/state=] to [=transaction/inactive=].

1. If |legacyOutputDidListenersThrowFlag| is true,
then run [=abort a transaction=] with
|transaction| and a newly [=exception/created=]
"{{AbortError}}" {{DOMException}}.

1. If |transaction|'s [=transaction/request list=] is empty,
1. If |transaction|'s [=transaction/manual commit flag=] is false and if |transaction|'s [=transaction/request list=] is empty,
then run [=commit a transaction=] with |transaction|.

</div>
Expand Down Expand Up @@ -5519,7 +5626,7 @@ To <dfn>fire an error event</dfn> at a |request|, run these steps:
1. If |transaction|'s [=transaction/state=] is [=transaction/active=],
then:

1. Set |transaction|'s [=transaction/state=] to [=transaction/inactive=].
1. If |transaction|'s [=transaction/manual commit flag=] is false, then set |transaction|'s [=transaction/state=] to [=transaction/inactive=].

1. If |legacyOutputDidListenersThrowFlag| is true,
then run [=abort a transaction=] with
Expand All @@ -5540,7 +5647,7 @@ To <dfn>fire an error event</dfn> at a |request|, run these steps:
|transaction| and [=/request=]'s [=request/error=], and
terminate these steps.

1. If |transaction|'s [=transaction/request list=] is empty,
1. If |transaction|'s [=transaction/manual commit flag=] is false and |transaction|'s [=transaction/request list=] is empty,
then run [=commit a transaction=] with |transaction|.

</div>
Expand Down Expand Up @@ -6781,6 +6888,7 @@ For the revision history of the second edition, see [that document's Revision Hi
* Specified [[#transaction-scheduling]] more precisely and disallow starting read/write transactions while read-only transactions with overlapping scope are running. ([Issue #253](https://github.com/w3c/IndexedDB/issues/253))
* Added <a href="#accessibility">Accessibility considerations</a> section. ([Issue #327](https://github.com/w3c/IndexedDB/issues/327))
* Used [[infra]]'s list sorting definition. ([Issue #346](https://github.com/w3c/IndexedDB/issues/346))
* Specified [=transaction/manual commit flag=], {{IDBTransactionOptions/manualCommit}} option and {{IDBTransaction/manualCommit}} attribute. ([Issue #34](https://github.com/w3c/IndexedDB/issues/34))

<!-- ============================================================ -->
# Acknowledgements # {#acknowledgements}
Expand Down

0 comments on commit d669216

Please sign in to comment.