Adding all project files

venv/Lib/site-packages/pyarrow/include/arrow/io/file.h

@@ -0,0 +1,221 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// IO interface implementations for OS files
+
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "arrow/io/concurrency.h"
+#include "arrow/io/interfaces.h"
+#include "arrow/util/visibility.h"
+
+namespace arrow {
+
+class Buffer;
+class MemoryPool;
+class Status;
+
+namespace io {
+
+/// \brief An operating system file open in write-only mode.
+class ARROW_EXPORT FileOutputStream : public OutputStream {
+ public:
+  ~FileOutputStream() override;
+
+  /// \brief Open a local file for writing, truncating any existing file
+  /// \param[in] path with UTF8 encoding
+  /// \param[in] append append to existing file, otherwise truncate to 0 bytes
+  /// \return an open FileOutputStream
+  ///
+  /// When opening a new file, any existing file with the indicated path is
+  /// truncated to 0 bytes, deleting any existing data
+  static Result<std::shared_ptr<FileOutputStream>> Open(const std::string& path,
+                                                        bool append = false);
+
+  /// \brief Open a file descriptor for writing.  The underlying file isn't
+  /// truncated.
+  /// \param[in] fd file descriptor
+  /// \return an open FileOutputStream
+  ///
+  /// The file descriptor becomes owned by the OutputStream, and will be closed
+  /// on Close() or destruction.
+  static Result<std::shared_ptr<FileOutputStream>> Open(int fd);
+
+  // OutputStream interface
+  Status Close() override;
+  bool closed() const override;
+  Result<int64_t> Tell() const override;
+
+  // Write bytes to the stream. Thread-safe
+  Status Write(const void* data, int64_t nbytes) override;
+  /// \cond FALSE
+  using Writable::Write;
+  /// \endcond
+
+  int file_descriptor() const;
+
+ private:
+  FileOutputStream();
+
+  class ARROW_NO_EXPORT FileOutputStreamImpl;
+  std::unique_ptr<FileOutputStreamImpl> impl_;
+};
+
+/// \brief An operating system file open in read-only mode.
+///
+/// Reads through this implementation are unbuffered.  If many small reads
+/// need to be issued, it is recommended to use a buffering layer for good
+/// performance.
+class ARROW_EXPORT ReadableFile
+    : public internal::RandomAccessFileConcurrencyWrapper<ReadableFile> {
+ public:
+  ~ReadableFile() override;
+
+  /// \brief Open a local file for reading
+  /// \param[in] path with UTF8 encoding
+  /// \param[in] pool a MemoryPool for memory allocations
+  /// \return ReadableFile instance
+  static Result<std::shared_ptr<ReadableFile>> Open(
+      const std::string& path, MemoryPool* pool = default_memory_pool());
+
+  /// \brief Open a local file for reading
+  /// \param[in] fd file descriptor
+  /// \param[in] pool a MemoryPool for memory allocations
+  /// \return ReadableFile instance
+  ///
+  /// The file descriptor becomes owned by the ReadableFile, and will be closed
+  /// on Close() or destruction.
+  static Result<std::shared_ptr<ReadableFile>> Open(
+      int fd, MemoryPool* pool = default_memory_pool());
+
+  bool closed() const override;
+
+  int file_descriptor() const;
+
+  Status WillNeed(const std::vector<ReadRange>& ranges) override;
+
+ private:
+  friend RandomAccessFileConcurrencyWrapper<ReadableFile>;
+
+  explicit ReadableFile(MemoryPool* pool);
+
+  Status DoClose();
+  Result<int64_t> DoTell() const;
+  Result<int64_t> DoRead(int64_t nbytes, void* buffer);
+  Result<std::shared_ptr<Buffer>> DoRead(int64_t nbytes);
+
+  /// \brief Thread-safe implementation of ReadAt
+  Result<int64_t> DoReadAt(int64_t position, int64_t nbytes, void* out);
+
+  /// \brief Thread-safe implementation of ReadAt
+  Result<std::shared_ptr<Buffer>> DoReadAt(int64_t position, int64_t nbytes);
+
+  Result<int64_t> DoGetSize();
+  Status DoSeek(int64_t position);
+
+  class ARROW_NO_EXPORT ReadableFileImpl;
+  std::unique_ptr<ReadableFileImpl> impl_;
+};
+
+/// \brief A file interface that uses memory-mapped files for memory interactions
+///
+/// This implementation supports zero-copy reads. The same class is used
+/// for both reading and writing.
+///
+/// If opening a file in a writable mode, it is not truncated first as with
+/// FileOutputStream.
+class ARROW_EXPORT MemoryMappedFile : public ReadWriteFileInterface {
+ public:
+  ~MemoryMappedFile() override;
+
+  /// Create new file with indicated size, return in read/write mode
+  static Result<std::shared_ptr<MemoryMappedFile>> Create(const std::string& path,
+                                                          int64_t size);
+
+  // mmap() with whole file
+  static Result<std::shared_ptr<MemoryMappedFile>> Open(const std::string& path,
+                                                        FileMode::type mode);
+
+  // mmap() with a region of file, the offset must be a multiple of the page size
+  static Result<std::shared_ptr<MemoryMappedFile>> Open(const std::string& path,
+                                                        FileMode::type mode,
+                                                        const int64_t offset,
+                                                        const int64_t length);
+
+  Status Close() override;
+
+  bool closed() const override;
+
+  Result<int64_t> Tell() const override;
+
+  Status Seek(int64_t position) override;
+
+  // Required by RandomAccessFile, copies memory into out. Not thread-safe
+  Result<int64_t> Read(int64_t nbytes, void* out) override;
+
+  // Zero copy read, moves position pointer. Not thread-safe
+  Result<std::shared_ptr<Buffer>> Read(int64_t nbytes) override;
+
+  // Zero-copy read, leaves position unchanged. Acquires a reader lock
+  // for the duration of slice creation (typically very short). Is thread-safe.
+  Result<std::shared_ptr<Buffer>> ReadAt(int64_t position, int64_t nbytes) override;
+
+  // Raw copy of the memory at specified position. Thread-safe, but
+  // locks out other readers for the duration of memcpy. Prefer the
+  // zero copy method
+  Result<int64_t> ReadAt(int64_t position, int64_t nbytes, void* out) override;
+
+  // Synchronous ReadAsync override
+  Future<std::shared_ptr<Buffer>> ReadAsync(const IOContext&, int64_t position,
+                                            int64_t nbytes) override;
+
+  Status WillNeed(const std::vector<ReadRange>& ranges) override;
+
+  bool supports_zero_copy() const override;
+
+  /// Write data at the current position in the file. Thread-safe
+  Status Write(const void* data, int64_t nbytes) override;
+  /// \cond FALSE
+  using Writable::Write;
+  /// \endcond
+
+  /// Set the size of the map to new_size.
+  Status Resize(int64_t new_size);
+
+  /// Write data at a particular position in the file. Thread-safe
+  Status WriteAt(int64_t position, const void* data, int64_t nbytes) override;
+
+  Result<int64_t> GetSize() override;
+
+  int file_descriptor() const;
+
+ private:
+  MemoryMappedFile();
+
+  Status WriteInternal(const void* data, int64_t nbytes);
+
+  class ARROW_NO_EXPORT MemoryMap;
+  std::shared_ptr<MemoryMap> memory_map_;
+};
+
+}  // namespace io
+}  // namespace arrow