net: Make UploadDataStream::Read() asynchronous

net/base/upload_data.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef NET_BASE_UPLOAD_DATA_H_
 #define NET_BASE_UPLOAD_DATA_H_
 
 #include <vector>
 
 #include "base/basictypes.h"
@@ skipping 21 matching lines @@
  protected:
   virtual ~ChunkCallback() {}
 };
 
 //-----------------------------------------------------------------------------
 // A very concrete class representing the data to be uploaded as part of a
 // URLRequest.
 //
 // Until there is a more abstract class for this, this one derives from
 // SupportsUserData to allow users to stash random data by
 // key and ensure its destruction when UploadData is finally deleted.

[mmenke, 2012/10/15 19:54:45]

How about a description of how chunked uploading works here?  I found it rather
non-obvious, since it's completely different from how async reads are handled,
and it's not handled transparently by upload_data_steam, but rather must be
micromanaged by the stream consumer.

My suggestion (In another paragraph):  "Chunked uploads are handled by
repeatedly calling AppendBytes as data becomes available.  When more data
becomes available, the ChunkCallback's OnChunkAvailable function is called.  The
UploadData creator is then responsible for checking if the UploadData stream has
more data available, if necessary."

[hashimoto, 2012/10/16 11:52:20]

Thank you for this great documentation, though the comment will be soon removed
when http://crbug.com/152148 gets fixed after this change is landed :)
Done.

 class NET_EXPORT UploadData
     : public base::RefCounted<UploadData>,
       public base::SupportsUserData {
  public:
   UploadData();
 
   void AppendBytes(const char* bytes, int bytes_len);
 
   void AppendFileRange(const FilePath& file_path,
                        uint64 offset, uint64 length,
                        const base::Time& expected_modification_time);
 
   // Adds the given chunk of bytes to be sent immediately with chunked transfer
   // encoding.
   void AppendChunk(const char* bytes, int bytes_len, bool is_last_chunk);
 
   // Sets the callback to be invoked when a new chunk is available to upload.
   void set_chunk_callback(ChunkCallback* callback);
 
   // Initializes the object to send chunks of upload data over time rather
-  // than all at once.
+  // than all at once. Only bytes can be appended for chunked data.

[mmenke, 2012/10/15 19:54:45]

Think this statement is too weak, since other functions that modify elements
don't work for initializing chunk encoded streams, either.  Suggest just
"Chunked data may only contain bytes, not files."

[hashimoto, 2012/10/16 11:52:20]

Done.

   void set_is_chunked(bool set) { is_chunked_ = set; }
   bool is_chunked() const { return is_chunked_; }
 
   void set_last_chunk_appended(bool set) { last_chunk_appended_ = set; }

[mmenke, 2012/10/15 19:54:45]

Maybe a comment that "set_last_chunk_appended() is not safe to call once an
UploadData starts being read from by an UploadDataStream."

[hashimoto, 2012/10/16 11:52:20]

This setter is exposed only for serialization code for IPC. (in
chrome/common/automation_messages.cc)
Added a comment.

   bool last_chunk_appended() const { return last_chunk_appended_; }
 
   const std::vector<UploadElement>* elements() const {
     return &elements_;
   }
 
   std::vector<UploadElement>* elements_mutable() {
     return &elements_;
   }
 
@@ skipping 19 matching lines @@
   ChunkCallback* chunk_callback_;
   bool is_chunked_;
   bool last_chunk_appended_;
 
   DISALLOW_COPY_AND_ASSIGN(UploadData);
 };
 
 }  // namespace net
 
 #endif  // NET_BASE_UPLOAD_DATA_H_