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 files changed, 100 insertions, 62 deletions

diff --git a/Doc/lib/libmmap.tex b/Doc/lib/libmmap.tex
index 0bd0332..917635b 100644
--- a/Doc/lib/libmmap.tex
+++ b/Doc/lib/libmmap.tex
@@ -1,5 +1,5 @@
 \section{\module{mmap} ---
-	Memory-mapped file support}
+Memory-mapped file support}
 
 \declaremodule{builtin}{mmap}
 \modulesynopsis{Interface to memory-mapped files for Unix and Windows.}
@@ -23,36 +23,67 @@ If you wish to map an existing Python file object, use its
 \function{os.open()} function, which returns a file descriptor
 directly (the file still needs to be closed when done).
 
-\begin{funcdesc}{mmap}{fileno, length\optional{, tagname}}
-\strong{(Windows version)}  Maps \var{length} bytes from the file
-specified by the file handle \var{fileno}, and returns a mmap object.
-If \var{length} is \code{0}, the maximum length of the map will be the
-current size of the file when \function{mmap()} is called.
-
-\var{tagname}, if specified and not \code{None}, is a string giving a
-tag name for the mapping.  Windows allows you to have many different
-mappings against the same file.  If you specify the name of an
-existing tag, that tag is opened, otherwise a new tag of this name is
-created.  If this parameter is omitted or \code{None}, the mapping is
-created without a name.  Avoiding the use of the tag parameter will
-assist in keeping your code portable between \UNIX{} and Windows.
+\begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}}
+  \strong{(Windows version)} Maps \var{length} bytes from the file
+  specified by the file handle \var{fileno}, and returns a mmap
+  object.  If \var{length} is \code{0}, the maximum length of the map
+  will be the current size of the file when \function{mmap()} is
+  called.
+  
+  \var{tagname}, if specified and not \code{None}, is a string giving
+  a tag name for the mapping.  Windows allows you to have many
+  different mappings against the same file.  If you specify the name
+  of an existing tag, that tag is opened, otherwise a new tag of this
+  name is created.  If this parameter is omitted or \code{None}, the
+  mapping is created without a name.  Avoiding the use of the tag
+  parameter will assist in keeping your code portable between \UNIX{}
+  and Windows.
+  
+  \var{access} may be specified as an optional keyword parameter.
+  \var{access} accepts one of three values: \constant{ACCESS_READ},
+  \constant{ACCESS_WRITE}, or \constant{ACCESS_COPY} to specify
+  readonly, write-through or copy-on-write memory respectively.
+  \var{access} can be used on both \UNIX{} and Windows.  If
+  \var{access} is not specified, Windows mmap returns a write-through
+  mapping.  The initial memory values for all three access types are
+  taken from the specified file.  Assignment to an
+  \constant{ACCESS_READ} memory map raises a \exception{TypeError}
+  exception.  Assignment to an \constant{ACCESS_WRITE} memory map
+  affects both memory and the underlying file.  Assigment to an
+  \constant{ACCESS_COPY} memory map affects memory but does not update
+  the underlying file.
 \end{funcdesc}
 
-\begin{funcdesc}{mmap}{fileno, length\optional{, flags\optional{, prot}}}
-\strong{(\UNIX{} version)}  Maps \var{length} bytes from the file
-specified by the file descriptor \var{fileno}, and returns a mmap object.
-
-\var{flags} specifies the nature of the mapping.  
-\constant{MAP_PRIVATE} creates a private copy-on-write mapping, so
-changes to the contents of the mmap object will be private to this
-process, and \constant{MAP_SHARED} creates a mapping that's shared
-with all other processes mapping the same areas of the file.
-The default value is \constant{MAP_SHARED}.
-
-\var{prot}, if specified, gives the desired memory protection; the two 
-most useful values are \constant{PROT_READ} and \constant{PROT_WRITE},
-to specify that the pages may be read or written.
-\var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
+\begin{funcdesc}{mmap}{fileno, length\optional{, flags\optional{, prot\optional{, access}}}}
+  \strong{(\UNIX{} version)} Maps \var{length} bytes from the file
+  specified by the file descriptor \var{fileno}, and returns a mmap
+  object.
+  
+  \var{flags} specifies the nature of the mapping.
+  \constant{MAP_PRIVATE} creates a private copy-on-write mapping, so
+  changes to the contents of the mmap object will be private to this
+  process, and \constant{MAP_SHARED} creates a mapping that's shared
+  with all other processes mapping the same areas of the file.  The
+  default value is \constant{MAP_SHARED}.
+  
+  \var{prot}, if specified, gives the desired memory protection; the
+  two most useful values are \constant{PROT_READ} and
+  \constant{PROT_WRITE}, to specify that the pages may be read or
+  written.  \var{prot} defaults to \constant{PROT_READ | PROT_WRITE}.
+  
+  \var{access} may be specified in lieu of \var{flags} and \var{prot}
+  as an optional keyword parameter.  \var{access} accepts one of three
+  values: \constant{ACCESS_READ}, \constant{ACCESS_WRITE}, or
+  \constant{ACCESS_COPY} to specify readonly, write-through, or
+  copy-on-write memory respectively.  \var{access} can be used on both
+  \UNIX{} and Windows.  It is an error to specify both \var{flags},
+  \var{prot} and \var{access}.  The initial memory values for all
+  three access types are taken from the specified file.  Assignment to
+  an \constant{ACCESS_READ} memory map raises a \exception{TypeError}
+  exception.  Assignment to an \constant{ACCESS_WRITE} memory map
+  affects both memory and the underlying file.  Assigment to an
+  \constant{ACCESS_COPY} memory map affects memory but does not update
+  the underlying file.
 \end{funcdesc}
 
 
