|
111
|
1 ------------------------------------------------------------------------------
|
|
|
2 -- --
|
|
|
3 -- GNAT RUN-TIME COMPONENTS --
|
|
|
4 -- --
|
|
|
5 -- S Y S T E M . M M A P --
|
|
|
6 -- --
|
|
|
7 -- S p e c --
|
|
|
8 -- --
|
|
131
|
9 -- Copyright (C) 2007-2018, AdaCore --
|
|
111
|
10 -- --
|
|
|
11 -- This library is free software; you can redistribute it and/or modify it --
|
|
|
12 -- under terms of the GNU General Public License as published by the Free --
|
|
|
13 -- Software Foundation; either version 3, or (at your option) any later --
|
|
|
14 -- version. This library is distributed in the hope that it will be useful, --
|
|
|
15 -- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHAN- --
|
|
|
16 -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. --
|
|
|
17 -- --
|
|
|
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
|
|
|
19 -- additional permissions described in the GCC Runtime Library Exception, --
|
|
|
20 -- version 3.1, as published by the Free Software Foundation. --
|
|
|
21 -- --
|
|
|
22 -- You should have received a copy of the GNU General Public License and --
|
|
|
23 -- a copy of the GCC Runtime Library Exception along with this program; --
|
|
|
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
|
|
|
25 -- <http://www.gnu.org/licenses/>. --
|
|
|
26 -- --
|
|
|
27 -- GNAT was originally developed by the GNAT team at New York University. --
|
|
|
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
|
|
|
29 -- --
|
|
|
30 ------------------------------------------------------------------------------
|
|
|
31
|
|
|
32 -- This package provides memory mapping of files. Depending on your operating
|
|
|
33 -- system, this might provide a more efficient method for accessing the
|
|
|
34 -- contents of files.
|
|
|
35 -- A description of memory-mapping is available on the sqlite page, at:
|
|
|
36 -- http://www.sqlite.org/mmap.html
|
|
|
37 --
|
|
|
38 -- The traditional method for reading a file is to allocate a buffer in the
|
|
|
39 -- application address space, then open the file and copy its contents. When
|
|
|
40 -- memory mapping is available though, the application asks the operating
|
|
|
41 -- system to return a pointer to the requested page, if possible. If the
|
|
|
42 -- requested page has been or can be mapped into the application address
|
|
|
43 -- space, the system returns a pointer to that page for the application to
|
|
|
44 -- use without having to copy anything. Skipping the copy step is what makes
|
|
|
45 -- memory mapped I/O faster.
|
|
|
46 --
|
|
|
47 -- When memory mapping is not available, this package automatically falls
|
|
|
48 -- back to the traditional copy method.
|
|
|
49 --
|
|
|
50 -- Example of use for this package, when reading a file that can be fully
|
|
|
51 -- mapped
|
|
|
52 --
|
|
|
53 -- declare
|
|
|
54 -- File : Mapped_File;
|
|
|
55 -- Str : Str_Access;
|
|
|
56 -- begin
|
|
|
57 -- File := Open_Read ("/tmp/file_on_disk");
|
|
|
58 -- Read (File); -- read the whole file
|
|
|
59 -- Str := Data (File);
|
|
|
60 -- for S in 1 .. Last (File) loop
|
|
|
61 -- Put (Str (S));
|
|
|
62 -- end loop;
|
|
|
63 -- Close (File);
|
|
|
64 -- end;
|
|
|
65 --
|
|
|
66 -- When the file is big, or you only want to access part of it at a given
|
|
|
67 -- time, you can use the following type of code.
|
|
|
68
|
|
|
69 -- declare
|
|
|
70 -- File : Mapped_File;
|
|
|
71 -- Str : Str_Access;
|
|
|
72 -- Offs : File_Size := 0;
|
|
|
73 -- Page : constant Integer := Get_Page_Size;
|
|
|
74 -- begin
|
|
|
75 -- File := Open_Read ("/tmp/file_on_disk");
|
|
|
76 -- while Offs < Length (File) loop
|
|
|
77 -- Read (File, Offs, Length => Long_Integer (Page) * 4);
|
|
|
78 -- Str := Data (File);
|
|
|
79 --
|
|
|
80 -- -- Print characters for this chunk:
|
|
|
81 -- for S in Integer (Offs - Offset (File)) + 1 .. Last (File) loop
|
|
|
82 -- Put (Str (S));
|
|
|
83 -- end loop;
|
|
|
84 --
|
|
|
85 -- -- Since we are reading multiples of Get_Page_Size, we can simplify
|
|
|
86 -- -- with
|
|
|
87 -- -- for S in 1 .. Last (File) loop ...
|
|
|
88 --
|
|
|
89 -- Offs := Offs + Long_Integer (Last (File));
|
|
|
90 -- end loop;
|
|
|
91
|
|
|
92 with Interfaces.C;
|
|
|
93
|
|
|
94 with System.Strings;
|
|
|
95
|
|
|
96 package System.Mmap is
|
|
|
97
|
|
|
98 type Mapped_File is private;
|
|
|
99 -- File to be mapped in memory.
|
|
|
100
|
|
|
101 -- This package will use the fastest possible algorithm to load the
|
|
|
102 -- file in memory. On systems that support it, the file is not really
|
|
|
103 -- loaded in memory. Instead, a call to the mmap() system call (or
|
|
|
104 -- CreateFileMapping()) will keep the file on disk, but make it
|
|
|
105 -- accessible as if it was in memory.
|
|
|
106
|
|
|
107 -- When the system does not support it, the file is actually loaded in
|
|
|
108 -- memory through calls to read(), and written back with write() when you
|
|
|
109 -- close it. This is of course much slower.
|
|
|
110
|
|
|
111 -- Legacy: each mapped file has a "default" mapped region in it.
|
|
|
112
|
|
|
113 type Mapped_Region is private;
|
|
|
114 -- A representation of part of a file in memory. Actual reading/writing
|
|
|
115 -- is done through a mapped region. After being returned by Read, a mapped
|
|
|
116 -- region must be free'd when done. If the original Mapped_File was open
|
|
|
117 -- for reading, it can be closed before the mapped region is free'd.
|
|
|
118
|
|
|
119 Invalid_Mapped_File : constant Mapped_File;
|
|
|
120 Invalid_Mapped_Region : constant Mapped_Region;
|
|
|
121
|
|
|
122 type Unconstrained_String is new String (Positive);
|
|
|
123 type Str_Access is access all Unconstrained_String;
|
|
|
124 pragma No_Strict_Aliasing (Str_Access);
|
|
|
125
|
|
|
126 type File_Size is new Interfaces.C.size_t;
|
|
|
127
|
|
|
128 function To_Str_Access
|
|
|
129 (Str : System.Strings.String_Access) return Str_Access;
|
|
|
130 -- Convert Str. The returned value points to the same memory block, but no
|
|
|
131 -- longer includes the bounds, which you need to manage yourself
|
|
|
132
|
|
|
133 function Open_Read
|
|
|
134 (Filename : String;
|
|
|
135 Use_Mmap_If_Available : Boolean := True) return Mapped_File;
|
|
|
136 -- Open a file for reading. The same file can be shared by multiple
|
|
|
137 -- processes, that will see each others's changes as they occur.
|
|
|
138 -- Any attempt to write the data might result in a segmentation fault,
|
|
|
139 -- depending on how the file is open.
|
|
|
140 -- Name_Error is raised if the file does not exist.
|
|
|
141 -- Filename should be compatible with the filesystem.
|
|
|
142
|
|
|
143 function Open_Read_No_Exception
|
|
|
144 (Filename : String;
|
|
|
145 Use_Mmap_If_Available : Boolean := True) return Mapped_File;
|
|
|
146 -- Like Open_Read but return Invalid_Mapped_File in case of error
|
|
|
147
|
|
|
148 function Open_Write
|
|
|
149 (Filename : String;
|
|
|
150 Use_Mmap_If_Available : Boolean := True) return Mapped_File;
|
|
|
151 -- Open a file for writing.
|
|
|
152 -- You cannot change the length of the file.
|
|
|
153 -- Name_Error is raised if the file does not exist
|
|
|
154 -- Filename should be compatible with the filesystem.
|
|
|
155
|
|
|
156 procedure Close (File : in out Mapped_File);
|
|
|
157 -- Close the file, and unmap the memory that is used for the region
|
|
|
158 -- contained in File. If the system does not support the unmmap() system
|
|
|
159 -- call or equivalent, or these were not available for the file itself,
|
|
|
160 -- then the file is written back to the disk if it was opened for writing.
|
|
|
161
|
|
|
162 procedure Free (Region : in out Mapped_Region);
|
|
|
163 -- Unmap the memory that is used for this region and deallocate the region
|
|
|
164
|
|
|
165 procedure Read
|
|
|
166 (File : Mapped_File;
|
|
|
167 Region : in out Mapped_Region;
|
|
|
168 Offset : File_Size := 0;
|
|
|
169 Length : File_Size := 0;
|
|
|
170 Mutable : Boolean := False);
|
|
|
171 -- Read a specific part of File and set Region to the corresponding mapped
|
|
|
172 -- region, or re-use it if possible.
|
|
|
173 -- Offset is the number of bytes since the beginning of the file at which
|
|
|
174 -- we should start reading. Length is the number of bytes that should be
|
|
|
175 -- read. If set to 0, as much of the file as possible is read (presumably
|
|
|
176 -- the whole file unless you are reading a _huge_ file).
|
|
|
177 -- Note that no (un)mapping is is done if that part of the file is already
|
|
|
178 -- available through Region.
|
|
|
179 -- If the file was opened for writing, any modification you do to the
|
|
|
180 -- data stored in File will be stored on disk (either immediately when the
|
|
|
181 -- file is opened through a mmap() system call, or when the file is closed
|
|
|
182 -- otherwise).
|
|
|
183 -- Mutable is processed only for reading files. If set to True, the
|
|
|
184 -- data can be modified, even through it will not be carried through the
|
|
|
185 -- underlying file, nor it is guaranteed to be carried through remapping.
|
|
|
186 -- This function takes care of page size alignment issues. The accessors
|
|
|
187 -- below only expose the region that has been requested by this call, even
|
|
|
188 -- if more bytes were actually mapped by this function.
|
|
|
189 -- TODO??? Enable to have a private copy for readable files
|
|
|
190
|
|
|
191 function Read
|
|
|
192 (File : Mapped_File;
|
|
|
193 Offset : File_Size := 0;
|
|
|
194 Length : File_Size := 0;
|
|
|
195 Mutable : Boolean := False) return Mapped_Region;
|
|
|
196 -- Likewise, return a new mapped region
|
|
|
197
|
|
|
198 procedure Read
|
|
|
199 (File : Mapped_File;
|
|
|
200 Offset : File_Size := 0;
|
|
|
201 Length : File_Size := 0;
|
|
|
202 Mutable : Boolean := False);
|
|
|
203 -- Likewise, use the legacy "default" region in File
|
|
|
204
|
|
|
205 function Length (File : Mapped_File) return File_Size;
|
|
|
206 -- Size of the file on the disk
|
|
|
207
|
|
|
208 function Offset (Region : Mapped_Region) return File_Size;
|
|
|
209 -- Return the offset, in the physical file on disk, corresponding to the
|
|
|
210 -- requested mapped region. The first byte in the file has offest 0.
|
|
|
211
|
|
|
212 function Offset (File : Mapped_File) return File_Size;
|
|
|
213 -- Likewise for the region contained in File
|
|
|
214
|
|
|
215 function Last (Region : Mapped_Region) return Integer;
|
|
|
216 -- Return the number of requested bytes mapped in this region. It is
|
|
|
217 -- erroneous to access Data for indices outside 1 .. Last (Region).
|
|
|
218 -- Such accesses may cause Storage_Error to be raised.
|
|
|
219
|
|
|
220 function Last (File : Mapped_File) return Integer;
|
|
|
221 -- Return the number of requested bytes mapped in the region contained in
|
|
|
222 -- File. It is erroneous to access Data for indices outside of 1 .. Last
|
|
|
223 -- (File); such accesses may cause Storage_Error to be raised.
|
|
|
224
|
|
|
225 function Data (Region : Mapped_Region) return Str_Access;
|
|
|
226 pragma Inline (Data);
|
|
|
227 -- The data mapped in Region as requested. The result is an unconstrained
|
|
|
228 -- string, so you cannot use the usual 'First and 'Last attributes.
|
|
|
229 -- Instead, these are respectively 1 and Size.
|
|
|
230
|
|
|
231 function Data (File : Mapped_File) return Str_Access;
|
|
|
232 pragma Inline (Data);
|
|
|
233 -- Likewise for the region contained in File
|
|
|
234
|
|
|
235 function Is_Mutable (Region : Mapped_Region) return Boolean;
|
|
|
236 -- Return whether it is safe to change bytes in Data (Region). This is true
|
|
|
237 -- for regions from writeable files, for regions mapped with the "Mutable"
|
|
|
238 -- flag set, and for regions that are copied in a buffer. Note that it is
|
|
|
239 -- not specified whether empty regions are mutable or not, since there is
|
|
|
240 -- no byte no modify.
|
|
|
241
|
|
|
242 function Is_Mmapped (File : Mapped_File) return Boolean;
|
|
|
243 -- Whether regions for this file are opened through an mmap() system call
|
|
|
244 -- or equivalent. This is in general irrelevant to your application, unless
|
|
|
245 -- the file can be accessed by multiple concurrent processes or tasks. In
|
|
|
246 -- such a case, and if the file is indeed mmap-ed, then the various parts
|
|
|
247 -- of the file can be written simulatenously, and thus you cannot ensure
|
|
|
248 -- the integrity of the file. If the file is not mmapped, the latest
|
|
|
249 -- process to Close it overwrite what other processes have done.
|
|
|
250
|
|
|
251 function Get_Page_Size return Integer;
|
|
|
252 -- Returns the number of bytes in a page. Once a file is mapped from the
|
|
|
253 -- disk, its offset and Length should be multiples of this page size (which
|
|
|
254 -- is ensured by this package in any case). Knowing this page size allows
|
|
|
255 -- you to map as much memory as possible at once, thus potentially reducing
|
|
|
256 -- the number of system calls to read the file by chunks.
|
|
|
257
|
|
|
258 function Read_Whole_File
|
|
|
259 (Filename : String;
|
|
|
260 Empty_If_Not_Found : Boolean := False)
|
|
|
261 return System.Strings.String_Access;
|
|
|
262 -- Returns the whole contents of the file.
|
|
|
263 -- The returned string must be freed by the user.
|
|
|
264 -- This is a convenience function, which is of course slower than the ones
|
|
|
265 -- above since we also need to allocate some memory, actually read the file
|
|
|
266 -- and copy the bytes.
|
|
|
267 -- If the file does not exist, null is returned. However, if
|
|
|
268 -- Empty_If_Not_Found is True, then the empty string is returned instead.
|
|
|
269 -- Filename should be compatible with the filesystem.
|
|
|
270
|
|
|
271 private
|
|
|
272 pragma Inline (Data, Length, Last, Offset, Is_Mmapped, To_Str_Access);
|
|
|
273
|
|
|
274 type Mapped_File_Record;
|
|
|
275 type Mapped_File is access Mapped_File_Record;
|
|
|
276
|
|
|
277 type Mapped_Region_Record;
|
|
|
278 type Mapped_Region is access Mapped_Region_Record;
|
|
|
279
|
|
|
280 Invalid_Mapped_File : constant Mapped_File := null;
|
|
|
281 Invalid_Mapped_Region : constant Mapped_Region := null;
|
|
|
282
|
|
|
283 end System.Mmap;
|
