On Tue, Apr 19, 2011 at 6:41 PM, Eliot Graff <eliot.gr...@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?
