Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 5ebfd36

Browse files
tim-onetim-one
committed
CVS patch #477161: New "access" keyword for mmap, from Jay T Miller.
This gives mmap() on Windows the ability to create read-only, write- through and copy-on-write mmaps. A new keyword argument is introduced because the mmap() signatures diverged between Windows and Unix, so while they (now) both support this functionality, there wasn't a way to spell it in a common way without introducing a new spelling gimmick. The old spellings are still accepted, so there isn't a backward- compatibility issue here.
1 parent afeb2a4 commit 5ebfd36

5 files changed

Lines changed: 412 additions & 145 deletions

File tree

‎Doc/lib/libmmap.tex‎

Lines changed: 100 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
\section{\module{mmap} ---
2-
Memory-mapped file support}
2+
Memory-mapped file support}
33

44
\declaremodule{builtin}{mmap}
55
\modulesynopsis{Interface to memory-mapped files for Unix and Windows.}
@@ -23,110 +23,148 @@ \section{\module{mmap} ---
2323
\function{os.open()} function, which returns a file descriptor
2424
directly (the file still needs to be closed when done).
2525

26-
\begin{funcdesc}{mmap}{fileno, length\optional{, tagname}}
27-
\strong{(Windows version)} Maps \var{length} bytes from the file
28-
specified by the file handle \var{fileno}, and returns a mmap object.
29-
If \var{length} is \code{0}, the maximum length of the map will be the
30-
current size of the file when \function{mmap()} is called.
31-
32-
\var{tagname}, if specified and not \code{None}, is a string giving a
33-
tag name for the mapping. Windows allows you to have many different
34-
mappings against the same file. If you specify the name of an
35-
existing tag, that tag is opened, otherwise a new tag of this name is
36-
created. If this parameter is omitted or \code{None}, the mapping is
37-
created without a name. Avoiding the use of the tag parameter will
38-
assist in keeping your code portable between \UNIX{} and Windows.
26+
\begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}}
27+
\strong{(Windows version)} Maps \var{length} bytes from the file
28+
specified by the file handle \var{fileno}, and returns a mmap
29+
object. If \var{length} is \code{0}, the maximum length of the map
30+
will be the current size of the file when \function{mmap()} is
31+
called.
32+
33+
\var{tagname}, if specified and not \code{None}, is a string giving
34+
a tag name for the mapping. Windows allows you to have many
35+
different mappings against the same file. If you specify the name
36+
of an existing tag, that tag is opened, otherwise a new tag of this
37+
name is created. If this parameter is omitted or \code{None}, the
38+
mapping is created without a name. Avoiding the use of the tag
39+
parameter will assist in keeping your code portable between \UNIX{}
40+
and Windows.
41+
42+
\var{access} may be specified as an optional keyword parameter.
43+
\var{access} accepts one of three values: \constant{ACCESS_READ},
44+
\constant{ACCESS_WRITE}, or \constant{ACCESS_COPY} to specify
45+
readonly, write-through or copy-on-write memory respectively.
46+
\var{access} can be used on both \UNIX{} and Windows. If
47+
\var{access} is not specified, Windows mmap returns a write-through
48+
mapping. The initial memory values for all three access types are
49+
taken from the specified file. Assignment to an
50+
\constant{ACCESS_READ} memory map raises a \exception{TypeError}
51+
exception. Assignment to an \constant{ACCESS_WRITE} memory map
52+
affects both memory and the underlying file. Assigment to an
53+
\constant{ACCESS_COPY} memory map affects memory but does not update
54+
the underlying file.
3955
\end{funcdesc}
4056

