Creation of ByteStream class.

content/browser/download/byte_stream.h

Index: content/browser/download/byte_stream.h
diff --git a/content/browser/download/byte_stream.h b/content/browser/download/byte_stream.h
new file mode 100644
index 0000000000000000000000000000000000000000..302b8e0dd42df8cf4d4f86483b229522e650c4ff
--- /dev/null
+++ b/content/browser/download/byte_stream.h
@@ -0,0 +1,128 @@
+// 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 CONTENT_BROWSER_DOWNLOAD_BYTE_STREAM_H_
+#define CONTENT_BROWSER_DOWNLOAD_BYTE_STREAM_H_
+#pragma once
+
+#include <set>
+#include <utility>
+#include <deque>
+
+#include "base/callback.h"
+#include "base/memory/ref_counted.h"
+#include "base/synchronization/lock.h"
+#include "content/public/browser/download_interrupt_reasons.h"
+#include "net/base/io_buffer.h"
+
+namespace base {
+class SequencedTaskRunner;
+}
+
+namespace content {
+
+// A byte stream is a pipe to transfer bytes between a source and a
+// sink, which may be on different threads.  It is intended to be the
+// only connection between source and sink; they need have no
+// awareness of each other aside from the byte stream.  The source and
+// the sink have different interfaces to a byte stream, |ByteStreamInput|
+// and |ByteStreamOutput|.  A pair of connected interfaces is generated by
+// calling |CreateByteStream|.
+//
+// The source adds bytes to the bytestream via |ByteStreamInput::Write|
+// and the sync retrieves bytes already written via |ByteStreamOutput::Read|.
+//
+// When the source has no more data to add, it will call
+// |ByteStreamInput::Close| to indicate that.  Errors at the source
+// are indicated to the sync via a non-DOWNLOAD_INTERRUPT_REASON_NONE code.
+//
+// Normally the source is not managed after the relationship is setup;
+// it is expected to provide data and then close itself.  If an error
+// occurs on the sink, it is not signalled to the source via this
+// mechanism; instead, the source will write data until it exausts the
+// available space.  Instead, it is the responsibility of the sink,
+// usually through notifying whatever controller setup the
+// relationship, to signal the source in some other fashion.
+//
+// Callback lifetime management: No lifetime management is done in this
+// class to prevent registered callbacks from being called after any
+// objects to which they may refer have been destroyed.  It is the
+// responsibility of the callers to avoid use-after-free references.
+// This may be done by any of several mechanisms, including weak
+// pointers, scoped_refptr references, or calling the registration
+// function with a null callback from a destructor.  To enable the null
+// callback strategy, callbacks will always be evaluated immediately
+// before execution.
+//
+// Class methods are virtual to allow mocking for tests; these classes
+// aren't intended to be base classes for other classes.
+class CONTENT_EXPORT ByteStreamInput {
+public:
+  virtual ~ByteStreamInput() = 0;
+
+  // Always adds the data passed into the ByteStream.  Returns true
+  // if more data may be added without exceeding the class limit
+  // on data.  Takes ownership of |buffer|.
+  virtual bool Write(scoped_refptr<net::IOBuffer> buffer,
+                     size_t byte_count) = 0;
+
+  // Signal that all data that is going to be sent, has been sent,
+  // and provide a status.  |DOWNLOAD_INTERRUPT_REASON_NONE| should be
+  // passed for successful completion.
+  virtual void Close(DownloadInterruptReason status) = 0;
+
+  // Register a callback to be called
+  // when the stream transitions from full to having space available.
+  // The callback will always be called on the task runner associated
+  // with the ByteStreamInput.
+  // This callback will only be called if a call to Write has previously
+  // returned false (i.e. the ByteStream has been filled).
+  // Multiple calls to this function are supported, but they may result
+  // in dispatched source callbacks never arriving if they race with
+  // the callback update.
+  // |empty_percentage| is an integer in the range 0-100 that specifies how

[willchan no longer on Chromium, 2012/05/15 19:41:32]

Is |empty_percentage| still here?

[Randy Smith (Not in Mondays), 2012/05/15 22:53:25]

Whoops; no.  I put in controllable hysteresis into the original class, and
decided I was getting ahead of myself (implementing features without targeted
use cases) and removed it in one of the rewrites.  Fixed.

+  // much of the space in the pipe must be available before the source
+  // callback is called.  If it is 0, the callback is called as soon as there
+  // is any space in the pipe; if 100, the pipe must be completely empty
+  // before it is called.
+  virtual void RegisterCallback(base::Closure source_callback) = 0;

[willchan no longer on Chromium, 2012/05/15 19:41:32]

const base::Closure&

[Randy Smith (Not in Mondays), 2012/05/15 22:53:25]

Done.

+};
+
+class CONTENT_EXPORT ByteStreamOutput {
+ public:
+  typedef enum { STREAM_EMPTY, STREAM_HAS_DATA, STREAM_COMPLETE } StreamState;
+
+  virtual ~ByteStreamOutput() = 0;
+
+  // Returns STREAM_EMPTY if there is no data on the ByteStream and
+  // Close() has not been called, and STREAM_COMPLETE if there
+  // is no data on the ByteStream and Close() has been called.
+  // If there is data on the ByteStream, returns STREAM_HAS_DATA
+  // and fills in |*data| with a pointer to the data, and |*length|
+  // with its length.
+  virtual StreamState Read(scoped_refptr<net::IOBuffer>* data,
+                           size_t* length) = 0;
+
+  // Only valid to call if Read() has returned STREAM_COMPLETE.
+  virtual DownloadInterruptReason GetStatus() const = 0;
+
+  // Register a callback to be called
+  // when data is added or the source completes.
+  // The callback will be always be called on the owning task runner.
+  // Multiple calls to this function are supported, but they may result
+  // in dispatched sink callbacks never arriving if they race with
+  // the callback update.
+  virtual void RegisterCallback(base::Closure sink_callback) = 0;
+};
+
+CONTENT_EXPORT void CreateByteStream(
+    scoped_ptr<ByteStreamInput>* input,
+    scoped_ptr<ByteStreamOutput>* output,
+    scoped_refptr<base::SequencedTaskRunner> input_task_runner,
+    scoped_refptr<base::SequencedTaskRunner> output_task_runner,
+    size_t buffer_size);
+
+}  // namespace content
+
+#endif  // CONTENT_BROWSER_DOWNLOAD_BYTE_STREAM_H_