1 //===-- runtime/buffer.h ----------------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 // External file buffering
10 
11 #ifndef FORTRAN_RUNTIME_BUFFER_H_
12 #define FORTRAN_RUNTIME_BUFFER_H_
13 
14 #include "io-error.h"
15 #include "memory.h"
16 #include <algorithm>
17 #include <cinttypes>
18 #include <cstring>
19 
20 namespace Fortran::runtime::io {
21 
22 void LeftShiftBufferCircularly(char *, std::size_t bytes, std::size_t shift);
23 
24 // Maintains a view of a contiguous region of a file in a memory buffer.
25 // The valid data in the buffer may be circular, but any active frame
26 // will also be contiguous in memory.  The requirement stems from the need to
27 // preserve read data that may be reused by means of Tn/TLn edit descriptors
28 // without needing to position the file (which may not always be possible,
29 // e.g. a socket) and a general desire to reduce system call counts.
30 //
31 // Possible scenario with a tiny 32-byte buffer after a ReadFrame or
32 // WriteFrame with a file offset of 103 to access "DEF":
33 //
34 //    fileOffset_ 100 --+  +-+ frame of interest (103:105)
35 //   file:  ............ABCDEFGHIJKLMNOPQRSTUVWXYZ....
36 // buffer: [NOPQRSTUVWXYZ......ABCDEFGHIJKLM]   (size_ == 32)
37 //                             |  +-- frame_ == 3
38 //                             +----- start_ == 19, length_ == 26
39 //
40 // The buffer holds length_ == 26 bytes from file offsets 100:125.
41 // Those 26 bytes "wrap around" the end of the circular buffer,
42 // so file offsets 100:112 map to buffer offsets 19:31 ("A..M") and
43 //    file offsets 113:125 map to buffer offsets  0:12 ("N..Z")
44 // The 3-byte frame of file offsets 103:105 is contiguous in the buffer
45 // at buffer offset (start_ + frame_) == 22 ("DEF").
46 
47 template <typename STORE, std::size_t minBuffer = 65536> class FileFrame {
48 public:
49   using FileOffset = std::int64_t;
50 
51   ~FileFrame() { FreeMemoryAndNullify(buffer_); }
52 
53   // The valid data in the buffer begins at buffer_[start_] and proceeds
54   // with possible wrap-around for length_ bytes.  The current frame
55   // is offset by frame_ bytes into that region and is guaranteed to
56   // be contiguous for at least as many bytes as were requested.
57 
58   FileOffset FrameAt() const { return fileOffset_ + frame_; }
59   char *Frame() const { return buffer_ + start_ + frame_; }
60   std::size_t FrameLength() const {
61     return std::min<std::size_t>(length_ - frame_, size_ - (start_ + frame_));
62   }
63   std::size_t BytesBufferedBeforeFrame() const { return frame_ - start_; }
64 
65   // Returns a short frame at a non-fatal EOF.  Can return a long frame as well.
66   std::size_t ReadFrame(
67       FileOffset at, std::size_t bytes, IoErrorHandler &handler) {
68     Flush(handler);
69     Reallocate(bytes, handler);
70     std::int64_t newFrame{at - fileOffset_};
71     if (newFrame < 0 || newFrame > length_) {
72       Reset(at);
73     } else {
74       frame_ = newFrame;
75     }
76     RUNTIME_CHECK(handler, at == fileOffset_ + frame_);
77     if (static_cast<std::int64_t>(start_ + frame_ + bytes) > size_) {
78       DiscardLeadingBytes(frame_, handler);
79       MakeDataContiguous(handler, bytes);
80       RUNTIME_CHECK(handler, at == fileOffset_ + frame_);
81     }
82     while (FrameLength() < bytes) {
83       auto next{start_ + length_};
84       RUNTIME_CHECK(handler, next < size_);
85       auto minBytes{bytes - FrameLength()};
86       auto maxBytes{size_ - next};
87       auto got{Store().Read(
88           fileOffset_ + length_, buffer_ + next, minBytes, maxBytes, handler)};
89       length_ += got;
90       RUNTIME_CHECK(handler, length_ <= size_);
91       if (got < minBytes) {
92         break; // error or EOF & program can handle it
93       }
94     }
95     return FrameLength();
96   }
97 
98   void WriteFrame(FileOffset at, std::size_t bytes, IoErrorHandler &handler) {
99     Reallocate(bytes, handler);
100     std::int64_t newFrame{at - fileOffset_};
101     if (!dirty_ || newFrame < 0 || newFrame > length_) {
102       Flush(handler);
103       Reset(at);
104     } else if (start_ + newFrame + static_cast<std::int64_t>(bytes) > size_) {
105       // Flush leading data before "at", retain from "at" onward
106       Flush(handler, length_ - newFrame);
107       MakeDataContiguous(handler, bytes);
108     } else {
109       frame_ = newFrame;
110     }
111     RUNTIME_CHECK(handler, at == fileOffset_ + frame_);
112     dirty_ = true;
113     length_ = std::max<std::int64_t>(length_, frame_ + bytes);
114   }
115 
116   void Flush(IoErrorHandler &handler, std::int64_t keep = 0) {
117     if (dirty_) {
118       while (length_ > keep) {
119         std::size_t chunk{
120             std::min<std::size_t>(length_ - keep, size_ - start_)};
121         std::size_t put{
122             Store().Write(fileOffset_, buffer_ + start_, chunk, handler)};
123         DiscardLeadingBytes(put, handler);
124         if (put < chunk) {
125           break;
126         }
127       }
128       if (length_ == 0) {
129         Reset(fileOffset_);
130       }
131     }
132   }
133 
134 private:
135   STORE &Store() { return static_cast<STORE &>(*this); }
136 
137   void Reallocate(std::int64_t bytes, const Terminator &terminator) {
138     if (bytes > size_) {
139       char *old{buffer_};
140       auto oldSize{size_};
141       size_ = std::max<std::int64_t>(bytes, minBuffer);
142       buffer_ =
143           reinterpret_cast<char *>(AllocateMemoryOrCrash(terminator, size_));
144       auto chunk{std::min<std::int64_t>(length_, oldSize - start_)};
145       std::memcpy(buffer_, old + start_, chunk);
146       start_ = 0;
147       std::memcpy(buffer_ + chunk, old, length_ - chunk);
148       FreeMemory(old);
149     }
150   }
151 
152   void Reset(FileOffset at) {
153     start_ = length_ = frame_ = 0;
154     fileOffset_ = at;
155     dirty_ = false;
156   }
157 
158   void DiscardLeadingBytes(std::int64_t n, const Terminator &terminator) {
159     RUNTIME_CHECK(terminator, length_ >= n);
160     length_ -= n;
161     if (length_ == 0) {
162       start_ = 0;
163     } else {
164       start_ += n;
165       if (start_ >= size_) {
166         start_ -= size_;
167       }
168     }
169     if (frame_ >= n) {
170       frame_ -= n;
171     } else {
172       frame_ = 0;
173     }
174     fileOffset_ += n;
175   }
176 
177   void MakeDataContiguous(IoErrorHandler &handler, std::size_t bytes) {
178     if (static_cast<std::int64_t>(start_ + bytes) > size_) {
179       // Frame would wrap around; shift current data (if any) to force
180       // contiguity.
181       RUNTIME_CHECK(handler, length_ < size_);
182       if (start_ + length_ <= size_) {
183         // [......abcde..] -> [abcde........]
184         std::memmove(buffer_, buffer_ + start_, length_);
185       } else {
186         // [cde........ab] -> [abcde........]
187         auto n{start_ + length_ - size_}; // 3 for cde
188         RUNTIME_CHECK(handler, length_ >= n);
189         std::memmove(buffer_ + n, buffer_ + start_, length_ - n); // cdeab
190         LeftShiftBufferCircularly(buffer_, length_, n); // abcde
191       }
192       start_ = 0;
193     }
194   }
195 
196   char *buffer_{nullptr};
197   std::int64_t size_{0}; // current allocated buffer size
198   FileOffset fileOffset_{0}; // file offset corresponding to buffer valid data
199   std::int64_t start_{0}; // buffer_[] offset of valid data
200   std::int64_t length_{0}; // valid data length (can wrap)
201   std::int64_t frame_{0}; // offset of current frame in valid data
202   bool dirty_{false};
203 };
204 } // namespace Fortran::runtime::io
205 #endif // FORTRAN_RUNTIME_BUFFER_H_
206