[tahoe-dev] [tahoe-lafs] #757: there isn't a doc that says "which operations are efficient"

[tahoe-lafs]

#757: there isn't a doc that says "which operations are efficient"
------------------------------------+---------------------------------------
 Reporter:  zooko                   |           Owner:  kevan    
     Type:  enhancement             |          Status:  assigned 
 Priority:  major                   |       Milestone:  undecided
Component:  documentation           |         Version:  1.4.1    
 Keywords:  performance docs large  |   Launchpad_bug:           
------------------------------------+---------------------------------------

Comment(by kevan):

 I'm attaching a first stab at this.

 If I understand correctly, mutable files can be modified in two ways:

   * Overwriting their contents with those of a new file. This is what
 tools like the WUI and CLI do when updating a mutable file.
   * download-modify-upload, which is done internally to directories when
 entries are added or removed to/from them.

 When I read "insert/delete B bytes in the middle of an existing A-byte
 mutable file", I thought of download-modify-upload (otherwise, this just
 seems like a special case of "modify B bytes of an existing A-byte mutable
 file"). I then wondered if it was appropriate to have an explanation of
 that in there. If performance.txt is intended for end-users and people who
 maintain grids, and if they wouldn't ever directly modify mutable files
 with download-modify-upload (since none of the end-user interfaces do that
 directly), then it seems like we'd do fine to just move the explanation
 for "insert/delete B bytes in the middle of an existing A-byte mutable
 file" into the explanation about modifying directories, since that is a
 special case of the same operation, and something that end users can do
 directly.

 I also removed the existing blurb about mutable files, since it seemed
 redundant now that there are blurbs about mutable files elsewhere. If
 anyone misses it, let me know and I'll put it back.

 I still want to add blurbs for the various verification operations, but I
 probably won't get around to that until tomorrow or Monday.

-- 
Ticket URL: <http://allmydata.org/trac/tahoe/ticket/757#comment:11>
tahoe-lafs <http://allmydata.org>
secure decentralized file storage grid