LLVM  14.0.0git
BinaryStream.h
Go to the documentation of this file.
1 //===- BinaryStream.h - Base interface for a stream of data -----*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef LLVM_SUPPORT_BINARYSTREAM_H
10 #define LLVM_SUPPORT_BINARYSTREAM_H
11 
12 #include "llvm/ADT/ArrayRef.h"
13 #include "llvm/ADT/BitmaskEnum.h"
15 #include "llvm/Support/Endian.h"
16 #include "llvm/Support/Error.h"
17 #include <cstdint>
18 
19 namespace llvm {
20 
22  BSF_None = 0,
23  BSF_Write = 1, // Stream supports writing.
24  BSF_Append = 2, // Writing can occur at offset == length.
25  LLVM_MARK_AS_BITMASK_ENUM(/* LargestValue = */ BSF_Append)
26 };
27 
28 /// An interface for accessing data in a stream-like format, but which
29 /// discourages copying. Instead of specifying a buffer in which to copy
30 /// data on a read, the API returns an ArrayRef to data owned by the stream's
31 /// implementation. Since implementations may not necessarily store data in a
32 /// single contiguous buffer (or even in memory at all), in such cases a it may
33 /// be necessary for an implementation to cache such a buffer so that it can
34 /// return it.
35 class BinaryStream {
36 public:
37  virtual ~BinaryStream() = default;
38 
39  virtual llvm::support::endianness getEndian() const = 0;
40 
41  /// Given an offset into the stream and a number of bytes, attempt to
42  /// read the bytes and set the output ArrayRef to point to data owned by the
43  /// stream.
45  ArrayRef<uint8_t> &Buffer) = 0;
46 
47  /// Given an offset into the stream, read as much as possible without
48  /// copying any data.
50  ArrayRef<uint8_t> &Buffer) = 0;
51 
52  /// Return the number of bytes of data in this stream.
53  virtual uint32_t getLength() = 0;
54 
55  /// Return the properties of this stream.
56  virtual BinaryStreamFlags getFlags() const { return BSF_None; }
57 
58 protected:
60  if (Offset > getLength())
61  return make_error<BinaryStreamError>(stream_error_code::invalid_offset);
62  if (getLength() < DataSize + Offset)
63  return make_error<BinaryStreamError>(stream_error_code::stream_too_short);
64  return Error::success();
65  }
66 };
67 
68 /// A BinaryStream which can be read from as well as written to. Note
69 /// that writing to a BinaryStream always necessitates copying from the input
70 /// buffer to the stream's backing store. Streams are assumed to be buffered
71 /// so that to be portable it is necessary to call commit() on the stream when
72 /// all data has been written.
74 public:
75  ~WritableBinaryStream() override = default;
76 
77  /// Attempt to write the given bytes into the stream at the desired
78  /// offset. This will always necessitate a copy. Cannot shrink or grow the
79  /// stream, only writes into existing allocated space.
81 
82  /// For buffered streams, commits changes to the backing store.
83  virtual Error commit() = 0;
84 
85  /// Return the properties of this stream.
86  BinaryStreamFlags getFlags() const override { return BSF_Write; }
87 
88 protected:
90  if (!(getFlags() & BSF_Append))
91  return checkOffsetForRead(Offset, DataSize);
92 
93  if (Offset > getLength())
94  return make_error<BinaryStreamError>(stream_error_code::invalid_offset);
95  return Error::success();
96  }
97 };
98 
99 } // end namespace llvm
100 
101 #endif // LLVM_SUPPORT_BINARYSTREAM_H
llvm::Check::Size
@ Size
Definition: FileCheck.h:73
llvm::BinaryStream
An interface for accessing data in a stream-like format, but which discourages copying.
Definition: BinaryStream.h:35
llvm
---------------------— PointerInfo ------------------------------------—
Definition: AllocatorList.h:23
LLVM_MARK_AS_BITMASK_ENUM
#define LLVM_MARK_AS_BITMASK_ENUM(LargestValue)
LLVM_MARK_AS_BITMASK_ENUM lets you opt in an individual enum type so you can perform bitwise operatio...
Definition: BitmaskEnum.h:41
llvm::Error::success
static ErrorSuccess success()
Create a success value.
Definition: Error.h:332
Error.h
llvm::WritableBinaryStream::commit
virtual Error commit()=0
For buffered streams, commits changes to the backing store.
Offset
uint64_t Offset
Definition: ELFObjHandler.cpp:81
llvm::BSF_None
@ BSF_None
Definition: BinaryStream.h:22
llvm::Data
@ Data
Definition: SIMachineScheduler.h:56
llvm::stream_error_code::invalid_offset
@ invalid_offset
llvm::BinaryStreamFlags
BinaryStreamFlags
Definition: BinaryStream.h:21
BinaryStreamError.h
llvm::WritableBinaryStream::~WritableBinaryStream
~WritableBinaryStream() override=default
llvm::BinaryStream::getFlags
virtual BinaryStreamFlags getFlags() const
Return the properties of this stream.
Definition: BinaryStream.h:56
llvm::BSF_Append
@ BSF_Append
Definition: BinaryStream.h:24
llvm::BinaryStream::checkOffsetForRead
Error checkOffsetForRead(uint32_t Offset, uint32_t DataSize)
Definition: BinaryStream.h:59
llvm::WritableBinaryStream::checkOffsetForWrite
Error checkOffsetForWrite(uint32_t Offset, uint32_t DataSize)
Definition: BinaryStream.h:89
ArrayRef.h
llvm::ArrayRef< uint8_t >
BitmaskEnum.h
uint32_t
llvm::BinaryStream::readLongestContiguousChunk
virtual Error readLongestContiguousChunk(uint32_t Offset, ArrayRef< uint8_t > &Buffer)=0
Given an offset into the stream, read as much as possible without copying any data.
llvm::BinaryStream::getLength
virtual uint32_t getLength()=0
Return the number of bytes of data in this stream.
llvm::BSF_Write
@ BSF_Write
Definition: BinaryStream.h:23
llvm::Error
Lightweight error class with error context and mandatory checking.
Definition: Error.h:157
llvm::BinaryStream::readBytes
virtual Error readBytes(uint32_t Offset, uint32_t Size, ArrayRef< uint8_t > &Buffer)=0
Given an offset into the stream and a number of bytes, attempt to read the bytes and set the output A...
llvm::BinaryStream::~BinaryStream
virtual ~BinaryStream()=default
llvm::WritableBinaryStream::writeBytes
virtual Error writeBytes(uint32_t Offset, ArrayRef< uint8_t > Data)=0
Attempt to write the given bytes into the stream at the desired offset.
llvm::stream_error_code::stream_too_short
@ stream_too_short
llvm::support::endianness
endianness
Definition: Endian.h:27
llvm::BinaryStream::getEndian
virtual llvm::support::endianness getEndian() const =0
Endian.h
llvm::WritableBinaryStream
A BinaryStream which can be read from as well as written to.
Definition: BinaryStream.h:73
llvm::WritableBinaryStream::getFlags
BinaryStreamFlags getFlags() const override
Return the properties of this stream.
Definition: BinaryStream.h:86