41-
\begin{funcdesc}{mmap}{fileno, length\optional{, flags\optional{, prot}}}
42-
\strong{(\UNIX{} version)} Maps \var{length} bytes from the file
43-
specified by the file descriptor \var{fileno}, and returns a mmap object.
44-
45-
\var{flags} specifies the nature of the mapping.
46-
\constant{MAP_PRIVATE} creates a private copy-on-write mapping, so
47-
changes to the contents of the mmap object will be private to this
48-
process, and \constant{MAP_SHARED} creates a mapping that's shared
49-
with all other processes mapping the same areas of the file.
50-
The default value is \constant{MAP_SHARED}.
51-
52-
\var{prot}, if specified, gives the desired memory protection; the two
53-
most useful values are \constant{PROT_READ} and \constant{PROT_WRITE},
54-
to specify that the pages may be read or written.
55-
\var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
57+
\begin{funcdesc}{mmap}{fileno, length\optional{, flags\optional{, prot\optional{, access}}}}
58+
\strong{(\UNIX{} version)} Maps \var{length} bytes from the file
59+
specified by the file descriptor \var{fileno}, and returns a mmap
60+
object.
61+
62+
\var{flags} specifies the nature of the mapping.
63+
\constant{MAP_PRIVATE} creates a private copy-on-write mapping, so
64+
changes to the contents of the mmap object will be private to this
65+
process, and \constant{MAP_SHARED} creates a mapping that's shared
66+
with all other processes mapping the same areas of the file. The
67+
default value is \constant{MAP_SHARED}.
68+
69+
\var{prot}, if specified, gives the desired memory protection; the
70+
two most useful values are \constant{PROT_READ} and
71+
\constant{PROT_WRITE}, to specify that the pages may be read or
72+
written. \var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
73+
74+
\var{access} may be specified in lieu of \var{flags} and \var{prot}
75+
as an optional keyword parameter. \var{access} accepts one of three
76+
values: \constant{ACCESS_READ}, \constant{ACCESS_WRITE}, or
77+
\constant{ACCESS_COPY} to specify readonly, write-through, or
78+
copy-on-write memory respectively. \var{access} can be used on both
79+
\UNIX{} and Windows. It is an error to specify both \var{flags},
80+
\var{prot} and \var{access}. The initial memory values for all
81+
three access types are taken from the specified file. Assignment to
82+
an \constant{ACCESS_READ} memory map raises a \exception{TypeError}
83+
exception. Assignment to an \constant{ACCESS_WRITE} memory map
84+
affects both memory and the underlying file. Assigment to an
85+
\constant{ACCESS_COPY} memory map affects memory but does not update
86+
the underlying file.
5687
\end{funcdesc}
5788

5889

5990
Memory-mapped file objects support the following methods:
6091

6192

6293
\begin{methoddesc}{close}{}
63-
Close the file. Subsequent calls to other methods of the object
64-
will result in an exception being raised.
94+
Close the file. Subsequent calls to other methods of the object
95+
will result in an exception being raised.
6596
\end{methoddesc}
6697

6798
\begin{methoddesc}{find}{string\optional{, start}}
68-
Returns the lowest index in the object where the substring
69-
\var{string} is found. Returns \code{-1} on failure. \var{start} is
70-
the index at which the search begins, and defaults to zero.
99+
Returns the lowest index in the object where the substring
100+
\var{string} is found. Returns \code{-1} on failure. \var{start}
101+
is the index at which the search begins, and defaults to zero.
71102
\end{methoddesc}
72103

73104
\begin{methoddesc}{flush}{\optional{offset, size}}
74-
Flushes changes made to the in-memory copy of a file back to disk.
75-
Without use of this call there is no guarantee that changes are
76-
written back before the object is destroyed. If \var{offset} and
77-
\var{size} are specified, only changes to the given range of bytes
78-
will be flushed to disk; otherwise, the whole extent of the mapping is
79-
flushed.
105+
Flushes changes made to the in-memory copy of a file back to disk.
106+
Without use of this call there is no guarantee that changes are
107+
written back before the object is destroyed. If \var{offset} and
108+
\var{size} are specified, only changes to the given range of bytes
109+
will be flushed to disk; otherwise, the whole extent of the mapping
110+
is flushed.
80111
\end{methoddesc}
81112

82113
\begin{methoddesc}{move}{\var{dest}, \var{src}, \var{count}}
83-
Copy the \var{count} bytes starting at offset \var{src}
84-
to the destination index \var{dest}.
114+
Copy the \var{count} bytes starting at offset \var{src} to the
115+
destination index \var{dest}. If the mmap was created with
116+
\constant{ACCESS_READ}, then calls to move will throw a
117+
\exception{TypeError} exception.
85118
\end{methoddesc}
86119

