Creation of ByteStream class.

content/browser/download/byte_stream.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 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|.

[benjhayden, 2012/05/16 14:26:25]

s/sync/sink/g?

[Randy Smith (Not in Mondays), 2012/05/16 20:30:16]

Done.

+//
+// 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.

[benjhayden, 2012/05/16 14:26:25]

Does this contradict the second sentence of the first paragraph?

[Randy Smith (Not in Mondays), 2012/05/16 20:30:16]

Modified the text a bit.  My intention is that the source and sink have no
direct knowledge of each other; there may be indirect links (and will be in 
the downloads system use case).

+//
+// 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

[benjhayden, 2012/05/16 14:26:25]

Sorry, what does it mean to evaluate a callback?

[Randy Smith (Not in Mondays), 2012/05/16 20:30:16]

Modified the text; let me know what you think.

+// 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

[benjhayden, 2012/05/16 14:26:25]

M-q to reflow?

[Randy Smith (Not in Mondays), 2012/05/16 20:30:16]

Done.

+  // 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, though note that it
+  // is the callers responsibility to handle races with space becoming
+  // available (i.e. in the case of that race either of the before
+  // or after callbacks may be called).
+  virtual void RegisterCallback(const base::Closure& source_callback) = 0;
+};
+
+class CONTENT_EXPORT ByteStreamOutput {
+ public:
+  typedef enum { STREAM_EMPTY, STREAM_HAS_DATA, STREAM_COMPLETE } StreamState;

[benjhayden, 2012/05/16 14:26:25]

Why do you need typedef?

[Randy Smith (Not in Mondays), 2012/05/16 20:30:16]

Because I'm an old programmer who isn't used to the new fangled compilers and
language specs :-}.  Done.

+
+  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

[benjhayden, 2012/05/16 14:26:25]

M-q?

[Randy Smith (Not in Mondays), 2012/05/16 20:30:16]

Done.

+  // 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, though note that it
+  // is the callers responsibility to handle races with data becoming
+  // available (i.e. in the case of that race either of the before
+  // or after callbacks may be called).
+  virtual void RegisterCallback(const base::Closure& sink_callback) = 0;
+};
+
+CONTENT_EXPORT void CreateByteStream(
+    scoped_ptr<ByteStreamInput>* input,
+    scoped_ptr<ByteStreamOutput>* output,
+    scoped_refptr<base::SequencedTaskRunner> input_task_runner,

[benjhayden, 2012/05/16 14:26:25]

I thought that function inputs (task_runners, buffer_size) usually preceded
outputs (byte stream halves). Maybe that's just my verilog showing.

[Randy Smith (Not in Mondays), 2012/05/16 20:30:16]

If so, the folks who wrote the style guide also knew verilog :-}.  Done.

+    scoped_refptr<base::SequencedTaskRunner> output_task_runner,
+    size_t buffer_size);
+
+}  // namespace content
+
+#endif  // CONTENT_BROWSER_DOWNLOAD_BYTE_STREAM_H_