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 | #ifndef ARROW_IO_INTERFACES_H |
19 | #define ARROW_IO_INTERFACES_H |
20 | |
21 | #include <cstdint> |
22 | #include <memory> |
23 | #include <string> |
24 | #include <vector> |
25 | |
26 | #include "arrow/util/macros.h" |
27 | #include "arrow/util/string_view.h" |
28 | #include "arrow/util/visibility.h" |
29 | |
30 | namespace arrow { |
31 | |
32 | class Buffer; |
33 | class Status; |
34 | |
35 | namespace io { |
36 | |
37 | struct FileMode { |
38 | enum type { READ, WRITE, READWRITE }; |
39 | }; |
40 | |
41 | struct ObjectType { |
42 | enum type { FILE, DIRECTORY }; |
43 | }; |
44 | |
45 | struct ARROW_EXPORT FileStatistics { |
46 | /// Size of file, -1 if finding length is unsupported |
47 | int64_t size; |
48 | ObjectType::type kind; |
49 | }; |
50 | |
51 | class ARROW_EXPORT FileSystem { |
52 | public: |
53 | virtual ~FileSystem() = default; |
54 | |
55 | virtual Status MakeDirectory(const std::string& path) = 0; |
56 | |
57 | virtual Status DeleteDirectory(const std::string& path) = 0; |
58 | |
59 | virtual Status GetChildren(const std::string& path, |
60 | std::vector<std::string>* listing) = 0; |
61 | |
62 | virtual Status Rename(const std::string& src, const std::string& dst) = 0; |
63 | |
64 | virtual Status Stat(const std::string& path, FileStatistics* stat) = 0; |
65 | }; |
66 | |
67 | class ARROW_EXPORT FileInterface { |
68 | public: |
69 | virtual ~FileInterface() = 0; |
70 | virtual Status Close() = 0; |
71 | virtual Status Tell(int64_t* position) const = 0; |
72 | virtual bool closed() const = 0; |
73 | |
74 | FileMode::type mode() const { return mode_; } |
75 | |
76 | protected: |
77 | FileInterface() : mode_(FileMode::READ) {} |
78 | FileMode::type mode_; |
79 | void set_mode(FileMode::type mode) { mode_ = mode; } |
80 | |
81 | private: |
82 | ARROW_DISALLOW_COPY_AND_ASSIGN(FileInterface); |
83 | }; |
84 | |
85 | class ARROW_EXPORT Seekable { |
86 | public: |
87 | virtual ~Seekable() = default; |
88 | virtual Status Seek(int64_t position) = 0; |
89 | }; |
90 | |
91 | class ARROW_EXPORT Writable { |
92 | public: |
93 | virtual ~Writable() = default; |
94 | |
95 | virtual Status Write(const void* data, int64_t nbytes) = 0; |
96 | |
97 | /// \brief Flush buffered bytes, if any |
98 | virtual Status Flush(); |
99 | |
100 | Status Write(const std::string& data); |
101 | }; |
102 | |
103 | class ARROW_EXPORT Readable { |
104 | public: |
105 | virtual ~Readable() = default; |
106 | |
107 | virtual Status Read(int64_t nbytes, int64_t* bytes_read, void* out) = 0; |
108 | |
109 | // Does not copy if not necessary |
110 | virtual Status Read(int64_t nbytes, std::shared_ptr<Buffer>* out) = 0; |
111 | }; |
112 | |
113 | class ARROW_EXPORT OutputStream : virtual public FileInterface, public Writable { |
114 | protected: |
115 | OutputStream() = default; |
116 | }; |
117 | |
118 | class ARROW_EXPORT InputStream : virtual public FileInterface, virtual public Readable { |
119 | public: |
120 | /// \brief Advance or skip stream indicated number of bytes |
121 | /// \param[in] nbytes the number to move forward |
122 | /// \return Status |
123 | Status Advance(int64_t nbytes); |
124 | |
125 | /// \brief Return string_view to any buffered bytes, up to the indicated |
126 | /// number. View becomes invalid after any operation on file. If the |
127 | /// InputStream is unbuffered, returns 0-length string_view |
128 | /// \param[in] nbytes the maximum number of bytes to see |
129 | /// \return arrow::util::string_view |
130 | virtual util::string_view Peek(int64_t nbytes) const; |
131 | |
132 | /// \brief Return true if InputStream is capable of zero copy Buffer reads |
133 | virtual bool supports_zero_copy() const; |
134 | |
135 | protected: |
136 | InputStream() = default; |
137 | }; |
138 | |
139 | class ARROW_EXPORT RandomAccessFile : public InputStream, public Seekable { |
140 | public: |
141 | /// Necessary because we hold a std::unique_ptr |
142 | ~RandomAccessFile() override; |
143 | |
144 | virtual Status GetSize(int64_t* size) = 0; |
145 | |
146 | /// \brief Read nbytes at position, provide default implementations using |
147 | /// Read(...), but can be overridden. The default implementation is |
148 | /// thread-safe. It is unspecified whether this method updates the file |
149 | /// position or not. |
150 | /// |
151 | /// \param[in] position Where to read bytes from |
152 | /// \param[in] nbytes The number of bytes to read |
153 | /// \param[out] bytes_read The number of bytes read |
154 | /// \param[out] out The buffer to read bytes into |
155 | /// \return Status |
156 | virtual Status ReadAt(int64_t position, int64_t nbytes, int64_t* bytes_read, void* out); |
157 | |
158 | /// \brief Read nbytes at position, provide default implementations using |
159 | /// Read(...), but can be overridden. The default implementation is |
160 | /// thread-safe. It is unspecified whether this method updates the file |
161 | /// position or not. |
162 | /// |
163 | /// \param[in] position Where to read bytes from |
164 | /// \param[in] nbytes The number of bytes to read |
165 | /// \param[out] out The buffer to read bytes into. The number of bytes read can be |
166 | /// retrieved by calling Buffer::size(). |
167 | virtual Status ReadAt(int64_t position, int64_t nbytes, std::shared_ptr<Buffer>* out); |
168 | |
169 | protected: |
170 | RandomAccessFile(); |
171 | |
172 | private: |
173 | struct ARROW_NO_EXPORT RandomAccessFileImpl; |
174 | std::unique_ptr<RandomAccessFileImpl> interface_impl_; |
175 | }; |
176 | |
177 | class ARROW_EXPORT WritableFile : public OutputStream, public Seekable { |
178 | public: |
179 | virtual Status WriteAt(int64_t position, const void* data, int64_t nbytes) = 0; |
180 | |
181 | protected: |
182 | WritableFile() = default; |
183 | }; |
184 | |
185 | // TODO(wesm): remove this after 0.11 |
186 | using WriteableFile = WritableFile; |
187 | |
188 | class ARROW_EXPORT ReadWriteFileInterface : public RandomAccessFile, public WritableFile { |
189 | protected: |
190 | ReadWriteFileInterface() { RandomAccessFile::set_mode(FileMode::READWRITE); } |
191 | }; |
192 | |
193 | using ReadableFileInterface = RandomAccessFile; |
194 | |
195 | } // namespace io |
196 | } // namespace arrow |
197 | |
198 | #endif // ARROW_IO_INTERFACES_H |
199 | |