[PDB] Partial resubmit of r296215, which improved PDB Stream Library.

This was reverted because it was breaking some builds, and
because of incorrect error code usage.  Since the CL was
large and contained many different things, I'm resubmitting
it in pieces.

This portion is NFC, and consists of:

1) Renaming classes to follow a consistent naming convention.
2) Fixing the const-ness of the interface methods.
3) Adding detailed doxygen comments.
4) Fixing a few instances of passing `const BinaryStream& X`.  These
   are now passed as `BinaryStreamRef X`.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@296394 91177308-0d34-0410-b5e6-96231b3b80d8

include/llvm/DebugInfo/CodeView/CVRecord.h

@@ -48,15 +48,13 @@ template <typename Kind> class CVRecord {
 
 } // end namespace codeview
 
-namespace msf {
-
 template <typename Kind>
 struct VarStreamArrayExtractor<codeview::CVRecord<Kind>> {
-  Error operator()(ReadableStreamRef Stream, uint32_t &Len,
+  Error operator()(BinaryStreamRef Stream, uint32_t &Len,
                    codeview::CVRecord<Kind> &Item) const {
     using namespace codeview;
     const RecordPrefix *Prefix = nullptr;
-    StreamReader Reader(Stream);
+    BinaryStreamReader Reader(Stream);
     uint32_t Offset = Reader.getOffset();
 
     if (auto EC = Reader.readObject(Prefix))
@@ -76,8 +74,6 @@ struct VarStreamArrayExtractor<codeview::CVRecord<Kind>> {
   }
 };
 
-} // end namespace msf
-
 } // end namespace llvm
 
 #endif // LLVM_DEBUGINFO_CODEVIEW_RECORDITERATOR_H

include/llvm/DebugInfo/CodeView/CVTypeVisitor.h

@@ -34,7 +34,7 @@ class CVTypeVisitor {
   Error visitTypeStream(CVTypeRange Types);
 
   Error visitFieldListMemberStream(ArrayRef<uint8_t> FieldList);
-  Error visitFieldListMemberStream(msf::StreamReader Reader);
+  Error visitFieldListMemberStream(BinaryStreamReader Reader);
 
 private:
   /// The interface to the class that gets notified of each visitation.

include/llvm/DebugInfo/CodeView/CodeViewRecordIO.h

@@ -33,8 +33,8 @@ class CodeViewRecordIO {
   }
 
 public:
-  explicit CodeViewRecordIO(msf::StreamReader &Reader) : Reader(&Reader) {}
-  explicit CodeViewRecordIO(msf::StreamWriter &Writer) : Writer(&Writer) {}
+  explicit CodeViewRecordIO(BinaryStreamReader &Reader) : Reader(&Reader) {}
+  explicit CodeViewRecordIO(BinaryStreamWriter &Writer) : Writer(&Writer) {}
 
   Error beginRecord(Optional<uint32_t> MaxLength);
   Error endRecord();
@@ -160,8 +160,8 @@ class CodeViewRecordIO {
 
   SmallVector<RecordLimit, 2> Limits;
 
-  msf::StreamReader *Reader = nullptr;
-  msf::StreamWriter *Writer = nullptr;
+  BinaryStreamReader *Reader = nullptr;
+  BinaryStreamWriter *Writer = nullptr;
 };
 
 } // end namespace codeview

include/llvm/DebugInfo/CodeView/ModuleSubstream.h

@@ -59,31 +59,29 @@ struct ColumnNumberEntry {
 class ModuleSubstream {
 public:
   ModuleSubstream();
-  ModuleSubstream(ModuleSubstreamKind Kind, msf::ReadableStreamRef Data);
-  static Error initialize(msf::ReadableStreamRef Stream, ModuleSubstream &Info);
+  ModuleSubstream(ModuleSubstreamKind Kind, BinaryStreamRef Data);
+  static Error initialize(BinaryStreamRef Stream, ModuleSubstream &Info);
   uint32_t getRecordLength() const;
   ModuleSubstreamKind getSubstreamKind() const;
-  msf::ReadableStreamRef getRecordData() const;
+  BinaryStreamRef getRecordData() const;
 
 private:
   ModuleSubstreamKind Kind;
-  msf::ReadableStreamRef Data;
+  BinaryStreamRef Data;
 };
 
-typedef msf::VarStreamArray<ModuleSubstream> ModuleSubstreamArray;
+typedef VarStreamArray<ModuleSubstream> ModuleSubstreamArray;
 } // namespace codeview
 
-namespace msf {
 template <> struct VarStreamArrayExtractor<codeview::ModuleSubstream> {
-  Error operator()(ReadableStreamRef Stream, uint32_t &Length,
+  Error operator()(BinaryStreamRef Stream, uint32_t &Length,
                    codeview::ModuleSubstream &Info) const {
     if (auto EC = codeview::ModuleSubstream::initialize(Stream, Info))
       return EC;
     Length = Info.getRecordLength();
     return Error::success();
   }
 };
-} // namespace msf
 } // namespace llvm
 
 #endif // LLVM_DEBUGINFO_CODEVIEW_MODULESUBSTREAM_H

include/llvm/DebugInfo/CodeView/ModuleSubstreamVisitor.h

@@ -28,8 +28,8 @@ namespace codeview {
 
 struct LineColumnEntry {
   support::ulittle32_t NameIndex;
-  msf::FixedStreamArray<LineNumberEntry> LineNumbers;
-  msf::FixedStreamArray<ColumnNumberEntry> Columns;
+  FixedStreamArray<LineNumberEntry> LineNumbers;
+  FixedStreamArray<ColumnNumberEntry> Columns;
 };
 
 struct FileChecksumEntry {
@@ -38,49 +38,47 @@ struct FileChecksumEntry {
   ArrayRef<uint8_t> Checksum; // The bytes of the checksum.
 };
 
-typedef msf::VarStreamArray<LineColumnEntry> LineInfoArray;
-typedef msf::VarStreamArray<FileChecksumEntry> FileChecksumArray;
+typedef VarStreamArray<LineColumnEntry> LineInfoArray;
+typedef VarStreamArray<FileChecksumEntry> FileChecksumArray;
 
 class IModuleSubstreamVisitor {
 public:
   virtual ~IModuleSubstreamVisitor() = default;
 
   virtual Error visitUnknown(ModuleSubstreamKind Kind,
-                             msf::ReadableStreamRef Data) = 0;
-  virtual Error visitSymbols(msf::ReadableStreamRef Data);
-  virtual Error visitLines(msf::ReadableStreamRef Data,
+                             BinaryStreamRef Data) = 0;
+  virtual Error visitSymbols(BinaryStreamRef Data);
+  virtual Error visitLines(BinaryStreamRef Data,
                            const LineSubstreamHeader *Header,
                            const LineInfoArray &Lines);
-  virtual Error visitStringTable(msf::ReadableStreamRef Data);
-  virtual Error visitFileChecksums(msf::ReadableStreamRef Data,
+  virtual Error visitStringTable(BinaryStreamRef Data);
+  virtual Error visitFileChecksums(BinaryStreamRef Data,
                                    const FileChecksumArray &Checksums);
-  virtual Error visitFrameData(msf::ReadableStreamRef Data);
-  virtual Error visitInlineeLines(msf::ReadableStreamRef Data);
-  virtual Error visitCrossScopeImports(msf::ReadableStreamRef Data);
-  virtual Error visitCrossScopeExports(msf::ReadableStreamRef Data);
-  virtual Error visitILLines(msf::ReadableStreamRef Data);
-  virtual Error visitFuncMDTokenMap(msf::ReadableStreamRef Data);
-  virtual Error visitTypeMDTokenMap(msf::ReadableStreamRef Data);
-  virtual Error visitMergedAssemblyInput(msf::ReadableStreamRef Data);
-  virtual Error visitCoffSymbolRVA(msf::ReadableStreamRef Data);
+  virtual Error visitFrameData(BinaryStreamRef Data);
+  virtual Error visitInlineeLines(BinaryStreamRef Data);
+  virtual Error visitCrossScopeImports(BinaryStreamRef Data);
+  virtual Error visitCrossScopeExports(BinaryStreamRef Data);
+  virtual Error visitILLines(BinaryStreamRef Data);
+  virtual Error visitFuncMDTokenMap(BinaryStreamRef Data);
+  virtual Error visitTypeMDTokenMap(BinaryStreamRef Data);
+  virtual Error visitMergedAssemblyInput(BinaryStreamRef Data);
+  virtual Error visitCoffSymbolRVA(BinaryStreamRef Data);
 };
 
 Error visitModuleSubstream(const ModuleSubstream &R,
                            IModuleSubstreamVisitor &V);
 } // end namespace codeview
 
-namespace msf {
-
 template <> class VarStreamArrayExtractor<codeview::LineColumnEntry> {
 public:
   VarStreamArrayExtractor(const codeview::LineSubstreamHeader *Header)
       : Header(Header) {}
 
-  Error operator()(ReadableStreamRef Stream, uint32_t &Len,
+  Error operator()(BinaryStreamRef Stream, uint32_t &Len,
                    codeview::LineColumnEntry &Item) const {
     using namespace codeview;
     const LineFileBlockHeader *BlockHeader;
-    StreamReader Reader(Stream);
+    BinaryStreamReader Reader(Stream);
     if (auto EC = Reader.readObject(BlockHeader))
       return EC;
     bool HasColumn = Header->Flags & LineFlags::HaveColumns;
@@ -113,11 +111,11 @@ template <> class VarStreamArrayExtractor<codeview::LineColumnEntry> {
 
 template <> class VarStreamArrayExtractor<codeview::FileChecksumEntry> {
 public:
-  Error operator()(ReadableStreamRef Stream, uint32_t &Len,
+  Error operator()(BinaryStreamRef Stream, uint32_t &Len,
                    codeview::FileChecksumEntry &Item) const {
     using namespace codeview;
     const FileChecksum *Header;
-    StreamReader Reader(Stream);
+    BinaryStreamReader Reader(Stream);
     if (auto EC = Reader.readObject(Header))
       return EC;
     Item.FileNameOffset = Header->FileNameOffset;
@@ -129,8 +127,6 @@ template <> class VarStreamArrayExtractor<codeview::FileChecksumEntry> {
   }
 };
 
-} // end namespace msf
-
 } // end namespace llvm
 
 #endif // LLVM_DEBUGINFO_CODEVIEW_MODULESUBSTREAMVISITOR_H

include/llvm/DebugInfo/CodeView/RecordSerialization.h

@@ -41,37 +41,37 @@ struct RecordPrefix {
 StringRef getBytesAsCharacters(ArrayRef<uint8_t> LeafData);
 StringRef getBytesAsCString(ArrayRef<uint8_t> LeafData);
 
-inline Error consume(msf::StreamReader &Reader) { return Error::success(); }
+inline Error consume(BinaryStreamReader &Reader) { return Error::success(); }
 
 /// Decodes a numeric "leaf" value. These are integer literals encountered in
 /// the type stream. If the value is positive and less than LF_NUMERIC (1 <<
 /// 15), it is emitted directly in Data. Otherwise, it has a tag like LF_CHAR
 /// that indicates the bitwidth and sign of the numeric data.
-Error consume(msf::StreamReader &Reader, APSInt &Num);
+Error consume(BinaryStreamReader &Reader, APSInt &Num);
 
 /// Decodes a numeric leaf value that is known to be a particular type.
-Error consume_numeric(msf::StreamReader &Reader, uint64_t &Value);
+Error consume_numeric(BinaryStreamReader &Reader, uint64_t &Value);
 
 /// Decodes signed and unsigned fixed-length integers.
-Error consume(msf::StreamReader &Reader, uint32_t &Item);
-Error consume(msf::StreamReader &Reader, int32_t &Item);
+Error consume(BinaryStreamReader &Reader, uint32_t &Item);
+Error consume(BinaryStreamReader &Reader, int32_t &Item);
 
 /// Decodes a null terminated string.
-Error consume(msf::StreamReader &Reader, StringRef &Item);
+Error consume(BinaryStreamReader &Reader, StringRef &Item);
 
 Error consume(StringRef &Data, APSInt &Num);
 Error consume(StringRef &Data, uint32_t &Item);
 
 /// Decodes an arbitrary object whose layout matches that of the underlying
 /// byte sequence, and returns a pointer to the object.
-template <typename T> Error consume(msf::StreamReader &Reader, T *&Item) {
+template <typename T> Error consume(BinaryStreamReader &Reader, T *&Item) {
   return Reader.readObject(Item);
 }
 
 template <typename T, typename U> struct serialize_conditional_impl {
   serialize_conditional_impl(T &Item, U Func) : Item(Item), Func(Func) {}
 
-  Error deserialize(msf::StreamReader &Reader) const {
+  Error deserialize(BinaryStreamReader &Reader) const {
     if (!Func())
       return Error::success();
     return consume(Reader, Item);
@@ -89,7 +89,7 @@ serialize_conditional_impl<T, U> serialize_conditional(T &Item, U Func) {
 template <typename T, typename U> struct serialize_array_impl {
   serialize_array_impl(ArrayRef<T> &Item, U Func) : Item(Item), Func(Func) {}
 
-  Error deserialize(msf::StreamReader &Reader) const {
+  Error deserialize(BinaryStreamReader &Reader) const {
     return Reader.readArray(Item, Func());
   }
 
@@ -100,7 +100,7 @@ template <typename T, typename U> struct serialize_array_impl {
 template <typename T> struct serialize_vector_tail_impl {
   serialize_vector_tail_impl(std::vector<T> &Item) : Item(Item) {}
 
-  Error deserialize(msf::StreamReader &Reader) const {
+  Error deserialize(BinaryStreamReader &Reader) const {
     T Field;
     // Stop when we run out of bytes or we hit record padding bytes.
     while (!Reader.empty() && Reader.peek() < LF_PAD0) {
@@ -118,14 +118,14 @@ struct serialize_null_term_string_array_impl {
   serialize_null_term_string_array_impl(std::vector<StringRef> &Item)
       : Item(Item) {}
 
-  Error deserialize(msf::StreamReader &Reader) const {
+  Error deserialize(BinaryStreamReader &Reader) const {
     if (Reader.empty())
       return make_error<CodeViewError>(cv_error_code::insufficient_buffer,
                                        "Null terminated string is empty!");
 
     while (Reader.peek() != 0) {
       StringRef Field;
-      if (auto EC = Reader.readZeroString(Field))
+      if (auto EC = Reader.readCString(Field))
         return EC;
       Item.push_back(Field);
     }
@@ -138,7 +138,7 @@ struct serialize_null_term_string_array_impl {
 template <typename T> struct serialize_arrayref_tail_impl {
   serialize_arrayref_tail_impl(ArrayRef<T> &Item) : Item(Item) {}
 
-  Error deserialize(msf::StreamReader &Reader) const {
+  Error deserialize(BinaryStreamReader &Reader) const {
     uint32_t Count = Reader.bytesRemaining() / sizeof(T);
     return Reader.readArray(Item, Count);
   }
@@ -149,7 +149,7 @@ template <typename T> struct serialize_arrayref_tail_impl {
 template <typename T> struct serialize_numeric_impl {
   serialize_numeric_impl(T &Item) : Item(Item) {}
 
-  Error deserialize(msf::StreamReader &Reader) const {
+  Error deserialize(BinaryStreamReader &Reader) const {
     return consume_numeric(Reader, Item);
   }
 
@@ -201,42 +201,42 @@ template <typename T> serialize_numeric_impl<T> serialize_numeric(T &Item) {
 #define CV_NUMERIC_FIELD(I) serialize_numeric(I)
 
 template <typename T, typename U>
-Error consume(msf::StreamReader &Reader,
+Error consume(BinaryStreamReader &Reader,
               const serialize_conditional_impl<T, U> &Item) {
   return Item.deserialize(Reader);
 }
 
 template <typename T, typename U>
-Error consume(msf::StreamReader &Reader,
+Error consume(BinaryStreamReader &Reader,
               const serialize_array_impl<T, U> &Item) {
   return Item.deserialize(Reader);
 }
 
-inline Error consume(msf::StreamReader &Reader,
+inline Error consume(BinaryStreamReader &Reader,
                      const serialize_null_term_string_array_impl &Item) {
   return Item.deserialize(Reader);
 }
 
 template <typename T>
-Error consume(msf::StreamReader &Reader,
+Error consume(BinaryStreamReader &Reader,
               const serialize_vector_tail_impl<T> &Item) {
   return Item.deserialize(Reader);
 }
 
 template <typename T>
-Error consume(msf::StreamReader &Reader,
+Error consume(BinaryStreamReader &Reader,
               const serialize_arrayref_tail_impl<T> &Item) {
   return Item.deserialize(Reader);
 }
 
 template <typename T>
-Error consume(msf::StreamReader &Reader,
+Error consume(BinaryStreamReader &Reader,
               const serialize_numeric_impl<T> &Item) {
   return Item.deserialize(Reader);
 }
 
 template <typename T, typename U, typename... Args>
-Error consume(msf::StreamReader &Reader, T &&X, U &&Y, Args &&... Rest) {
+Error consume(BinaryStreamReader &Reader, T &&X, U &&Y, Args &&... Rest) {
   if (auto EC = consume(Reader, X))
     return EC;
   return consume(Reader, Y, std::forward<Args>(Rest)...);

include/llvm/DebugInfo/CodeView/SymbolDeserializer.h

@@ -27,8 +27,8 @@ class SymbolDeserializer : public SymbolVisitorCallbacks {
     explicit MappingInfo(ArrayRef<uint8_t> RecordData)
         : Stream(RecordData), Reader(Stream), Mapping(Reader) {}
 
-    msf::ByteStream Stream;
-    msf::StreamReader Reader;
+    BinaryByteStream Stream;
+    BinaryStreamReader Reader;
     SymbolRecordMapping Mapping;
   };
 

include/llvm/DebugInfo/CodeView/SymbolRecord.h

@@ -938,7 +938,7 @@ class ThreadLocalDataSym : public SymbolRecord {
 };
 
 typedef CVRecord<SymbolKind> CVSymbol;
-typedef msf::VarStreamArray<CVSymbol> CVSymbolArray;
+typedef VarStreamArray<CVSymbol> CVSymbolArray;
 
 } // end namespace codeview
 } // end namespace llvm

include/llvm/DebugInfo/CodeView/SymbolRecordMapping.h

@@ -14,16 +14,14 @@
 #include "llvm/DebugInfo/CodeView/SymbolVisitorCallbacks.h"
 
 namespace llvm {
-namespace msf {
-class StreamReader;
-class StreamWriter;
-}
+class BinaryStreamReader;
+class BinaryStreamWriter;
 
 namespace codeview {
 class SymbolRecordMapping : public SymbolVisitorCallbacks {
 public:
-  explicit SymbolRecordMapping(msf::StreamReader &Reader) : IO(Reader) {}
-  explicit SymbolRecordMapping(msf::StreamWriter &Writer) : IO(Writer) {}
+  explicit SymbolRecordMapping(BinaryStreamReader &Reader) : IO(Reader) {}
+  explicit SymbolRecordMapping(BinaryStreamWriter &Writer) : IO(Writer) {}
 
   Error visitSymbolBegin(CVSymbol &Record) override;
   Error visitSymbolEnd(CVSymbol &Record) override;