7.9 `mmap` -- Supporto per i file mappati in memoria

Gli oggetti file mappati in memoria si comportano sia come oggetti stringhe che come oggetti file. Diversamente dai normali oggetti stringa, questi sono mutabili. Si possono usare gli oggetti mmap in molti posti nei quali ci si aspettano delle stringhe; per esempio, si può usare il modulo re per ricercare all'interno di un file mappato in memoria. Visto che sono mutabili, si può modificare un singolo carattere con obj[index] = 'a' o modificare una sottostringa assegnandola ad una fetta: obj[i1:i2] = '...'. Si possono inoltre leggere e scrivere dati iniziando dalla posizione corrente nel file, ed usare seek() per spostarsi in posizioni differenti.

Un file mappato in memoria viene creato attraverso la funzione mmap(), che è differente su Unix e Windows. In entrambi i casi si deve fornire un descrittore di file di un file aperto per la modifica. Se si vuole mappare un oggetto file Python esistente, si usi il suo metodo fileno() per ottenere il valore corretto del parametro fileno. Altrimenti, si può aprire il file usando la funzione os.open(), che restituisce direttamente un descrittore di file (il file necessita comunque di essere chiuso al termine).

Per entrambe le versioni Unix e Windows della funzione, access può essere specificato come un parametro facoltativo a parola chiave. access accetta uno di questi tre valori: ACCESS_READ, ACCESS_WRITE o ACCESS_COPY per specificare rispettivamente sola lettura, scrittura o memoria copy-on-write. access può essere usato sia su Unix che su Windows. Se access non viene specificato, la mmap di Windows restituisce una mappatura in scrittura. I valori iniziali di memoria per tutti i tre tipi di accesso sono presi dal file specificato. L'assegnamento ad una mappa di memoria ACCESS_READ solleva l'eccezione TypeError. L'assegnamento ad una mappa di memoria ACCESS_WRITE agisce sia sulla memoria che sul file sottostante. L'assegnamento ad una mappa di memoria ACCESS_COPY agisce unicamente sulla memoria, senza aggiornare il file sottostante.

mmap( fileno, length[, tagname[, access]]): (Versione Windows) Mappa length byte dal file specificato dal gestore di file fileno, e restituisce un oggetto mmap. Se length è 0, la lunghezza massima della mappa sarà la dimensione corrente del file al momento della chiamata a mmap().
tagname, se specificato e diverso da None, è una stringa che fornisce un nome di tag per la mappatura. Windows vi permette di avere diverse mappature riferite allo stesso file. Se specificate il nome di un tag esistente, quel tag viene aperto, altrimenti viene creato un nuovo tag con questo nome. Se questo parametro viene omesso o è None, la mappatura viene creata senza nome. Evitando di usare il parametro tag il codice rimarrà portabile fra Unix e Windows.

mmap( fileno, length[, flags[, prot[, access]]])

(Unix version) Mappa length byte dal file specificato dal descrittore di file fileno, e restituisce un oggetto mmap.

flags specifica la natura della mappatura. MAP_PRIVATE crea una mappatura copy-on-write privata, perciò la modifica del contenuto dell'oggetto mmap rimarrà privata a questo processo, mentre MAP_SHARED crea una mappatura condivisa con tutti gli altri processi che stanno mappando le stesse aree del file. Il valore predefinito è MAP_SHARED.

prot, se specificato, fornisce la protezione di memoria desiderata; i due valori più utili sono PROT_READ e PROT_WRITE, per specificare che le pagine possono essere lette o scritte. prot, il valore predefinito è PROT_READ | PROT_WRITE.

access può essere specificato al posto di flags e prot come un argomento a parola chiave facoltativo. Specificare flags, prot e access rappresenta un errore. Leggere la descrizione qui sopra di access per delle informazioni su come gestire questo parametro.

I file mappati in memoria supportano i seguenti metodi:

close( ): Chiude il file. Chiamate successive ad altri metodi dell'oggetto solleveranno un'eccezione.

find( string[, start]): Restituisce l'indice più basso nell'oggetto in cui viene trovata la sottostringa string. Restituisce -1 in caso di fallimento. start è l'indice dal quale inizia la ricerca, il valore predefinito è zero.

flush( [offset, size]): Aggiorna le modifiche fatte alla copia in memoria del file su disco. Senza usare questa chiamata non c'è garanzia che le modifiche vengano scritte sul disco prima che l'oggetto venga distrutto. Se offset e size vengono specificati, solo le modifiche sull'intervallo dato di byte verranno scritte sul disco; altrimenti, viene aggiornata l'intera estensione della mappatura.

move( dest, src, count): Copia count byte partendo da src all'indice di destinazione dest. Se la mmap è stata creata con ACCESS_READ, la chiamata a move solleverà l'eccezione TypeError.

read( num): Restituisce una stringa contenente almeno num byte partendo dalla posizione corrente nel file; la posizione nel file viene aggiornata in modo da puntare dopo i byte che sono stati restituiti.

read_byte( ): Restituisce una stringa di lunghezza 1 contenente il carattere alla posizione corrente nel file, e la fa avanzare di 1.

readline( ): Restituisce una singola riga, partente dalla posizione corrente nel file, ed avanza alla prossima nuova riga.

resize( newsize): Se la mmap è stata creata con ACCESS_READ o ACCESS_COPY, ridimensionare la mappa solleverà un'eccezione TypeError.

seek( pos[, whence]): Imposta la posizione corrente nel file, l'argomento whence è facoltativo e il valore predefinito è 0 (posizione assoluta nel file); altri valori sono 1 (relativa alla posizione corrente nel file) e 2 (relativa alla fine del file).

size( ): Restituisce la lunghezza del file, che può essere più grande della dimensione dell'area della mappa di memoria.

tell( ): Restituisce la posizione corrente del puntatore del file.

write( string): Scrive i byte in string nella memoria alla posizione corrente del puntatore del file; la posizione nel file è aggiornata per puntare dopo i byte che sono stati scritti. Se la mmap è stata creata con ACCESS_READ, scrivervi solleverà un'eccezione TypeError.

write_byte( byte): Scrive la stringa di un solo carattere byte nella memoria, alla posizione corrente del puntatore nel file; la posizione nel file è avanzata di 1. Se la mmap è stata creata con ACCESS_READ, scrivervi solleverà un'eccezione TypeError.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.

7.9 mmap -- Supporto per i file mappati in memoria

7.9 `mmap` -- Supporto per i file mappati in memoria