16.7. mmap — 内存映射文件支持

Memory-mapped file objects behave like both strings and like file objects. Unlike normal string objects, however, these are mutable. You can use mmap objects in most places where strings are expected; for example, you can use the re module to search through a memory-mapped file. Since they’re mutable, you can change a single character by doing obj[index] = 'a', or change a substring by assigning to a slice: obj[i1:i2] = '...'. You can also read and write data starting at the current file position, and seek() through the file to different positions.

内存映射文件是由 mmap 构造函数创建的，其在 Unix和 Windows上是不同的。 无论哪种情况，你都必须为一个打开的文件提供文件描述符以进行更新。 如果你希望映射一个已有的 Python 文件对象，请使用该对象的 fileno() 方法来获取 fileno 参数的正确值。 否则，你可以使用 os.open() 函数来打开这个文件，这会直接返回一个文件描述符（结束时仍然需要关闭该文件）。

注解

如果要为可写的缓冲文件创建内存映射，则应当首先 flush() 该文件。 这确保了对缓冲区的本地修改在内存映射中可用。

For both the Unix and Windows versions of the constructor, access may be specified as an optional keyword parameter. access accepts one of three values: ACCESS_READ, ACCESS_WRITE, or ACCESS_COPY to specify read-only, write-through or copy-on-write memory respectively. access can be used on both Unix and Windows. If 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 ACCESS_READ memory map raises a TypeError exception. Assignment to an ACCESS_WRITE memory map affects both memory and the underlying file. Assignment to an ACCESS_COPY memory map affects memory but does not update the underlying file.

在 2.5 版更改: 要映射匿名内存，应将 -1 作为 fileno 和 length 一起传递。

在 2.6 版更改: mmap.mmap has formerly been a factory function creating mmap objects. Now mmap.mmap is the class itself.

class mmap.mmap(fileno, length[, tagname[, access[, offset]]])

（ Windows 版本） 映射被文件句柄 fileno 指定的文件的 length 个字节，并创建一个 mmap 对象。如果 length 大于当前文件大小，则文件将扩展为包含 length 个字节。如果 length 为 0，则映射的最大长度为当前文件大小。如果文件为空， Windows 会引发异常（你无法在Windows上创建空映射）。

如果 tagname 被指定且不是 None ，则是为映射提供标签名称的字符串。 Windows 允许你对同一文件拥有许多不同的映射。如果指定现有标签的名称，则会打开该标签，否则将创建该名称的新标签。如果省略此参数或设置为 None ，则创建的映射不带名称。避免使用 tag 参数将有助于使代码在Unix和Windows之间可移植。

offset 可以被指定为非负整数偏移量。 mmap 引用将相对于从文件开头的偏移。 offset 默认为0。 offeset 必须是 ALLOCATIONGRANULARITY 的倍数。

class mmap.mmap(fileno, length[, flags[, prot[, access[, offset]]]])

(Unix 版本) 映射文件描述符 fileno 指定的文件的 length 个字节，并返回一个 mmap 对象。如果 length 为 0 ，则当调用 mmap 时，映射的最大长度将为文件的当前大小。

flags specifies the nature of the mapping. 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 MAP_SHARED creates a mapping that’s shared with all other processes mapping the same areas of the file. The default value is MAP_SHARED.

prot, if specified, gives the desired memory protection; the two most useful values are PROT_READ and PROT_WRITE, to specify that the pages may be read or written. prot defaults to PROT_READ | PROT_WRITE.

access may be specified in lieu of flags and prot as an optional keyword parameter. It is an error to specify both flags, prot and access. See the description of access above for information on how to use this parameter.

offset may be specified as a non-negative integer offset. mmap references will be relative to the offset from the beginning of the file. offset defaults to 0. offset must be a multiple of ALLOCATIONGRANULARITY which is equal to PAGESIZE on Unix systems.

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 mmap:

import mmap

# write a simple example file
with open("hello.txt", "wb") as f:
    f.write("Hello Python!\n")

with open("hello.txt", "r+b") as f:
    # memory-map the file, size 0 means whole file
    mm = mmap.mmap(f.fileno(), 0)
    # read content via standard file methods
    print mm.readline()  # prints "Hello Python!"
    # read content via slice notation
    print mm[:5]  # prints "Hello"
    # update content using slice notation;
    # note that new content must have same size
    mm[6:] = " world!\n"
    # ... and read again using standard file methods
    mm.seek(0)
    print mm.readline()  # prints "Hello  world!"
    # close the map
    mm.close()

The next example demonstrates how to create an anonymous map and exchange data between the parent and child processes:

import mmap
import os

mm = mmap.mmap(-1, 13)
mm.write("Hello world!")

pid = os.fork()

if pid == 0:  # In a child process
    mm.seek(0)
    print mm.readline()

    mm.close()

Memory-mapped file objects support the following methods:

close()

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.

find(string[, start[, end]])

Returns the lowest index in the object where the substring string is found, such that string is contained in the range [start, end]. Optional arguments start and end are interpreted as in slice notation. Returns -1 on failure.

flush([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 offset and 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. offset must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY.

(Windows version) A nonzero value returned indicates success; zero indicates failure.

(Unix 版本) 返回零值以表示成功。 当调用失败时将引发异常。

move(dest, src, count)

Copy the count bytes starting at offset src to the destination index dest. If the mmap was created with ACCESS_READ, then calls to move will raise a TypeError exception.

read(num)

Return a string containing up to num bytes starting from the current file position; the file position is updated to point after the bytes that were returned.

read_byte()

Returns a string of length 1 containing the character at the current file position, and advances the file position by 1.

readline()

Returns a single line, starting at the current file position and up to the next newline.

resize(newsize)

Resizes the map and the underlying file, if any. If the mmap was created with ACCESS_READ or ACCESS_COPY, resizing the map will raise a TypeError exception.

rfind(string[, start[, end]])

Returns the highest index in the object where the substring string is found, such that string is contained in the range [start, end]. Optional arguments start and end are interpreted as in slice notation. Returns -1 on failure.

seek(pos[, whence])

Set the file’s current position. whence argument is optional and defaults to os.SEEK_SET or 0 (absolute file positioning); other values are os.SEEK_CUR or 1 (seek relative to the current position) and os.SEEK_END or 2 (seek relative to the file’s end).

size()

Return the length of the file, which can be larger than the size of the memory-mapped area.

tell()

Returns the current position of the file pointer.

write(string)

Write the bytes in 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 ACCESS_READ, then writing to it will raise a TypeError exception.

write_byte(byte)

Write the single-character string byte into memory at the current position of the file pointer; the file position is advanced by 1. If the mmap was created with ACCESS_READ, then writing to it will raise a TypeError exception.