- From: timeless <timeless@gmail.com>
- Date: Wed, 20 Apr 2011 22:41:42 -0400
- To: Eliot Graff <Eliot.Graff@microsoft.com>
- Cc: public-webapps <public-webapps@w3.org>
On Tue, Apr 19, 2011 at 6:41 PM, Eliot Graff <Eliot.Graff@microsoft.com> wrote: > Thanks for the feedback. Moving forward, I will track changes and resolution of these suggestions in bug 9379 [1]. ok > Appreciate the time you've spent on this. here's next next part, note that i drafted it a while ago and am just sending it to flush my mailbox. > http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html part two... > The transaction mode determines both which operations are allowed > to be performed during the transaction, as well whether two transactions > can run concurrently or not. The transaction mode controls whether or not multiple transactions can run currently and which operations may be performed during the transaction. > Which operations are allowed be be performed are The allowed operations are > defined in detail below, > but in general transactions opened in READ_ONLY mode are only allowed > to perform reading operations which does not change data. s/reading // s/does/do/ -- this defines read, and operations are plural.. if you really want to define it perhaps stick some quotes around reading? > READ_WRITE transactions are allowed to > perform reading and writing transactions to existing object stores, s/perform reading and writing/read from and write/ > where as VERSION_CHANGE transactions are allowed to perform any operations, including ones that delete and create object stores and indexes. > As long as the VERSION_CHANGE transaction, the implementation s/transaction/transaction is pending/ ? > MUST wait with starting any other transactions against the same s/with/before/ > database until the VERSION_CHANGE transaction is finished. > There are a number of ways that an implementation ensure this. s/ensure/ensures/ > It can prevent READ_WRITE transactions whose scope overlap s/prevent/stall/ ? (you don't prevent them from ever existing, you at best prevent them from starting which seems more like stalling or delaying) s/overlap/overlaps/ > the scope of the READ_ONLY transaction from starting until the > READ_ONLY transaction is finished. s/is finished/finishes/ > Or it can allow the READ_ONLY transaction to see a snapshot of the > contents of the object stores which is taken when the READ_ONLY > transaction is started. s/is // > Similarly, implementations MUST ensure that a READ_WRITE transaction is only affected by changes to object stores that are made using the transaction itself. I.e. the implementation MUST ensure that another transaction does not modify the contents of object stores in the READ_WRITE transactions scope. I don't think starting a sentence with "i.e." is a good idea... s/transactions/transaction's/ > The implementation MUST also ensure that if the READ_WRITE transaction > completes successfully, that the changes written to object stores using the s/, that / / > transaction can be committed to the database without merge conflicts. i find "can be" here problematic, i know it's only meaningful with the next sentence, but i don't think it works well. > An implementation MUST NOT abort a transaction due to merge conflicts. > An implementation MUST NOT start any transaction until all other > READ_WRITE transactions with overlapping scope have completed. doesn't this prevent merge conflicts? > When multiple transactions are eligible to be started, older transactions > should be started first. should 'should' be written as an RFC word? > User agents MUST ensure a reasonable level of fairness across transactions to prevent starvation. > For example if multiple READ_ONLY transaction are started one after another the implementation MUST ensure that that doesn't indefinitely prevent a pending READ_WRITE transaction from starting. This MUST doesn't seem testable, and sticking a MUST into an example seems wrong. > Transaction objects implement Each transaction object will implement either > the IDBTransaction or the IDBTransactionSync > interfaces. interface. -- this is a style change and applies to other objects in this document. I'm assuming that an object only ever implements one of the two interfaces and thus <interface> should be singular and you should spell out that it's exclusive. If it isn't, I'd like to know how/why. > Every request also has a result and an errorCode, neither of which are accessible until the done flag is set to true. does 'are accessible' mean "will throw an exception if poked"? > Finally, requests have a request transaction. When a request is created, it is always placed against a transaction using either the steps to a asynchronously execute a request or the steps to a synchronously execute a request. It would be really helpful if things like <steps to whatever> were links > This sets the request transaction to be that request. s/This sets/Those steps set/ > The only exceptions to this are the request returned from a IDBFactory.open call and the request returned from a IDBDatabase.setVersion call, which create requests which have a null request transaction. "exceptions" sometimes is an English word and sometimes it's a code term (something which can be thrown). I can't tell here which is intended, if the latter it should be used with 'thrown', for the former I'd suggest avoiding the word entirely. > A key range MAY be lower-bounded or upper-bounded if there is a value that is, respectively, smaller than or larger than all its elements. "larger" seems odd, is there something wrong with using "greater" (and thus "less")? > A key range is said to be bounded if it is both lower- and upper-bounded and unbounded otherwise. s/ and unbounded otherwise/; otherwise it is unbounded/ ? > A key range MAY be open, i.e., not including its endpoints or s/endpoints/endpoints,/ > closed, i.e., including its endpoints. > Either ... and either of the bounds are open. s/are/is/ > The cursor has a source indicating which index or object store whose records it is iterating. s/which/the/ s/object/the object/ > A cursor maintains a position over this series, which moves in a direction that is either monotonically increasing or decreasing order of the record keys. "order" feels out of place here > If the source of a cursor is a object store, s/a object/an object/ > the effective key of the cursor is the cursors position. s/cursors/cursor's/ > If the source of a cursor is a index, s/a index/an index/ > the effective object store of the cursor is that index's referenced object store and the effective key is the cursors object store position. s/cursors/cursor's/ > For cursors iterating indexes the situation is a little bit more complicated since multiple records can have the same key and are therefor also sorted by value. s/therefor/therefore/ > When iterating indexes the cursor's also has a object store position, s/cursor's/cursor/ s/a object/an object/ > which indicates the value of the previously found record in the index. > Both position and the object store position is used when finding the next appropriate record. s/is/are/ > A mutation operation in the transaction failed > due to a because a constraint was not satisfied. s/due to a // > For example, an object such as an object store or index already exists and > a new one was being attempted to be created. a request attempted to create a new one. > const unsigned short DATA_ERR = 5 > Data provided to an operation does not meet requirements. this seems like an odd error name given its description > A operation An operation was > called on an object on which it is not allowed or at a time when it is not allowed. > The TRANSACTION_INACTIVE_ERR and READ_ONLY_ERR errors are more specific variants of this error. Does that mean that they should be dispatched instead when applicable? Or can the UA choose to always use this one?
Received on Thursday, 21 April 2011 02:42:11 UTC