Skip to content

Commit 5894ba8

Browse files
xadupreCopilot
andauthored
Add portable random-access file reads to Env (#32503)
## Description Fixes #32500. Add `Env::OpenRandomAccessFile()` and an owned `RandomAccessFile` interface with `GetLength()` and synchronous, thread-safe positional `Read()` operations. All operations use the same open file identity rather than reopening its pathname for each range. - POSIX uses `pread`, retries interrupted operations, handles short reads, and rejects non-regular files without blocking on FIFOs. - Windows uses an overlapped disk handle and per-call event/OVERLAPPED state, handling pending operations and draining outstanding I/O before returning. Read sharing and delete sharing permit pathname replacement while retaining the original file identity; write sharing is denied. - Both implementations validate offsets and range overflow and preserve output ownership on failed opens. - Existing `ReadFileIntoBuffer` remains available and unchanged. The new Env virtual is appended, and its default implementation explicitly returns NOT_IMPLEMENTED so custom environments are not silently bypassed. This is not protection against in-place file modification under POSIX, or a snapshot across multiple files. Callers must retain the object for the entire sequence of reads that needs a stable identity and keep it alive until all readers finish. ## Scope This PR is based directly on main. It provides the platform abstraction requested during #32437; migration of that CUDA loader is not included. Loader lifecycle cleanup is tracked separately in #32502. ## Platform compatibility Android exposes fortified overloads of `open`, which prevented `TempFailureRetry` from deducing its callable type and caused all four failing Android CI jobs to stop at compilation. The call to `open` is now wrapped in a lambda, preserving the fortified call and EINTR retry behavior. After the compilation fixes, Android minimal-baseline CI measured 1,587,406 bytes of ELF sections. The active workflow budget is now 1,589,248 bytes (a 4 KiB increase), leaving 1,842 bytes of headroom while keeping the size check enabled. The concurrent-read tests use `std::thread` with scope-bound joins for Android and older libc++ implementations that lack `std::jthread`. On Windows, the atomic replacement test uses `FileRenameInfoEx` with POSIX replacement semantics because legacy filesystem rename rejects an open destination; the production write-sharing restriction is unchanged. ## Coverage Adds platform tests for concurrent reads, file size, invalid ranges, EOF after a partial read, empty files, failed-open output preservation, the default unsupported implementation, atomic pathname replacement, platform-specific truncation behavior, FIFO rejection, and sparse files beyond 4 GiB on 64-bit POSIX and Windows. Existing path-based reads and length queries are also exercised. ## Validation All 12 selected Linux CPU tests passed: ```text onnxruntime_test_all --gtest_filter="RandomAccessFileTest.*:PlatformEnvTest.*" ``` Windows code and Windows-specific test branches require Windows CI; no Windows compiler/runtime was available locally. The local CPU build has contrib ops disabled and encountered an existing unrelated unused-function warning in nhwc_transformer_test.cc. Only that translation unit was compiled with -Wno-error=unused-function; no unrelated source or global warning settings were changed. --------- Co-authored-by: Copilot <[email protected]>
1 parent a2ee3eb commit 5894ba8

6 files changed

Lines changed: 534 additions & 25 deletions

File tree

‎.github/workflows/android.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,8 @@ jobs:
7979
run: |
8080
set -e -x
8181
BINARY_SIZE_THRESHOLD_ARGS=""
82-
echo "Binary size threshold in bytes: 1585152"
83-
BINARY_SIZE_THRESHOLD_ARGS="--threshold_size_in_bytes 1585152"
82+
echo "Binary size threshold in bytes: 1589248"
83+
BINARY_SIZE_THRESHOLD_ARGS="--threshold_size_in_bytes 1589248"
8484
8585
# Ensure ANDROID_NDK_HOME is available and get its real path
8686
if [ -z "$ANDROID_NDK_HOME" ]; then

‎onnxruntime/core/platform/env.h‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,35 @@ std::ostream& operator<<(std::ostream& os, gsl::span<const LogicalProcessors>);
108108
/// <returns>errno and the error message string if errno indicates an error.</returns>
109109
std::pair<int, std::string> GetErrnoInfo();
110110

111+
/**
112+
* An owned open file supporting concurrent positional reads.
113+
*
114+
* Reads and length queries refer to the same file even if its pathname is replaced.
115+
* This is not a snapshot: callers must not modify the file in place while reading it.
116+
* Keep the object alive until all callers have finished. Its destruction closes the file.
117+
*/
118+
class RandomAccessFile {
119+
public:
120+
virtual ~RandomAccessFile() = default;
121+
122+
// Query the open file, leaving length unchanged on failure.
123+
virtual common::Status GetLength(size_t& length) const = 0;
124+
125+
/**
126+
* Fill buffer starting at offset without changing a shared file position.
127+
* Concurrent calls must use disjoint buffers. Returns only after all I/O has completed.
128+
* Negative offsets, unrepresentable ranges, and unexpected EOF are errors.
129+
* An empty buffer succeeds for any nonnegative offset. On failure, buffer may be partially written.
130+
*/
131+
virtual common::Status Read(FileOffsetType offset, gsl::span<char> buffer) const = 0;
132+
133+
protected:
134+
RandomAccessFile() = default;
135+
136+
private:
137+
ORT_DISALLOW_COPY_ASSIGNMENT_AND_MOVE(RandomAccessFile);
138+
};
139+
111140
/// \brief An interface used by the onnxruntime implementation to
112141
/// access operating system functionality like the filesystem etc.
113142
///
@@ -286,6 +315,17 @@ class Env {
286315
// Returns empty string if there is no such environment variable available
287316
virtual std::string GetEnvironmentVar(const std::string& var_name) const = 0;
288317

318+
/**
319+
* Open a regular file for positional reads. Leaves file unchanged on failure.
320+
* Retain the returned object across every read that must use the same file identity,
321+
* for example throughout loading a tensor or all tensors from one external-data file.
322+
* Custom environments can override this to supply their own file implementation.
323+
*/
324+
virtual common::Status OpenRandomAccessFile(const ORTCHAR_T* /*file_path*/,
325+
std::unique_ptr<RandomAccessFile>& /*file*/) const {
326+
return ORT_MAKE_STATUS(ONNXRUNTIME, NOT_IMPLEMENTED, "This environment does not support random-access files.");
327+
}
328+
289329
protected:
290330
Env();
291331

‎onnxruntime/core/platform/posix/env.cc‎

Lines changed: 86 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,72 @@ long int TempFailureRetry(TFunc retriable_operation, TFuncArgs&&... args) {
103103
return result;
104104
}
105105

106+
common::Status ReportSystemError(const char* operation_name, const std::string& path) {
107+
auto [err_no, err_msg] = GetErrnoInfo();
108+
std::ostringstream oss;
109+
oss << operation_name << " file \"" << path << "\" failed: " << err_msg;
110+
return common::Status(common::SYSTEM, err_no, oss.str());
111+
}
112+
113+
common::Status GetFileLength(int fd, size_t& file_size) {
114+
if (fd < 0) {
115+
return ORT_MAKE_STATUS(ONNXRUNTIME, INVALID_ARGUMENT, "Invalid fd was supplied: ", fd);
116+
}
117+
118+
struct stat buf;
119+
if (TempFailureRetry(fstat, fd, &buf) < 0) {
120+
return ReportSystemError("fstat", "");
121+
}
122+
if (buf.st_size < 0) {
123+
return ORT_MAKE_STATUS(SYSTEM, FAIL, "Received negative size from stat call");
124+
}
125+
if (static_cast<uintmax_t>(buf.st_size) > std::numeric_limits<size_t>::max()) {
126+
return ORT_MAKE_STATUS(SYSTEM, FAIL, "File is too large.");
127+
}
128+
129+
file_size = static_cast<size_t>(buf.st_size);
130+
return common::Status::OK();
131+
}
132+
133+
class PosixRandomAccessFile final : public RandomAccessFile {
134+
public:
135+
PosixRandomAccessFile(ScopedFileDescriptor descriptor, std::string path)
136+
: descriptor_(std::move(descriptor)), path_(std::move(path)) {}
137+
138+
common::Status GetLength(size_t& length) const override {
139+
return GetFileLength(descriptor_.Get(), length);
140+
}
141+
142+
common::Status Read(FileOffsetType offset, gsl::span<char> buffer) const override {
143+
if (offset < 0) {
144+
return ORT_MAKE_STATUS(ONNXRUNTIME, INVALID_ARGUMENT, "RandomAccessFile::Read: offset must be nonnegative.");
145+
}
146+
if (static_cast<uintmax_t>(buffer.size()) >
147+
static_cast<uintmax_t>(std::numeric_limits<FileOffsetType>::max() - offset)) {
148+
return ORT_MAKE_STATUS(ONNXRUNTIME, INVALID_ARGUMENT, "RandomAccessFile::Read: file range is not representable.");
149+
}
150+
151+
size_t total_bytes_read = 0;
152+
while (total_bytes_read < buffer.size()) {
153+
constexpr size_t kMaxBytesToRead = 1 << 30;
154+
const auto bytes_to_read = std::min(buffer.size() - total_bytes_read, kMaxBytesToRead);
155+
const auto bytes_read = TempFailureRetry(pread, descriptor_.Get(), buffer.data() + total_bytes_read,
156+
bytes_to_read, offset + static_cast<FileOffsetType>(total_bytes_read));
157+
if (bytes_read < 0) {
158+
return ReportSystemError("pread", path_);
159+
}
160+
ORT_RETURN_IF(bytes_read == 0, "RandomAccessFile::Read: unexpected end of file: ", path_);
161+
total_bytes_read += static_cast<size_t>(bytes_read);
162+
}
163+
return common::Status::OK();
164+
}
165+
166+
private:
167+
ORT_DISALLOW_COPY_ASSIGNMENT_AND_MOVE(PosixRandomAccessFile);
168+
ScopedFileDescriptor descriptor_;
169+
const std::string path_;
170+
};
171+
106172
// nftw() callback to remove a file
107173
int nftw_remove(
108174
const char* fpath, const struct stat* /*sb*/,
@@ -371,26 +437,30 @@ class PosixEnv : public Env {
371437
}
372438

373439
common::Status GetFileLength(int fd, /*out*/ size_t& file_size) const override {
374-
using namespace common;
375-
if (fd < 0) {
376-
return ORT_MAKE_STATUS(ONNXRUNTIME, INVALID_ARGUMENT, "Invalid fd was supplied: ", fd);
377-
}
440+
return onnxruntime::GetFileLength(fd, file_size);
441+
}
378442

379-
struct stat buf;
380-
int rc = fstat(fd, &buf);
381-
if (rc < 0) {
382-
return ReportSystemError("fstat", "");
443+
common::Status OpenRandomAccessFile(const ORTCHAR_T* file_path,
444+
std::unique_ptr<RandomAccessFile>& file) const override {
445+
if (file_path == nullptr) {
446+
return ORT_MAKE_STATUS(ONNXRUNTIME, INVALID_ARGUMENT, "file_path == nullptr");
383447
}
384-
385-
if (buf.st_size < 0) {
386-
return ORT_MAKE_STATUS(SYSTEM, FAIL, "Received negative size from stat call");
448+
// Nonblocking open lets us reject FIFOs without waiting for a writer.
449+
int flags = O_RDONLY | O_NONBLOCK;
450+
#ifdef O_CLOEXEC
451+
flags |= O_CLOEXEC;
452+
#endif
453+
// Android's fortified open is overloaded; resolve the call inside a lambda.
454+
ScopedFileDescriptor descriptor{static_cast<int>(TempFailureRetry([&] { return open(file_path, flags); }))};
455+
if (!descriptor.IsValid()) {
456+
return ReportSystemError("open", file_path);
387457
}
388-
389-
if (static_cast<unsigned long long>(buf.st_size) > std::numeric_limits<size_t>::max()) {
390-
return ORT_MAKE_STATUS(SYSTEM, FAIL, "File is too large.");
458+
struct stat info;
459+
if (TempFailureRetry(fstat, descriptor.Get(), &info) < 0) {
460+
return ReportSystemError("fstat", file_path);
391461
}
392-
393-
file_size = static_cast<size_t>(buf.st_size);
462+
ORT_RETURN_IF_NOT(S_ISREG(info.st_mode), "Random-access reads require a regular file: ", file_path);
463+
file = std::make_unique<PosixRandomAccessFile>(std::move(descriptor), file_path);
394464
return Status::OK();
395465
}
396466

@@ -486,13 +556,6 @@ class PosixEnv : public Env {
486556
return Status::OK();
487557
}
488558

489-
static common::Status ReportSystemError(const char* operation_name, const std::string& path) {
490-
auto [err_no, err_msg] = GetErrnoInfo();
491-
std::ostringstream oss;
492-
oss << operation_name << " file \"" << path << "\" failed: " << err_msg;
493-
return common::Status(common::SYSTEM, err_no, oss.str());
494-
}
495-
496559
bool FolderExists(const std::string& path) const override {
497560
struct stat sb;
498561
if (stat(path.c_str(), &sb)) {

‎onnxruntime/core/platform/windows/env.cc‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ limitations under the License.
2121
#include <iostream>
2222
#include <fstream>
2323
#include <filesystem>
24+
#include <limits>
2425
#include <optional>
2526
#include <string>
2627
#include <thread>
@@ -357,6 +358,122 @@ common::Status WindowsEnv::GetFileLength(int fd, /*out*/ size_t& file_size) cons
357358
return Status::OK();
358359
}
359360

361+
namespace {
362+
363+
class WindowsRandomAccessFile final : public RandomAccessFile {
364+
public:
365+
explicit WindowsRandomAccessFile(wil::unique_hfile file_handle) : file_handle_(std::move(file_handle)) {}
366+
ORT_DISALLOW_COPY_ASSIGNMENT_AND_MOVE(WindowsRandomAccessFile);
367+
368+
Status GetLength(size_t& length) const override {
369+
LARGE_INTEGER file_size{};
370+
if (!GetFileSizeEx(file_handle_.get(), &file_size)) {
371+
return FileError("GetFileSizeEx", GetLastError());
372+
}
373+
if (file_size.QuadPart < 0 ||
374+
static_cast<ULONGLONG>(file_size.QuadPart) > std::numeric_limits<size_t>::max()) {
375+
return ORT_MAKE_STATUS(ONNXRUNTIME, FAIL, "RandomAccessFile: invalid or unrepresentable file length");
376+
}
377+
length = static_cast<size_t>(file_size.QuadPart);
378+
return Status::OK();
379+
}
380+
381+
Status Read(FileOffsetType offset, gsl::span<char> buffer) const override {
382+
if (offset < 0) {
383+
return ORT_MAKE_STATUS(ONNXRUNTIME, INVALID_ARGUMENT, "RandomAccessFile: offset < 0");
384+
}
385+
if (buffer.size() > static_cast<uint64_t>(std::numeric_limits<FileOffsetType>::max() - offset)) {
386+
return ORT_MAKE_STATUS(ONNXRUNTIME, INVALID_ARGUMENT, "RandomAccessFile: offset + length overflows");
387+
}
388+
if (buffer.empty()) {
389+
return Status::OK();
390+
}
391+
392+
// Each caller owns its event and OVERLAPPED; neither the file cursor nor another caller's event is used.
393+
wil::unique_handle event{CreateEventExW(nullptr, nullptr, CREATE_EVENT_MANUAL_RESET, EVENT_ALL_ACCESS)};
394+
if (!event) {
395+
return FileError("CreateEventExW", GetLastError());
396+
}
397+
398+
size_t total_bytes_read = 0;
399+
while (total_bytes_read < buffer.size()) {
400+
OVERLAPPED overlapped{};
401+
const auto current_offset = static_cast<uint64_t>(offset) + total_bytes_read;
402+
overlapped.Offset = static_cast<DWORD>(current_offset & 0xFFFFFFFF);
403+
overlapped.OffsetHigh = static_cast<DWORD>(current_offset >> 32);
404+
overlapped.hEvent = event.get();
405+
constexpr size_t kMaxBytesToRead = 1 << 30;
406+
const DWORD bytes_to_read =
407+
static_cast<DWORD>(std::min(buffer.size() - total_bytes_read, kMaxBytesToRead));
408+
if (!ReadFile(file_handle_.get(), buffer.data() + total_bytes_read, bytes_to_read, nullptr, &overlapped)) {
409+
const auto error_code = GetLastError();
410+
if (error_code != ERROR_IO_PENDING) {
411+
return FileError("ReadFile", error_code);
412+
}
413+
}
414+
415+
DWORD bytes_read = 0;
416+
if (!GetOverlappedResult(file_handle_.get(), &overlapped, &bytes_read, TRUE)) {
417+
const auto error_code = GetLastError();
418+
// A failed wait must not let outstanding I/O outlive the buffer, OVERLAPPED, or event.
419+
if (!HasOverlappedIoCompleted(&overlapped)) {
420+
(void)CancelIoEx(file_handle_.get(), &overlapped);
421+
do {
422+
(void)GetOverlappedResult(file_handle_.get(), &overlapped, &bytes_read, TRUE);
423+
} while (!HasOverlappedIoCompleted(&overlapped));
424+
}
425+
return FileError("GetOverlappedResult", error_code);
426+
}
427+
if (bytes_read == 0) {
428+
return ORT_MAKE_STATUS(ONNXRUNTIME, FAIL, "RandomAccessFile: unexpected end of file");
429+
}
430+
total_bytes_read += bytes_read;
431+
}
432+
return Status::OK();
433+
}
434+
435+
private:
436+
static Status FileError(const char* operation, DWORD error_code) {
437+
return ORT_MAKE_STATUS(ONNXRUNTIME, FAIL, "RandomAccessFile: ", operation, " failed, errcode = ",
438+
error_code, " - ", std::system_category().message(error_code));
439+
}
440+
441+
wil::unique_hfile file_handle_;
442+
};
443+
444+
} // namespace
445+
446+
Status WindowsEnv::OpenRandomAccessFile(_In_z_ const ORTCHAR_T* file_path,
447+
std::unique_ptr<RandomAccessFile>& file) const {
448+
if (file_path == nullptr) {
449+
return ORT_MAKE_STATUS(ONNXRUNTIME, INVALID_ARGUMENT, "OpenRandomAccessFile: file_path == nullptr");
450+
}
451+
CREATEFILE2_EXTENDED_PARAMETERS parameters{};
452+
parameters.dwSize = sizeof(parameters);
453+
parameters.dwFileFlags = FILE_FLAG_OVERLAPPED;
454+
wil::unique_hfile file_handle{
455+
CreateFile2(file_path, GENERIC_READ, FILE_SHARE_READ | FILE_SHARE_DELETE, OPEN_EXISTING, &parameters)};
456+
if (file_handle.get() == INVALID_HANDLE_VALUE) {
457+
const auto error_code = GetLastError();
458+
return ORT_MAKE_STATUS(ONNXRUNTIME, FAIL, "open file ", ToUTF8String(Basename(file_path)),
459+
" fail, errcode = ", error_code, " - ", std::system_category().message(error_code));
460+
}
461+
if (GetFileType(file_handle.get()) != FILE_TYPE_DISK) {
462+
return ORT_MAKE_STATUS(ONNXRUNTIME, FAIL, "OpenRandomAccessFile: expected a disk file");
463+
}
464+
BY_HANDLE_FILE_INFORMATION information{};
465+
if (!GetFileInformationByHandle(file_handle.get(), &information)) {
466+
const auto error_code = GetLastError();
467+
return ORT_MAKE_STATUS(ONNXRUNTIME, FAIL, "GetFileInformationByHandle failed, errcode = ",
468+
error_code, " - ", std::system_category().message(error_code));
469+
}
470+
if ((information.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) != 0) {
471+
return ORT_MAKE_STATUS(ONNXRUNTIME, FAIL, "OpenRandomAccessFile: expected a regular file");
472+
}
473+
file = std::make_unique<WindowsRandomAccessFile>(std::move(file_handle));
474+
return Status::OK();
475+
}
476+
360477
Status WindowsEnv::ReadFileIntoBuffer(_In_z_ const ORTCHAR_T* const file_path, const FileOffsetType offset, const size_t length,
361478
const gsl::span<char> buffer) const {
362479
ORT_RETURN_IF_NOT(file_path, "file_path == nullptr");

‎onnxruntime/core/platform/windows/env.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ class WindowsEnv : public Env {
6161
PIDType GetSelfPid() const override;
6262
Status GetFileLength(_In_z_ const ORTCHAR_T* file_path, size_t& length) const override;
6363
common::Status GetFileLength(int fd, /*out*/ size_t& file_size) const override;
64+
Status OpenRandomAccessFile(_In_z_ const ORTCHAR_T* file_path,
65+
std::unique_ptr<RandomAccessFile>& file) const override;
6466
Status ReadFileIntoBuffer(_In_z_ const ORTCHAR_T* const file_path, const FileOffsetType offset, const size_t length,
6567
const gsl::span<char> buffer) const override;
6668
Status MapFileIntoMemory(_In_z_ const ORTCHAR_T* file_path,

0 commit comments

Comments
 (0)