Changeset 391 for python/trunk/Doc/library/mmap.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/mmap.rst (modified) (9 diffs)

python/trunk/Doc/library/mmap.rst

@@ -23 +23 @@
 :func:`os.open` function, which returns a file descriptor directly (the file
 still needs to be closed when done).
+
+.. note::
+   If you want to create a memory-mapping for a writable, buffered file, you
+   should :func:`~io.IOBase.flush` the file first.  This is necessary to ensure
+   that local modifications to the buffers are actually available to the
+   mapping.
 
 For both the Unix and Windows versions of the constructor, *access* may be
@@ -95 +101 @@
    ALLOCATIONGRANULARITY.
 
+   To ensure validity of the created memory mapping the file specified
+   by the descriptor *fileno* is internally automatically synchronized
+   with physical backing store on Mac OS X and OpenVMS.
+
    This example shows a simple way of using :class:`mmap`::
 
@@ -105 +115 @@
       with open("hello.txt", "r+b") as f:
           # memory-map the file, size 0 means whole file
-          map = mmap.mmap(f.fileno(), 0)
+          mm = mmap.mmap(f.fileno(), 0)
           # read content via standard file methods
-          print map.readline()  # prints "Hello Python!"
+          print mm.readline()  # prints "Hello Python!"
           # read content via slice notation
-          print map[:5]  # prints "Hello"
+          print mm[:5]  # prints "Hello"
           # update content using slice notation;
           # note that new content must have same size
-          map[6:] = " world!\n"
+          mm[6:] = " world!\n"
           # ... and read again using standard file methods
-          map.seek(0)
-          print map.readline()  # prints "Hello  world!"
+          mm.seek(0)
+          print mm.readline()  # prints "Hello  world!"
           # close the map
-          map.close()
+          mm.close()
 
 
@@ -126 +136 @@
       import os
 
-      map = mmap.mmap(-1, 13)
-      map.write("Hello world!")
+      mm = mmap.mmap(-1, 13)
+      mm.write("Hello world!")
 
       pid = os.fork()
 
       if pid == 0: # In a child process
-          map.seek(0)
-          print map.readline()
-
-          map.close()
+          mm.seek(0)
+          print mm.readline()
+
+          mm.close()
 
 
@@ -143 +153 @@
    .. method:: close()
 
-      Close the file.  Subsequent calls to other methods of the object will
-      result in an exception being raised.
+      Closes the mmap. Subsequent calls to other methods of the object will
+      result in a ValueError exception being raised. This will not close
+      the open file.
 
 
@@ -174 +185 @@
       Copy the *count* bytes starting at offset *src* to the destination index
       *dest*.  If the mmap was created with :const:`ACCESS_READ`, then calls to
-      move will throw a :exc:`TypeError` exception.
+      move will raise a :exc:`TypeError` exception.
 
 
@@ -200 +211 @@
       Resizes the map and the underlying file, if any. If the mmap was created
       with :const:`ACCESS_READ` or :const:`ACCESS_COPY`, resizing the map will
-      throw a :exc:`TypeError` exception.
+      raise a :exc:`TypeError` exception.
 
 
@@ -235 +246 @@
       file pointer; the file position is updated to point after the bytes that
       were written. If the mmap was created with :const:`ACCESS_READ`, then
-      writing to it will throw a :exc:`TypeError` exception.
+      writing to it will raise a :exc:`TypeError` exception.
 
 
@@ -243 +254 @@
       position of the file pointer; the file position is advanced by ``1``. If
       the mmap was created with :const:`ACCESS_READ`, then writing to it will
-      throw a :exc:`TypeError` exception.
-
-
+      raise a :exc:`TypeError` exception.