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, andMAP_SHARED
creates a mapping that’s shared with all other processes mapping the same areas of the file. The default value isMAP_SHARED
.prot, if specified, gives the desired memory protection; the two most useful values are
PROT_READ
andPROT_WRITE
, to specify that the pages may be read or written. prot defaults toPROT_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 toPAGESIZE
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
orALLOCATIONGRANULARITY
.(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 aTypeError
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
orACCESS_COPY
, resizing the map will raise aTypeError
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
or0
(absolute file positioning); other values areos.SEEK_CUR
or1
(seek relative to the current position) andos.SEEK_END
or2
(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.
-