Apache Arrow (C++)
A columnar in-memory analytics layer designed to accelerate big data.
message.h
Go to the documentation of this file.
1 // Licensed to the Apache Software Foundation (ASF) under one
2 // or more contributor license agreements. See the NOTICE file
3 // distributed with this work for additional information
4 // regarding copyright ownership. The ASF licenses this file
5 // to you under the Apache License, Version 2.0 (the
6 // "License"); you may not use this file except in compliance
7 // with the License. You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing,
12 // software distributed under the License is distributed on an
13 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14 // KIND, either express or implied. See the License for the
15 // specific language governing permissions and limitations
16 // under the License.
17 
18 // C++ object model and user API for interprocess schema messaging
19 
20 #ifndef ARROW_IPC_MESSAGE_H
21 #define ARROW_IPC_MESSAGE_H
22 
23 #include <cstdint>
24 #include <memory>
25 #include <string>
26 
27 #include "arrow/status.h"
28 #include "arrow/util/macros.h"
29 #include "arrow/util/visibility.h"
30 
31 namespace arrow {
32 
33 class Buffer;
34 
35 namespace io {
36 
37 class FileInterface;
38 class InputStream;
39 class OutputStream;
40 class RandomAccessFile;
41 
42 } // namespace io
43 
44 namespace ipc {
45 
46 enum class MetadataVersion : char {
48  V1,
49 
51  V2,
52 
54  V3,
55 
57  V4
58 };
59 
60 // ARROW-109: We set this number arbitrarily to help catch user mistakes. For
61 // deeply nested schemas, it is expected the user will indicate explicitly the
62 // maximum allowed recursion depth
63 constexpr int kMaxNestingDepth = 64;
64 
65 // Read interface classes. We do not fully deserialize the flatbuffers so that
66 // individual fields metadata can be retrieved from very large schema without
67 //
68 
71 class ARROW_EXPORT Message {
72  public:
73  enum Type { NONE, SCHEMA, DICTIONARY_BATCH, RECORD_BATCH, TENSOR };
74 
78  Message(const std::shared_ptr<Buffer>& metadata, const std::shared_ptr<Buffer>& body);
79 
80  ~Message();
81 
88  static Status Open(const std::shared_ptr<Buffer>& metadata,
89  const std::shared_ptr<Buffer>& body, std::unique_ptr<Message>* out);
90 
98  static Status ReadFrom(const std::shared_ptr<Buffer>& metadata, io::InputStream* stream,
99  std::unique_ptr<Message>* out);
100 
110  static Status ReadFrom(const int64_t offset, const std::shared_ptr<Buffer>& metadata,
111  io::RandomAccessFile* file, std::unique_ptr<Message>* out);
112 
117  bool Equals(const Message& other) const;
118 
122  std::shared_ptr<Buffer> metadata() const;
123 
127  std::shared_ptr<Buffer> body() const;
128 
131  int64_t body_length() const;
132 
134  Type type() const;
135 
137  MetadataVersion metadata_version() const;
138 
139  const void* header() const;
140 
150  Status SerializeTo(io::OutputStream* file, int32_t alignment,
151  int64_t* output_length) const;
152 
154  bool Verify() const;
155 
156  private:
157  // Hide serialization details from user API
158  class MessageImpl;
159  std::unique_ptr<MessageImpl> impl_;
160 
162 };
163 
164 ARROW_EXPORT std::string FormatMessageType(Message::Type type);
165 
168 class ARROW_EXPORT MessageReader {
169  public:
170  virtual ~MessageReader() = default;
171 
173  static std::unique_ptr<MessageReader> Open(io::InputStream* stream);
174 
176  static std::unique_ptr<MessageReader> Open(
177  const std::shared_ptr<io::InputStream>& owned_stream);
178 
183  virtual Status ReadNextMessage(std::unique_ptr<Message>* message) = 0;
184 };
185 
200 ARROW_EXPORT
201 Status ReadMessage(const int64_t offset, const int32_t metadata_length,
202  io::RandomAccessFile* file, std::unique_ptr<Message>* message);
203 
210 ARROW_EXPORT
211 Status AlignStream(io::InputStream* stream, int32_t alignment = 8);
212 
219 ARROW_EXPORT
220 Status AlignStream(io::OutputStream* stream, int32_t alignment = 8);
221 
224 ARROW_EXPORT
225 Status CheckAligned(io::FileInterface* stream, int32_t alignment = 8);
226 
232 ARROW_EXPORT
233 Status ReadMessage(io::InputStream* stream, std::unique_ptr<Message>* message);
234 
235 } // namespace ipc
236 } // namespace arrow
237 
238 #endif // ARROW_IPC_MESSAGE_H
Definition: interfaces.h:111
std::string FormatMessageType(Message::Type type)
Main data type enumeration.
Definition: type.h:47
An IPC message including metadata and body.
Definition: message.h:71
#define ARROW_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: macros.h:23
Definition: interfaces.h:116
Definition: interfaces.h:127
Status ReadMessage(const int64_t offset, const int32_t metadata_length, io::RandomAccessFile *file, std::unique_ptr< Message > *message)
Read encapsulated RPC message from position in file.
Definition: interfaces.h:66
Definition: status.h:95
Type
Definition: message.h:73
Status AlignStream(io::InputStream *stream, int32_t alignment=8)
Advance stream to an 8-byte offset if its position is not a multiple of 8 already.
Top-level namespace for Apache Arrow C++ API.
Definition: adapter.h:32
MetadataVersion
Definition: message.h:46
Status CheckAligned(io::FileInterface *stream, int32_t alignment=8)
Return error Status if file position is not a multiple of the indicated alignment.
constexpr int kMaxNestingDepth
Definition: message.h:63
Abstract interface for a sequence of messages.
Definition: message.h:168
::arrow::Buffer Buffer
Definition: memory.h:54