@@ -60,73 +91,80 @@ Memory-mapped file objects support the following methods:
 
 
 \begin{methoddesc}{close}{}
-Close the file.  Subsequent calls to other methods of the object
-will result in an exception being raised.
+  Close the file.  Subsequent calls to other methods of the object
+  will result in an exception being raised.
 \end{methoddesc}
 
 \begin{methoddesc}{find}{string\optional{, start}}
-Returns the lowest index in the object where the substring
-\var{string} is found.  Returns \code{-1} on failure.  \var{start} is
-the index at which the search begins, and defaults to zero.
+  Returns the lowest index in the object where the substring
+  \var{string} is found.  Returns \code{-1} on failure.  \var{start}
+  is the index at which the search begins, and defaults to zero.
 \end{methoddesc}
 
 \begin{methoddesc}{flush}{\optional{offset, size}}
-Flushes changes made to the in-memory copy of a file back to disk.
-Without use of this call there is no guarantee that changes are
-written back before the object is destroyed.  If \var{offset} and
-\var{size} are specified, only changes to the given range of bytes
-will be flushed to disk; otherwise, the whole extent of the mapping is
-flushed.
+  Flushes changes made to the in-memory copy of a file back to disk.
+  Without use of this call there is no guarantee that changes are
+  written back before the object is destroyed.  If \var{offset} and
+  \var{size} are specified, only changes to the given range of bytes
+  will be flushed to disk; otherwise, the whole extent of the mapping
+  is flushed.
 \end{methoddesc}
 
 \begin{methoddesc}{move}{\var{dest}, \var{src}, \var{count}}
-Copy the \var{count} bytes starting at offset \var{src} 
-to the destination index \var{dest}.
+  Copy the \var{count} bytes starting at offset \var{src} to the
+  destination index \var{dest}.  If the mmap was created with
+  \constant{ACCESS_READ}, then calls to move will throw a
+  \exception{TypeError} exception.
 \end{methoddesc}
 
 \begin{methoddesc}{read}{\var{num}}
-Return a string containing up to \var{num} bytes starting from the
-current file position; the file position is updated to point after the
-bytes that were returned. 
+  Return a string containing up to \var{num} bytes starting from the
+  current file position; the file position is updated to point after the
+  bytes that were returned.
 \end{methoddesc}
 
 \begin{methoddesc}{read_byte}{}
-Returns a string of length 1 containing the character at the current
-file position, and advances the file position by 1.
+  Returns a string of length 1 containing the character at the current
+  file position, and advances the file position by 1.
 \end{methoddesc}
 
 \begin{methoddesc}{readline}{}
-Returns a single line, starting at the current file position and up to 
-the next newline.
+  Returns a single line, starting at the current file position and up to 
+  the next newline.
 \end{methoddesc}
 
 \begin{methoddesc}{resize}{\var{newsize}}
+  If the mmap was created with \constant{ACCESS_READ} or
+  \constant{ACCESS_COPY}, resizing the map will throw a \exception{TypeError} exception.
 \end{methoddesc}
 
 \begin{methoddesc}{seek}{pos\optional{, whence}}
-Set the file's current position.
-\var{whence} argument is optional and defaults to \code{0} (absolute
-file positioning); other values are \code{1} (seek relative to the
-current position) and \code{2} (seek relative to the file's end).
+  Set the file's current position.  \var{whence} argument is optional
+  and defaults to \code{0} (absolute file positioning); other values
+  are \code{1} (seek relative to the current position) and \code{2}
+  (seek relative to the file's end).
 \end{methoddesc}
 
 \begin{methoddesc}{size}{}
-Return the length of the file, which can be larger than the size
-of the memory-mapped area. 
+  Return the length of the file, which can be larger than the size of
+  the memory-mapped area.
 \end{methoddesc}
 
 \begin{methoddesc}{tell}{}
-Returns the current position of the file pointer.
+  Returns the current position of the file pointer.
 \end{methoddesc}
 
 \begin{methoddesc}{write}{\var{string}}
-Write the bytes in \var{string} into memory at the current position of
-the file pointer; the file position is updated to point after the
-bytes that were written. 
+  Write the bytes in \var{string} into memory at the current position
+  of the file pointer; the file position is updated to point after the
+  bytes that were written. If the mmap was created with
+  \constant{ACCESS_READ}, then writing to it will throw a
+  \exception{TypeError} exception.
 \end{methoddesc}
 
 \begin{methoddesc}{write_byte}{\var{byte}}
-Write the single-character string \var{byte} into memory at the
-current position of the file pointer; the file position is advanced by
-\code{1}.
+  Write the single-character string \var{byte} into memory at the
+  current position of the file pointer; the file position is advanced
+  by \code{1}.If the mmap was created with \constant{ACCESS_READ},
+  then writing to it will throw a \exception{TypeError} exception.
 \end{methoddesc}