[Python-checkins] CVS: python/dist/src/Doc/lib libmmap.tex,1.5,1.6
Tim Peters
tim_one@users.sourceforge.net
Tue, 13 Nov 2001 15:11:21 -0800
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv31339/python/Doc/lib
Modified Files:
libmmap.tex
Log Message:
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.
Index: libmmap.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libmmap.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** libmmap.tex 2001/09/25 19:00:08 1.5
--- libmmap.tex 2001/11/13 23:11:19 1.6
***************
*** 1,4 ****
\section{\module{mmap} ---
! Memory-mapped file support}
\declaremodule{builtin}{mmap}
--- 1,4 ----
\section{\module{mmap} ---
! Memory-mapped file support}
\declaremodule{builtin}{mmap}
***************
*** 24,57 ****
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.
\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}.
\end{funcdesc}
--- 24,88 ----
directly (the file still needs to be closed when done).
! \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\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}
***************
*** 61,132 ****
\begin{methoddesc}{close}{}
! 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.
\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.
\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}.
\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.
\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.
\end{methoddesc}
\begin{methoddesc}{readline}{}
! Returns a single line, starting at the current file position and up to
! the next newline.
\end{methoddesc}
\begin{methoddesc}{resize}{\var{newsize}}
\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).
\end{methoddesc}
\begin{methoddesc}{size}{}
! 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.
\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.
\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}.
\end{methoddesc}
--- 92,170 ----
\begin{methoddesc}{close}{}
! 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.
\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.
\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}. 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.
\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.
\end{methoddesc}
\begin{methoddesc}{readline}{}
! 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).
\end{methoddesc}
\begin{methoddesc}{size}{}
! 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.
\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. 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}.If the mmap was created with \constant{ACCESS_READ},
! then writing to it will throw a \exception{TypeError} exception.
\end{methoddesc}