mmap — Поддержка файлов с отображением в память

Объекты файлов с отображением в память ведут себя как строки и как объекты файлов. Однако, в отличие от обычных строковых объектов, они изменяемы. Вы можете использовать объекты mmap в большинстве мест, где ожидаются строки; например, вы можете использовать модуль re, чтобы искать в файле с отображением в память. Поскольку они изменяемы, вы можете изменить один символ, выполнив obj[index] = 'a', или изменить подстроку, присвоив значение срезу: obj[i1:i2] = '...'. Вы также можете читать и записывать данные, начиная с текущей позиции файла, и seek() через файл в разные позиции.

Файл с отображением в память создается конструктором mmap, который отличается на Unix и Windows. В любом случае вы должны указать дескриптор файла, открытого для обновления. Если вы хотите отобразить существующий объект файла Python, используйте его метод fileno() для получения правильного значения для параметра fileno. В противном случае вы можете открыть файл с помощью функции os.open(), которая возвращает дескриптор файла непосредственно (файл все равно необходимо закрыть по завершении).

Для обоих версий конструктора (Unix и Windows), access может быть указан как необязательный параметр ключевого слова. access принимает одно из трех значений: ACCESS_READ, ACCESS_WRITE, или ACCESS_COPY для указания соответственно только чтения, записи с прохождением или копирования при записи в память. access может быть использован как на Unix, так и на Windows. Если access не указан, Windows mmap возвращает отображение с прохождением записи. Начальные значения памяти для всех трех типов доступа берутся из указанного файла. Присваивание значения в ACCESS_READ отображении памяти вызывает исключение TypeError. Присваивание значения в ACCESS_WRITE отображении памяти влияет как на память, так и на исходный файл. Присваивание значения в ACCESS_COPY отображении памяти влияет на память, но не обновляет исходный файл.

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

(Версия Windows) Отображает length байт из файла, указанного дескриптором файла fileno, и создает объект mmap. Если length больше текущего размера файла, файл расширяется, чтобы содержать length байт. Если length 0, максимальная длина отображения — текущий размер файла, за исключением того, что если файл пуст, Windows генерирует исключение (вы не можете создать пустое отображение на Windows).

tagname, если указан и не None, — это строка, предоставляющая имя тега для отображения. Windows позволяет иметь множество различных отображений одного и того же файла. Если вы укажете имя существующего тега, этот тег откроется, иначе будет создан новый тег с этим именем. Если этот параметр опущен или None, отображение создается без имени. Избегайте использования параметра tagname, чтобы ваш код был совместим между Unix и Windows.

offset может быть указан как неотрицательное целое число смещения. mmap-ссылка будет относиться к смещению от начала файла. offset по умолчанию равен 0. offset должен быть кратным ALLOCATIONGRANULARITY.

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

(Версия для Unix) Картирует length байтов из файла, указанного дескриптором файла fileno, и возвращает объект mmap. Если length равно 0, максимальный размер карты будет соответствовать текущему размеру файла при вызове mmap.

flags определяет характер отображения. MAP_PRIVATE создаёт частную карту с копированием при записи, поэтому изменения в содержимом объекта mmap будут приватными для данного процесса, а MAP_SHARED создаёт карту, которая используется совместно всеми процессами, отображающими те же участки файла. Значение по умолчанию равно MAP_SHARED.

prot, если указано, задаёт желаемую защиту памяти; две наиболее полезные значения — PROT_READ и PROT_WRITE, чтобы указать, что страницы могут быть прочитаны или записаны. prot по умолчанию равно PROT_READ | PROT_WRITE.

access может быть указано вместо flags и prot как необязательный ключевой параметр. Указание одновременно flags, prot и access является ошибкой. См. описание access выше для информации об использовании этого параметра.

offset может быть указано как неотрицательное целое смещение. Ссылки mmap будут относиться к смещению от начала файла. offset по умолчанию равно 0. offset должен быть кратен ALLOCATIONGRANULARITY, что равно PAGESIZE на системах Unix.

Для обеспечения корректности созданной карты памяти, файл, указанный дескриптором fileno, автоматически синхронизируется с физическим носителем на Mac OS X и OpenVMS.

Этот пример демонстрирует простой способ использования 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()

Следующий пример демонстрирует, как создать анонимную карту и обмениваться данными между родительским и дочерним процессами:

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()

Объекты файлов с отображением памяти поддерживают следующие методы:

close()

Закрывает mmap. Последующие вызовы других методов объекта приведут к исключению ValueError. Это не закрывает открытый файл.

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

Возвращает наименьший индекс в объекте, где подстрока string найдена, так что string содержится в диапазоне [start, end]. Необязательные аргументы start и end интерпретируются так же, как в обозначении срезов. Возвращает -1 при ошибке.

flush([offset, size])

Выгружает изменения, внесённые в копию файла в памяти, обратно на диск. Без использования этого вызова нет гарантии, что изменения будут записаны обратно перед уничтожением объекта. Если offset и size заданы, только изменения в указанном диапазоне байтов будут выгружены на диск; в противном случае весь объём отображения выгружается. offset должен быть кратен PAGESIZE или ALLOCATIONGRANULARITY.

(Версия для Windows) ненулевое значение указывает на успех; ноль — на неудачу.

(Версия для Unix) Ноль возвращается, чтобы указать успех. При неудачном вызове возбуждается исключение.

move(dest, src, count)

Копирует count байтов, начиная со смещения src, в индекс назначения dest. Если mmap был создан с ACCESS_READ, вызовы move приведут к исключению TypeError.

read(num)

Возвращает строку, содержащую до num байтов, начиная с текущей позиции файла; позиция файла обновляется для указания на байты после возвращённых.

read_byte()

Возвращает строку длиной 1, содержащую символ в текущей позиции файла, и перемещает позицию файла вперёд на 1.

readline()

Возвращает одну строку, начиная с текущей позиции файла и до следующего символа новой строки.

resize(newsize)

Изменяет размер карты и, при необходимости, базового файла. Если mmap был создан с ACCESS_READ или ACCESS_COPY, изменение размера карты вызовет исключение TypeError.

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

Возвращает наибольший индекс в объекте, где подстрока string найдена, так что string содержится в диапазоне [start, end]. Необязательные аргументы start и end интерпретируются так же, как в обозначении срезов. Возвращает -1 при ошибке.

seek(pos[, whence])

Устанавливает текущую позицию файла. Аргумент whence необязательный и по умолчанию равен os.SEEK_SET или 0 (абсолютное позиционирование в файле); другие значения — os.SEEK_CUR или 1 (смещение относительно текущей позиции) и os.SEEK_END или 2 (смещение относительно конца файла).

size()

Возвращает длину файла, которая может быть больше размера отображаемого участка памяти.

tell()

Возвращает текущую позицию указателя файла.

write(string)

Записывает байты в string в память по текущей позиции указателя файла; позиция файла обновляется для указания на байты после записи. Если mmap был создан с ACCESS_READ, запись в него вызовет исключение TypeError.

write_byte(byte)

Записывает строку из одного символа byte в память по текущей позиции указателя файла; позиция файла сдвигается на 1. Если mmap был создан с ACCESS_READ, запись в него вызовет исключение TypeError.