Apache OpenDALâ„¢ C++ Binding
The C++ binding for Apache OpenDALâ„¢
Loading...
Searching...
No Matches
opendal.hpp
Go to the documentation of this file.
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20#pragma once
21
22#include <algorithm>
23#include <cstdint>
24#include <cstring>
25#include <iostream>
26#include <memory>
27#include <optional>
28#include <string>
29#include <unordered_map>
30#include <vector>
31
32#include "data_structure.hpp"
33#include "layer.hpp"
34
35namespace opendal {
36
37namespace ffi {
38class Operator;
39class Reader;
40class Lister;
41class Writer;
42} // namespace ffi
43
44class Reader;
45class Lister;
46class Writer;
47
52class Operator {
53 public:
54 Operator() noexcept;
55
63 Operator(std::string_view scheme,
64 const std::unordered_map<std::string, std::string> &config = {},
65 std::vector<std::unique_ptr<OperatorOption>> options = {});
66
67 // Disable copy and assign
68 Operator(const Operator &) = delete;
69 Operator &operator=(const Operator &) = delete;
70
71 // Enable move
72 Operator(Operator &&other) noexcept;
73 Operator &operator=(Operator &&other) noexcept;
74
75 ~Operator() noexcept;
76
82 bool Available() const;
83
92 std::string Read(std::string_view path);
93
101 std::string Read(std::string_view path, const ReadOptions &options);
102
109 void Write(std::string_view path, std::string_view data);
110
118 void Write(std::string_view path, std::string_view data,
119 const WriteOptions &options);
120
127 Reader GetReader(std::string_view path);
128 Reader GetReader(std::string_view path, const ReaderOptions &options);
129 Writer GetWriter(std::string_view path);
130 Writer GetWriter(std::string_view path, const WriteOptions &options);
131
138 [[deprecated("Use Exists() instead.")]]
139 bool IsExist(std::string_view path);
140
147 bool Exists(std::string_view path);
148
154 void CreateDir(std::string_view path);
155
162 void Copy(std::string_view src, std::string_view dst);
163 void Copy(std::string_view src, std::string_view dst,
164 const CopyOptions &options);
165
172 void Rename(std::string_view src, std::string_view dst);
173 void Rename(std::string_view src, std::string_view dst,
174 const RenameOptions &options);
175
181 void Remove(std::string_view path);
182 void Remove(std::string_view path, const DeleteOptions &options);
183 void RemoveAll(const std::vector<std::string> &paths);
184
191 Metadata Stat(std::string_view path);
192 Metadata Stat(std::string_view path, const StatOptions &options);
193
201 std::vector<Entry> List(std::string_view path);
202 std::vector<Entry> List(std::string_view path, const ListOptions &options);
203
204 Lister GetLister(std::string_view path);
205 Lister GetLister(std::string_view path, const ListOptions &options);
207
208 private:
209 void Destroy() noexcept;
210
211 ffi::Operator *operator_{nullptr};
212 };
213
223class Reader {
224 public:
225 Reader(Reader &&other) noexcept;
226
227 ~Reader() noexcept;
228
229 std::streamsize Read(void *s, std::streamsize n);
230
231 std::streamsize ReadAt(void *s, std::streamsize n, uint64_t offset);
232
233 std::streampos Seek(std::streamoff off, std::ios_base::seekdir way);
234
235 private:
236 friend class Operator;
237
238 Reader(ffi::Reader *pointer) noexcept;
239
240 void Destroy() noexcept;
241
242 ffi::Reader *reader_{nullptr};
243};
244
252class Writer {
253 public:
254 Writer(Writer &&other) noexcept;
255
256 ~Writer() noexcept;
257
258 void Write(std::string_view data);
259
260 void Flush();
261
262 void Close();
263
264 private:
265 friend class Operator;
266
267 Writer(ffi::Writer *pointer) noexcept;
268
269 void Destroy() noexcept;
270
271 ffi::Writer *writer_{nullptr};
272};
273
280class ReaderStream : public std::istream {
281 public:
282 class ReaderStreamBuf : public std::streambuf {
283 public:
285 : reader_(std::move(reader)), buffer_start_pos_(0) {
286 setg(buffer_, buffer_, buffer_);
287 }
288
289 protected:
290 std::streamsize xsgetn(char *s, std::streamsize count) override {
291 std::streamsize total_read = 0;
292
293 while (total_read < count) {
294 if (gptr() < egptr()) {
295 std::streamsize available_bytes = egptr() - gptr();
296 std::streamsize to_copy =
297 (std::min)(available_bytes, count - total_read);
298 std::memcpy(s + total_read, gptr(), to_copy);
299 gbump(to_copy);
300 total_read += to_copy;
301 continue;
302 }
303
304 if (underflow() == traits_type::eof()) break;
305 }
306
307 return total_read;
308 }
309
310 int_type underflow() override {
311 if (gptr() < egptr()) {
312 return traits_type::to_int_type(*gptr());
313 }
314
315 // Update the buffer start position to current reader position
316 buffer_start_pos_ += static_cast<std::streamoff>(egptr() - eback());
317
318 std::streamsize n = reader_.Read(buffer_, sizeof(buffer_));
319 if (n <= 0) {
320 return traits_type::eof();
321 }
322
323 setg(buffer_, buffer_, buffer_ + n);
324 return traits_type::to_int_type(*gptr());
325 }
326
327 int_type uflow() override {
328 int_type result = underflow();
329 if (result != traits_type::eof()) {
330 gbump(1);
331 }
332 return result;
333 }
334
335 std::streampos seekoff(std::streamoff off, std::ios_base::seekdir dir,
336 std::ios_base::openmode which) override {
337 if (dir == std::ios_base::cur && off == 0) {
338 // tellg() case - return current position
339 return buffer_start_pos_ + static_cast<std::streamoff>(gptr() - eback());
340 }
341
342 // Actual seek operation
343 std::streampos new_pos = reader_.Seek(off, dir);
344 if (new_pos != std::streampos(-1)) {
345 buffer_start_pos_ = new_pos;
346 setg(buffer_, buffer_, buffer_);
347 }
348 return new_pos;
349 }
350
351 std::streampos seekpos(std::streampos pos,
352 std::ios_base::openmode which) override {
353 return seekoff(pos, std::ios_base::beg, which);
354 }
355
356 private:
357 Reader reader_;
358 char buffer_[8192];
359 std::streampos buffer_start_pos_;
360 };
361
363 : std::istream(&buf_), buf_(std::move(reader)) {}
364
365 private:
366 ReaderStreamBuf buf_;
367};
368
381class Lister {
382 public:
383 Lister(Lister &&other) noexcept;
384
385 ~Lister() noexcept;
386
393 class Iterator {
394 public:
395 using iterator_category = std::input_iterator_tag;
397 using difference_type = std::ptrdiff_t;
398 using pointer = Entry *;
399 using reference = Entry &;
400
401 Iterator(Lister &lister) : lister_{lister} {
402 current_entry_ = lister_.Next();
403 }
404
405 Entry operator*() { return current_entry_.value(); }
406
408 if (current_entry_) {
409 current_entry_ = lister_.Next();
410 }
411 return *this;
412 }
413
414 bool operator!=(const Iterator &other) const {
415 return current_entry_ != std::nullopt ||
416 other.current_entry_ != std::nullopt;
417 }
418
419 protected:
420 // Only used for end iterator
421 Iterator(Lister &lister, bool /*end*/) noexcept : lister_(lister) {}
422
423 private:
424 friend class Lister;
425
426 Lister &lister_;
427 std::optional<Entry> current_entry_;
428 };
429
435 std::optional<Entry> Next();
436
437 Iterator begin() { return Iterator(*this); }
438 Iterator end() { return Iterator(*this, true); }
439
440 private:
441 friend class Operator;
442
443 Lister(ffi::Lister *pointer) noexcept;
444
445 void Destroy() noexcept;
446
447 ffi::Lister *lister_{nullptr};
448};
449
450} // namespace opendal
Definition data_structure.hpp:340
The entry of a file or directory.
Definition data_structure.hpp:190
Definition opendal.hpp:393
std::ptrdiff_t difference_type
Definition opendal.hpp:397
Entry operator*()
Definition opendal.hpp:405
Entry * pointer
Definition opendal.hpp:398
Entry value_type
Definition opendal.hpp:396
Iterator(Lister &lister)
Definition opendal.hpp:401
Entry & reference
Definition opendal.hpp:399
std::input_iterator_tag iterator_category
Definition opendal.hpp:395
friend class Lister
Definition opendal.hpp:424
Iterator(Lister &lister, bool) noexcept
Definition opendal.hpp:421
Iterator & operator++()
Definition opendal.hpp:407
bool operator!=(const Iterator &other) const
Definition opendal.hpp:414
Lister is designed to list the entries of a directory.
Definition opendal.hpp:381
friend class Operator
Definition opendal.hpp:441
std::optional< Entry > Next()
Get the next entry of the lister.
~Lister() noexcept
Lister(Lister &&other) noexcept
Iterator begin()
Definition opendal.hpp:437
Iterator end()
Definition opendal.hpp:438
The metadata of a file or directory.
Definition data_structure.hpp:51
void RemoveAll(const std::vector< std::string > &paths)
void Remove(std::string_view path)
Remove a file or directory.
Reader GetReader(std::string_view path)
Read data from the operator.
Operator() noexcept
Capability Info()
void Rename(std::string_view src, std::string_view dst)
Rename a file from src to dst.
Operator(Operator &&other) noexcept
bool Exists(std::string_view path)
Check if the path exists.
bool Available() const
Check if the operator is available.
~Operator() noexcept
std::string Read(std::string_view path)
Read data from the operator.
Operator(const Operator &)=delete
bool IsExist(std::string_view path)
Check if the path exists.
Operator & operator=(const Operator &)=delete
Lister GetLister(std::string_view path)
void CreateDir(std::string_view path)
Create a directory.
Operator & operator=(Operator &&other) noexcept
void Copy(std::string_view src, std::string_view dst)
Copy a file from src to dst.
Writer GetWriter(std::string_view path)
void Write(std::string_view path, std::string_view data)
Write data to the operator.
std::vector< Entry > List(std::string_view path)
List the entries of a directory.
Metadata Stat(std::string_view path)
Get the metadata of a file or directory.
int_type uflow() override
Definition opendal.hpp:327
std::streampos seekoff(std::streamoff off, std::ios_base::seekdir dir, std::ios_base::openmode which) override
Definition opendal.hpp:335
std::streamsize xsgetn(char *s, std::streamsize count) override
Definition opendal.hpp:290
int_type underflow() override
Definition opendal.hpp:310
std::streampos seekpos(std::streampos pos, std::ios_base::openmode which) override
Definition opendal.hpp:351
ReaderStreamBuf(Reader &&reader)
Definition opendal.hpp:284
ReaderStream(Reader &&reader)
Definition opendal.hpp:362
Reader is designed to read data from the operator.
Definition opendal.hpp:223
Reader(Reader &&other) noexcept
friend class Operator
Definition opendal.hpp:236
std::streamsize ReadAt(void *s, std::streamsize n, uint64_t offset)
std::streamsize Read(void *s, std::streamsize n)
std::streampos Seek(std::streamoff off, std::ios_base::seekdir way)
~Reader() noexcept
Writer is designed to write a sequence of byte buffers to an object.
Definition opendal.hpp:252
friend class Operator
Definition opendal.hpp:265
~Writer() noexcept
void Write(std::string_view data)
Writer(Writer &&other) noexcept
Definition layer.hpp:31
Definition data_structure.hpp:29
Options for copy operations.
Definition data_structure.hpp:300
Options for delete operations.
Definition data_structure.hpp:321
Options for list and lister operations.
Definition data_structure.hpp:330
Options for read operations.
Definition data_structure.hpp:245
Options for creating readers.
Definition data_structure.hpp:265
Options for rename operations.
Definition data_structure.hpp:313
Options for stat operations.
Definition data_structure.hpp:230
Options for write and writer operations.
Definition data_structure.hpp:282