net: Introduce SeekableIOBuffer and clean up HttpStreamParser.

net/base/io_buffer.h

 // Copyright (c) 2011 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_IO_BUFFER_H_
 #define NET_BASE_IO_BUFFER_H_
 #pragma once
 
 #include <string>
 
@@ skipping 136 matching lines @@
   int size() const { return size_; }
 
  private:
   virtual ~DrainableIOBuffer();
 
   scoped_refptr<IOBuffer> base_;
   int size_;
   int used_;
 };
 
+// Similar to DrainableIOBuffer(), but this version comes with its own
+// storage, so you don't need to create a separate IOBuffer. DidAppend(),
+// capacity(), and Clear() are also provided, so that the SeekableIOBuffer is
+// reusable. Example:
+//
+// SeekableIOBuffer buf(1024);
+// // capacity() == 1024. size() == BytesRemaining == BytesConsumed() == 0.
+// // data() points to the beginning of the buffer.
+//
+// int bytes_read = some_reader->Read(buf, buf.capacity());

[wtc, 2012/02/02 20:22:57]

The first argument should be buf.data().

In the general case, this call should look like:
  int bytes_read = some_reader->Read(buf.data() + buf.size(),
                                     buf.capacity() - buf.size());
	

[satorux1, 2012/02/02 22:02:27]

Done.

[wtc, 2012/02/02 22:32:30]

Please ignore this entire comment.  I forgot that our Read()
methods take IOBuffer* as the first argument.  Sorry about
the confusion.

This does mean such a Read() method can only be called once.
On the other hand, if we are using something like memcpy()
to read data into 'buf', then we can do that multiple times,
using the code I suggested above.

[satorux1, 2012/02/02 22:51:09]

No worry, some Read() function takes const char* (ex. FileStream as of now).
Changed it back from buf.data() -> buf, as it's more common. Removed "the
general case" for simplicity.
It's possible to call such a Read() method multiple times, but it's a bit
tricky:

bytes_read = some_reader->Read(buf, buf.capacity());
buf->DidAppend(bytes_read);
buf->DidConsume(bytes_read);  // advance data() by bytes_read.
bytes_read = some_reader->Read(buf, buf.capacity() -> buf.size());
buf->DidAppend(bytes_read);
buf->DidConsume(bytes_read);

// Before reading buf, move data() to the beginning...
buf->SetOffset(0);  
You are right.

+// buf.DidAppend(bytes_read);
+// // size() == BytesRemaining() == bytes_read. data() is unaffected.
+//
+// while (buf.BytesRemaining() > 0) {
+//   int bytes_consumed = Read(buf, buf->BytesRemaining());

[wtc, 2012/02/02 20:22:57]

We should call Write() instead of Read() here.

The first argument should be buf.data().

[satorux1, 2012/02/02 22:02:27]

Good catch. Fixed.
Here, we assume Write() takes IOBuffer*. If it takes const char*, we could just
use a regular IOBuffer with buf->data() + offset. Added some comment about it.

[wtc, 2012/02/02 22:32:30]

I was wrong again.  Sorry!

+//   buf.DidConsume(bytes_consumed);
+// }
+// // BytesRemaining() == 0. BytesConsumed() == size().
+// // data() points to the end of the comsumed bytes (exclusive).
+//
+// // If you want to reuse the buffer, be sure to clear the buffer.
+// buf.Clear();
+// // size() == BytesRemaining() == BytesConsumed() == 0.
+// // data() points to the beginning of the buffer.
+//
+class NET_EXPORT SeekableIOBuffer : public IOBuffer {
+ public:
+  explicit SeekableIOBuffer(int size);

[wtc, 2012/02/02 20:22:57]

This parameter should be named 'capacity'.

[satorux1, 2012/02/02 22:02:27]

Done.

+
+  // DidConsume() changes the |data_| pointer so that |data_| always points
+  // to the first unconsumed byte.
+  void DidConsume(int bytes);
+
+  // Returns the number of unconsumed bytes.
+  // GUARANTEES: 0 <= BytesRemaining() <= size().
+  int BytesRemaining() const;
+
+  // Returns the number of consumed bytes.
+  // GUARANTEES: BytesRemaining() + BytesConsumed == size().
+  int BytesConsumed() const;

[wtc, 2012/02/02 20:22:57]

Do we need the BytesConsumed() method?

[satorux1, 2012/02/02 22:02:27]

Removed. Right now, we don't need it. Removed it in the spirit of YAGNI. :)

+
+  // Seeks to an arbitrary point in the buffer. The notion of bytes consumed
+  // and remaining are updated appropriately.
+  // REQUIRES: 0 <= bytes <= size().
+  void SetOffset(int bytes);
+
+  // Marks that |bytes| have been appended. |bytes| is added to |size_|, but
+  // data() is unaffected.
+  // REQUIRES: 0 <= |bytes| + size() <= capacity().
+  void DidAppend(int bytes);
+
+  // Changes the logical size to 0, and the offset to 0.
+  void Clear();
+
+  // Returns the logical size of the buffer (i.e the number of bytes of data
+  // in the buffer).
+  // GUARANTEES: 0 <= size() <= capacity().
+  int size() const { return size_; }
+
+  // Returns the capacity of the buffer. The capacity is the size used when
+  // the object is created.
+  int capacity() const { return capacity_; };
+
+ private:
+  virtual ~SeekableIOBuffer();
+
+  char* begin_;

[wtc, 2012/02/02 20:22:57]

I suggest you name this member 'real_data_'.

[satorux1, 2012/02/02 22:02:27]

Done.

+  int capacity_;
+  int size_;
+  int used_;
+};
+
 // This version provides a resizable buffer and a changeable offset.
 class NET_EXPORT GrowableIOBuffer : public IOBuffer {

[wtc, 2012/02/02 20:22:57]

IMPORTANT: DrainableIOBuffer, SeekableIOBuffer, and
GrowableIOBuffer are all similar.

It would be nice to improve the comments for DrainableIOBuffer
and GrowableIOBuffer to explain when they should be used.

DrainableIOBuffer is used for writing the data progressively.
The data we need to write is given to us in an IOBuffer.

GrowableIOBuffer is used for reading the data
progressively, I think.

[satorux1, 2012/02/02 22:02:27]

Agreed. Added some comments for DrainableIOBuffer and GroableIOBuffer. Updated
the comment for SeekableIOBuffer as well.

  public:
   GrowableIOBuffer();
 
   // realloc memory to the specified capacity.
   void SetCapacity(int capacity);
   int capacity() { return capacity_; }
 
   // |offset| moves the |data_| pointer, allowing "seeking" in the data.
   void set_offset(int offset);
   int offset() { return offset_; }
@@ skipping 36 matching lines @@
  public:
   explicit WrappedIOBuffer(const char* data);
 
  protected:
   virtual ~WrappedIOBuffer();
 };
 
 }  // namespace net
 
 #endif  // NET_BASE_IO_BUFFER_H_