mmap — Stöd för minnesmappade filer


Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Minnesmappade filobjekt beter sig som både bytearray och som filobjekt. Du kan använda mmap-objekt på de flesta ställen där bytearray förväntas; till exempel kan du använda modulen re för att söka igenom en minnesmappad fil. Du kan också ändra en enstaka byte genom att göra obj[index] = 97, eller ändra en delsekvens genom att tilldela en slice: obj[i1:i2] = b'...'. Du kan också läsa och skriva data med början vid den aktuella filpositionen och seek() genom filen till olika positioner.

En minnesmappad fil skapas av mmap-konstruktören, som är olika i Unix och Windows. I båda fallen måste du tillhandahålla en filbeskrivare för en fil som är öppen för uppdatering. Om du vill mappa ett befintligt Python-filobjekt använder du dess fileno()-metod för att få rätt värde för parametern fileno. Annars kan du öppna filen med hjälp av funktionen os.open(), som returnerar en filbeskrivning direkt (filen måste fortfarande stängas när den är klar).

Anteckning

Om du vill skapa en minnesmappning för en skrivbar, buffrad fil, bör du flush() filen först. Detta är nödvändigt för att säkerställa att lokala ändringar av buffertarna faktiskt är tillgängliga för mappningen.

För både Unix- och Windows-versionerna av konstruktören kan access anges som en valfri nyckelordsparameter. access accepterar ett av fyra värden: ACCESS_READ, ACCESS_WRITE, eller ACCESS_COPY för att ange skrivskyddad läsning, genomskrivning respektive kopiering vid skrivning, eller ACCESS_DEFAULT för att hänvisa till prot. access kan användas både på Unix och Windows. Om access inte anges returnerar Windows mmap en genomskrivningsmappning. De initiala minnesvärdena för alla tre access-typerna hämtas från den angivna filen. Tilldelning till en minnesmappning av typen ACCESS_READ ger upphov till ett undantag av typen TypeError. Tilldelning till en ACCESS_WRITE-minnesmappning påverkar både minnet och den underliggande filen. Tilldelning till en ACCESS_COPY-minnesmappning påverkar minnet men uppdaterar inte den underliggande filen.

Ändrad i version 3.7: Lagt till ACCESS_DEFAULT konstant.

För att kartlägga anonyma minnen ska -1 anges som fileno tillsammans med längden.

class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0)

(Windows-version) Mappar längd byte från filen som anges av filhandtaget fileno och skapar ett mmap-objekt. Om length är större än filens aktuella storlek utökas filen till att innehålla length byte. Om längd är 0 är den maximala längden på mappningen den aktuella filstorleken, förutom att om filen är tom gör Windows ett undantag (du kan inte skapa en tom mappning i Windows).

tagname, om det anges och inte None, är en sträng som anger ett taggnamn för mappningen. I Windows kan du ha många olika mappningar mot samma fil. Om du anger namnet på en befintlig tagg öppnas den taggen, annars skapas en ny tagg med detta namn. Om denna parameter utelämnas eller None skapas mappningen utan namn. Om du undviker att använda parametern tagname blir det lättare att hålla din kod portabel mellan Unix och Windows.

offset kan anges som en icke-negativ heltalsförskjutning. mmap-referenser kommer att vara relativa till förskjutningen från början av filen. offset är 0 som standard. offset måste vara en multipel av ALLOCATIONGRANULARITY.

Utlöser en auditing event mmap.__new__ med argumenten fileno, length, access, offset.

class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE | PROT_READ, access=ACCESS_DEFAULT, offset=0, *, trackfd=True)

(Unix version) Mappar längd byte från filen som anges av filbeskrivaren fileno och returnerar ett mmap-objekt. Om längd är 0 kommer den maximala längden på mappningen att vara den aktuella storleken på filen när mmap anropas.

flags anger hur mappningen ska se ut. MAP_PRIVATE skapar en privat copy-on-write-mappning, så ändringar i innehållet i mmap-objektet kommer att vara privata för den här processen, och MAP_SHARED skapar en mappning som delas med alla andra processer som mappar samma områden i filen. Standardvärdet är MAP_SHARED. Vissa system har ytterligare möjliga flaggor med den fullständiga listan som anges i MAP_* constants.

prot, om det anges, ger önskat minnesskydd; de två mest användbara värdena är PROT_READ och PROT_WRITE, för att ange att sidorna kan läsas eller skrivas. prot är som standard PROT_READ | PROT_WRITE.

access kan anges i stället för flags och prot som en valfri nyckelordsparameter. Det är ett fel att ange både flags, prot och access. Se beskrivningen av access ovan för information om hur denna parameter ska användas.