87120
\begin{methoddesc}{read}{\var{num}}
88-
Return a string containing up to \var{num} bytes starting from the
89-
current file position; the file position is updated to point after the
90-
bytes that were returned.
121+
Return a string containing up to \var{num} bytes starting from the
122+
current file position; the file position is updated to point after the
123+
bytes that were returned.
91124
\end{methoddesc}
92125

93126
\begin{methoddesc}{read_byte}{}
94-
Returns a string of length 1 containing the character at the current
95-
file position, and advances the file position by 1.
127+
Returns a string of length 1 containing the character at the current
128+
file position, and advances the file position by 1.
96129
\end{methoddesc}
97130

98131
\begin{methoddesc}{readline}{}
99-
Returns a single line, starting at the current file position and up to
100-
the next newline.
132+
Returns a single line, starting at the current file position and up to
133+
the next newline.
101134
\end{methoddesc}
102135

103136
\begin{methoddesc}{resize}{\var{newsize}}
137+
If the mmap was created with \constant{ACCESS_READ} or
138+
\constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception.
104139
\end{methoddesc}
105140

106141
\begin{methoddesc}{seek}{pos\optional{, whence}}
107-
Set the file's current position.
108-
\var{whence} argument is optional and defaults to \code{0} (absolute
109-
file positioning); other values are \code{1} (seek relative to the
110-
current position) and \code{2} (seek relative to the file's end).
142+
Set the file's current position. \var{whence} argument is optional
143+
and defaults to \code{0} (absolute file positioning); other values
144+
are \code{1} (seek relative to the current position) and \code{2}
145+
(seek relative to the file's end).
111146
\end{methoddesc}
112147

113148
\begin{methoddesc}{size}{}
114-
Return the length of the file, which can be larger than the size
115-
of the memory-mapped area.
149+
Return the length of the file, which can be larger than the size of
150+
the memory-mapped area.
116151
\end{methoddesc}
117152

118153
\begin{methoddesc}{tell}{}
119-
Returns the current position of the file pointer.
154+
Returns the current position of the file pointer.
120155
\end{methoddesc}
121156

122157
\begin{methoddesc}{write}{\var{string}}
123-
Write the bytes in \var{string} into memory at the current position of
124-
the file pointer; the file position is updated to point after the
125-
bytes that were written.
158+
Write the bytes in \var{string} into memory at the current position
159+
of the file pointer; the file position is updated to point after the
160+
bytes that were written. If the mmap was created with
161+
\constant{ACCESS_READ}, then writing to it will throw a
162+
\exception{TypeError} exception.
126163
\end{methoddesc}
127164

128165
\begin{methoddesc}{write_byte}{\var{byte}}
129-
Write the single-character string \var{byte} into memory at the
130-
current position of the file pointer; the file position is advanced by
131-
\code{1}.
166+
Write the single-character string \var{byte} into memory at the
167+
current position of the file pointer; the file position is advanced
168+
by \code{1}.If the mmap was created with \constant{ACCESS_READ},
169+
then writing to it will throw a \exception{TypeError} exception.
132170
\end{methoddesc}

‎Lib/test/output/test_mmap‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,17 @@ test_mmap
1717
Try to seek beyond end of mmap...
1818
Try to seek to negative position...
1919
Attempting resize()
20+
Creating 10 byte test data file.
21+
Opening mmap with access=ACCESS_READ
22+
Ensuring that readonly mmap can't be slice assigned.
23+
Ensuring that readonly mmap can't be item assigned.
24+
Ensuring that readonly mmap can't be write() to.
25+
Ensuring that readonly mmap can't be write_byte() to.
26+
Ensuring that readonly mmap can't be resized.
27+
Opening mmap with access=ACCESS_WRITE
28+
Modifying write-through memory map.
29+
Opening mmap with access=ACCESS_COPY
30+
Modifying copy-on-write memory map.
31+
Ensuring copy-on-write maps cannot be resized.
32+
Ensuring invalid access parameter raises exception.
2033
Test passed

0 commit comments

Comments
 (0)