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
30namespace arrow {
31
32class Buffer;
33class Status;
34
35namespace io {
36
37struct FileMode {
38 enum type { READ, WRITE, READWRITE };
39};
40
41struct ObjectType {
42 enum type { FILE, DIRECTORY };
43};
44
45struct ARROW_EXPORT FileStatistics {
46 /// Size of file, -1 if finding length is unsupported
47 int64_t size;
48 ObjectType::type kind;
49};
50
51class 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
67class 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
85class ARROW_EXPORT Seekable {
86 public:
87 virtual ~Seekable() = default;
88 virtual Status Seek(int64_t position) = 0;
89};
90
91class 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
103class 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
113class ARROW_EXPORT OutputStream : virtual public FileInterface, public Writable {
114 protected:
115 OutputStream() = default;
116};
117
118class 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
139class 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
177class 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
186using WriteableFile = WritableFile;
187
188class ARROW_EXPORT ReadWriteFileInterface : public RandomAccessFile, public WritableFile {
189 protected:
190 ReadWriteFileInterface() { RandomAccessFile::set_mode(FileMode::READWRITE); }
191};
192
193using ReadableFileInterface = RandomAccessFile;
194
195} // namespace io
196} // namespace arrow
197
198#endif // ARROW_IO_INTERFACES_H
199