offset kan anges som en icke-negativ heltalsförskjutning. mmap-referenser kommer att vara relativa till förskjutningen från början av filen. offset är 0 som standard. offset måste vara en multipel av ALLOCATIONGRANULARITY som är lika med PAGESIZE på Unix-system.

Om trackfd är False kommer filbeskrivaren som anges av fileno inte att dupliceras och det resulterande mmap-objektet kommer inte att associeras med mappens underliggande fil. Detta innebär att metoderna size() och resize() misslyckas. Detta läge är användbart för att begränsa antalet öppna filbeskrivare.

För att säkerställa giltigheten för den skapade minnesmappningen synkroniseras filen som anges av deskriptorn fileno internt automatiskt med det fysiska backinglagret på macOS.

Ändrad i version 3.13: Parametern trackfd har lagts till.

Detta exempel visar ett enkelt sätt att använda mmap:

import mmap

# write a simple example file
with open("hello.txt", "wb") as f:
    f.write(b"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 b"Hello Python!\n"
    # read content via slice notation
    print(mm[:5])  # prints b"Hello"
    # update content using slice notation;
    # note that new content must have same size
    mm[6:] = b" world!\n"
    # ... and read again using standard file methods
    mm.seek(0)
    print(mm.readline())  # prints b"Hello  world!\n"
    # close the map
    mm.close()

mmap kan också användas som en kontexthanterare i en with-sats:

import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")

Tillagd i version 3.2: Stöd för kontextansvarig.

I nästa exempel visas hur du skapar en anonym karta och utbyter data mellan föräldra- och barnprocesserna:

import mmap
import os

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

pid = os.fork()

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

    mm.close()

Utlöser en auditing event mmap.__new__ med argumenten fileno, length, access, offset.

Minnesmappade filobjekt stöder följande metoder:

close()

Stänger mmap. Efterföljande anrop till andra metoder i objektet kommer att resultera i ett ValueError-undantag. Detta kommer inte att stänga den öppna filen.

closed

True om filen är stängd.

Tillagd i version 3.2.

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

Returnerar det lägsta indexet i objektet där underföljden sub finns, så att sub ingår i intervallet [start, slut]. De valfria argumenten start och end tolkas som i slice-notation. Returnerar -1 om den misslyckas.

Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.

flush([offset[, size]])

Spolar tillbaka ändringar som gjorts i minneskopian av en fil till disken. Utan användning av detta anrop finns det ingen garanti för att ändringar skrivs tillbaka innan objektet förstörs. Om offset och size anges, kommer endast ändringar i det angivna intervallet av byte att spolas till disken; annars spolas hela omfattningen av mappningen. offset måste vara en multipel av PAGESIZE eller ALLOCATIONGRANULARITY.

None returneras för att indikera framgång. Ett undantag uppstår när anropet misslyckades.

Ändrad i version 3.8: Tidigare returnerades ett värde som inte var noll vid framgång, medan noll returnerades vid fel under Windows. Under Unix returnerades ett nollvärde vid framgång och ett undantag vid fel.

madvise(option[, start[, length]])

Skicka råd option till kärnan om minnesregionen som börjar vid start och sträcker sig length byte. option måste vara en av de MADV_*-konstanter som finns tillgängliga i systemet. Om start och length utelämnas täcks hela mappningen. På vissa system (inklusive Linux) måste start vara en multipel av PAGESIZE.

Tillgänglighet: System med systemanropet madvise().

Tillagd i version 3.8.

move(dest, src, count)

Kopierar antal byte från offset src till destinationsindex dest. Om mmap skapades med ACCESS_READ, så kommer anrop till move att ge upphov till ett TypeError undantag.

read([n])

Returnerar en bytes som innehåller upp till n byte med start från aktuell filposition. Om argumentet utelämnas, None eller negativt, returneras alla byte från den aktuella filpositionen till slutet av mappningen. Filpositionen uppdateras så att den pekar efter de byte som returnerades.

Ändrad i version 3.3: Argumentet kan utelämnas eller vara None.

read_byte()

Returnerar en byte vid den aktuella filpositionen som ett heltal och flyttar fram filpositionen med 1.

readline()

Returnerar en enda rad, med början vid den aktuella filpositionen och fram till nästa nya rad. Filpositionen uppdateras så att den pekar efter de bytes som returnerades.

resize(newsize)

Ändrar storlek på kartan och den underliggande filen, om en sådan finns.

Om du ändrar storlek på en karta som skapats med access av ACCESS_READ eller ACCESS_COPY, kommer det att leda till ett TypeError-undantag. Om du ändrar storlek på en karta som skapats med trackfd satt till False, kommer ett ValueError undantag att uppstå.

På Windows: Om du ändrar storlek på kartan kommer det att uppstå ett OSError om det finns andra kartor mot samma namngivna fil. Om du ändrar storlek på en anonym karta (dvs. mot sidfilen) skapas en ny karta i tysthet med originaldata som kopieras över upp till längden på den nya storleken.

Ändrad i version 3.11: Misslyckas korrekt vid försök att ändra storlek när en annan karta hålls kvar Tillåter ändring av storlek mot en anonym karta i Windows

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

Returnerar det högsta indexet i objektet där underföljden sub finns, så att sub ingår i intervallet [start, slut]. De valfria argumenten start och end tolkas som i slice-notation. Returnerar -1 om den misslyckas.

Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.

seek(pos[, whence])

Ställ in filens aktuella position. whence-argumentet är valfritt och standardvärdet är os.SEEK_SET eller 0 (absolut filpositionering); andra värden är os.SEEK_CUR eller 1 (sök relativt den aktuella positionen) och os.SEEK_END eller 2 (sök relativt filens slut).

Ändrad i version 3.13: Returnerar den nya absoluta positionen istället för None.

seekable()

Returnerar om filen stöder sökning, och returvärdet är alltid True.

Tillagd i version 3.13.

size()

Returnera längden på filen, som kan vara större än storleken på det minnesmappade området.

tell()

Returnerar den aktuella positionen för filpekaren.

write(bytes)

Skriv bytena i bytes till minnet vid filpekarens aktuella position och returnera antalet skrivna byte (aldrig mindre än len(bytes), eftersom om skrivningen misslyckas kommer ett ValueError att uppstå). Filpositionen uppdateras så att den pekar efter de byte som skrevs. Om mmap skapades med ACCESS_READ, så kommer skrivning till den att ge upphov till ett TypeError undantag.

Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.

Ändrad i version 3.6: Antalet skrivna bytes returneras nu.

write_byte(byte)

Skriv in heltalet byte i minnet vid filpekarens aktuella position; filpositionen flyttas fram med 1. Om mmap skapades med ACCESS_READ, så kommer skrivning till den att ge upphov till ett TypeError undantag.

MADV_* Konstanter

mmap.MADV_NORMAL
mmap.MADV_RANDOM
mmap.MADV_SEQUENTIAL
mmap.MADV_WILLNEED
mmap.MADV_DONTNEED
mmap.MADV_REMOVE
mmap.MADV_DONTFORK
mmap.MADV_DOFORK
mmap.MADV_HWPOISON
mmap.MADV_MERGEABLE
mmap.MADV_UNMERGEABLE
mmap.MADV_SOFT_OFFLINE
mmap.MADV_HUGEPAGE
mmap.MADV_NOHUGEPAGE
mmap.MADV_DONTDUMP
mmap.MADV_DODUMP
mmap.MADV_FREE
mmap.MADV_NOSYNC
mmap.MADV_AUTOSYNC
mmap.MADV_NOCORE
mmap.MADV_CORE
mmap.MADV_PROTECT
mmap.MADV_FREE_REUSABLE
mmap.MADV_FREE_REUSE

Dessa alternativ kan skickas till mmap.madvise(). Alla alternativ kommer inte att finnas på alla system.

Tillgänglighet: System med systemanropet madvise().

Tillagd i version 3.8.

MAP_* Konstanter

mmap.MAP_SHARED
mmap.MAP_PRIVATE
mmap.MAP_32BIT
mmap.MAP_ALIGNED_SUPER
mmap.MAP_ANON
mmap.MAP_ANONYMOUS
mmap.MAP_CONCEAL
mmap.MAP_DENYWRITE
mmap.MAP_EXECUTABLE
mmap.MAP_HASSEMAPHORE
mmap.MAP_JIT
mmap.MAP_NOCACHE
mmap.MAP_NOEXTEND
mmap.MAP_NORESERVE
mmap.MAP_POPULATE
mmap.MAP_RESILIENT_CODESIGN
mmap.MAP_RESILIENT_MEDIA
mmap.MAP_STACK
mmap.MAP_TPRO
mmap.MAP_TRANSLATED_ALLOW_EXECUTE
mmap.MAP_UNIX03

Dessa är de olika flaggor som kan skickas till mmap.mmap(). MAP_ALIGNED_SUPER är endast tillgänglig på FreeBSD och MAP_CONCEAL är endast tillgänglig på OpenBSD. Observera att vissa alternativ kanske inte finns på vissa system.

Ändrad i version 3.10: Lagt till MAP_POPULATE konstant.

Tillagd i version 3.11: Lagt till MAP_STACK konstant.

Tillagd i version 3.12: Lagt till konstanterna MAP_ALIGNED_SUPER och MAP_CONCEAL.