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 ellerNone
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 argumentenfileno
,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ärmmap
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, ochMAP_SHARED
skapar en mappning som delas med alla andra processer som mappar samma områden i filen. Standardvärdet ärMAP_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
ochPROT_WRITE
, för att ange att sidorna kan läsas eller skrivas. prot är som standardPROT_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 medPAGESIZE
på Unix-system.Om trackfd är
False
kommer filbeskrivaren som anges av fileno inte att dupliceras och det resulterandemmap
-objektet kommer inte att associeras med mappens underliggande fil. Detta innebär att metodernasize()
ochresize()
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 enwith
-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 argumentenfileno
,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
ellerALLOCATIONGRANULARITY
.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 ettTypeError
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
ellerACCESS_COPY
, kommer det att leda till ettTypeError
-undantag. Om du ändrar storlek på en karta som skapats med trackfd satt tillFalse
, kommer ettValueError
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
eller0
(absolut filpositionering); andra värden äros.SEEK_CUR
eller1
(sök relativt den aktuella positionen) ochos.SEEK_END
eller2
(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 ettValueError
att uppstå). Filpositionen uppdateras så att den pekar efter de byte som skrevs. Om mmap skapades medACCESS_READ
, så kommer skrivning till den att ge upphov till ettTypeError
undantag.Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.
Ändrad i version 3.6: Antalet skrivna bytes returneras nu.
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 ochMAP_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
ochMAP_CONCEAL
.Tillagd i version 3.13: Lade till
MAP_32BIT
,MAP_HASSEMAPHORE
,MAP_JIT
,MAP_NOCACHE
,MAP_NOEXTEND
,MAP_NORESERVE
,MAP_RESILIENT_CODESIGN
,MAP_RESILIENT_MEDIA
,MAP_TPRO
,MAP_TRANSLATED_ALLOW_EXECUTE
, ochMAP_UNIX03
konstanter.