third_party/blink/public/platform/web_data_consumer_handle.h

// Copyright 2014 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 THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_DATA_CONSUMER_HANDLE_H_
#define THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_DATA_CONSUMER_HANDLE_H_

#include <stddef.h>
#include <memory>

#include "base/memory/scoped_refptr.h"
#include "third_party/blink/public/platform/web_common.h"

namespace base {
class SingleThreadTaskRunner;
}  // namespace base

namespace blink {

// WebDataConsumerHandle represents the "consumer" side of a data pipe. A user
// can read data from it.
//
// A WebDataConsumerHandle is a thread-safe object. A user can call
// |ObtainReader| or destruct the object on any thread.
// A WebDataConsumerHandle having a reader is called "locked". A
// WebDataConsumerHandle or its reader are called "waiting" when reading from
// the handle or reader returns kShouldWait.
//
// WebDataConsumerHandle can be created / used / destructed only on
// Oilpan-enabled threads.
// TODO(yhirano): Remove this restriction.
class BLINK_PLATFORM_EXPORT WebDataConsumerHandle {
 public:
  using Flags = unsigned;
  static const Flags kFlagNone = 0;

  enum Result {
    kOk,
    kDone,
    kBusy,
    kShouldWait,
    kResourceExhausted,
    kUnexpectedError,
  };

  // Client gets notification from the pipe.
  class BLINK_PLATFORM_EXPORT Client {
   public:
    virtual ~Client() = default;
    // The associated handle gets readable. This function will be called
    // when the associated reader was waiting but is not waiting any more.
    // This means this function can be called when handle gets errored or
    // closed. This also means that this function will not be called even
    // when some data arrives if the handle already has non-empty readable
    // data.
    // It is not guaranteed that the handle is not waiting when this
    // function is called, i.e. it can be called more than needed.
    // One can use / destruct the associated reader in this function.
    virtual void DidGetReadable() = 0;
  };

  // This class provides a means to read data from the associated handle. A
  // Reader object is bound to the thread on which |ObtainReader| is called.
  // Any functions including the destructor should be called on the thread.
  // A reader can outlive the associated handle. In such a case, the handle
  // destruction will not affect the reader functionality.
  // Reading functions may success (i.e. return kOk) or fail (otherwise), and
  // the behavior which is not specified is unspecified.
  class BLINK_PLATFORM_EXPORT Reader {
   public:
    // Destructing a reader means it is released and a user can get another
    // Reader by calling |ObtainReader| on any thread again.
    virtual ~Reader() = default;

    // Reads data into |data| up to |size| bytes. The actual read size will
    // be stored in |*read_size|. This function cannot be called when a
    // two-phase read is in progress.
    // Returns kDone when it reaches to the end of the data.
    // Returns kShouldWait when the handle does not have data to read but
    // it is not closed or errored.
    // The default implementation uses BeginRead and EndRead.
    virtual Result Read(void* data,
                        size_t /* size */,
                        Flags,
                        size_t* read_size);

    // Begins a two-phase read. On success, the function stores a buffer
    // that contains the read data of length |*available| into |*buffer|.
    // Returns kDone when it reaches to the end of the data.
    // Returns kShouldWait when the handle does not have data to read but
    // it is not closed or errored.
    // On fail, you don't have to (and should not) call EndRead, because the
    // read session implicitly ends in that case.
    virtual Result BeginRead(const void** buffer, Flags, size_t* available) = 0;

    // Ends a two-phase read.
    // |read_size| indicates the actual read size.
    virtual Result EndRead(size_t read_size) = 0;
  };

  WebDataConsumerHandle();
  virtual ~WebDataConsumerHandle();

  // Returns a non-null reader. This function can be called only when this
  // handle is not locked. |client| can be null. Otherwise, |*client| must be
  // valid as long as the reader is valid. The returned reader is bound to
  // the calling thread and client notification will be called on the thread
  // if |client| is not null.
  // If |client| is not null and the handle is not waiting, client
  // notification is called asynchronously.
  // |task_runner| cannot be null.
  virtual std::unique_ptr<Reader> ObtainReader(
      Client*,
      scoped_refptr<base::SingleThreadTaskRunner>) = 0;

  // Returns a string literal (e.g. class name) for debugging only.
  virtual const char* DebugName() const = 0;
};

}  // namespace blink

#endif  // THIRD_PARTY_BLINK_PUBLIC_PLATFORM_WEB_DATA_CONSUMER_HANDLE_H_