mmap —メモリマップトファイルのサポート
メモリマップトファイルオブジェクトは、 bytearray とファイルオブジェクトの両方のように動作します。 bytearray が予想されるほとんどの場所でmmapオブジェクトを使用できます。 たとえば、 re モジュールを使用して、メモリマップトファイルを検索できます。 obj[index] = 97
を実行して1バイトを変更したり、スライスに割り当てることでサブシーケンスを変更したりすることもできます:obj[i1:i2] = b'...'
。 また、現在のファイル位置からデータを読み書きしたり、seek()
ファイルを介して別の位置にデータを書き込んだりすることもできます。
メモリマップトファイルは、 mmap コンストラクターによって作成されます。これは、UnixとWindowsでは異なります。 いずれの場合も、更新用に開いたファイルのファイル記述子を指定する必要があります。 既存のPythonファイルオブジェクトをマップする場合は、そのfileno()
メソッドを使用して、 fileno パラメーターの正しい値を取得します。 それ以外の場合は、 os.open()関数を使用してファイルを開くことができます。この関数は、ファイル記述子を直接返します(完了したらファイルを閉じる必要があります)。
ノート
書き込み可能なバッファファイルのメモリマッピングを作成する場合は、最初にファイルを flush()する必要があります。 これは、バッファへのローカル変更を実際にマッピングで使用できるようにするために必要です。
コンストラクターのUnixバージョンとWindowsバージョンの両方で、 access をオプションのキーワードパラメーターとして指定できます。 access は、ACCESS_READ
、ACCESS_WRITE
、またはACCESS_COPY
の4つの値のいずれかを受け入れ、読み取り専用、ライトスルー、またはコピーオンライトメモリを指定します。それぞれ、またはACCESS_DEFAULT
を prot に延期します。 access は、UnixとWindowsの両方で使用できます。 access が指定されていない場合、Windowsmmapはライトスルーマッピングを返します。 3つのアクセスタイプすべての初期メモリ値は、指定されたファイルから取得されます。 ACCESS_READ
メモリマップに割り当てると、 TypeError 例外が発生します。 ACCESS_WRITE
メモリマップへの割り当ては、メモリと基になるファイルの両方に影響します。 ACCESS_COPY
メモリマップへの割り当てはメモリに影響しますが、基になるファイルは更新されません。
バージョン3.7で変更: ACCESS_DEFAULT
定数を追加。
匿名メモリをマップするには、長さとともにファイル番号として-1を渡す必要があります。
- class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])
(Windows版)ファイルハンドル fileno で指定されたファイルから長さバイトをマッピングし、mmapオブジェクトを作成します。 length がファイルの現在のサイズよりも大きい場合、ファイルは length バイトを含むように拡張されます。 length が
0
の場合、マップの最大長はファイルの現在のサイズです。ただし、ファイルが空の場合、Windowsで例外が発生します(Windowsで空のマッピングを作成することはできません)。 )。tagname は、
None
ではなく指定されている場合、マッピングのタグ名を示す文字列です。 Windowsでは、同じファイルに対してさまざまなマッピングを行うことができます。 既存のタグの名前を指定すると、そのタグが開きます。指定しない場合は、この名前の新しいタグが作成されます。 このパラメータを省略した場合、またはNone
の場合、マッピングは名前なしで作成されます。 タグパラメータの使用を避けることは、UnixとWindowsの間でコードを移植可能に保つのに役立ちます。offset は、非負の整数オフセットとして指定できます。 mmap参照は、ファイルの先頭からのオフセットを基準にしています。 offset のデフォルトは0です。 offset は
ALLOCATIONGRANULARITY
の倍数である必要があります。
- class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])
(Unixバージョン)ファイル記述子 fileno で指定されたファイルから length バイトをマップし、mmapオブジェクトを返します。 length が
0
の場合、マップの最大長は、 mmap が呼び出されたときのファイルの現在のサイズになります。flags は、マッピングの性質を指定します。
MAP_PRIVATE
はプライベートコピーオンライトマッピングを作成するため、mmapオブジェクトのコンテンツへの変更はこのプロセス専用になり、MAP_SHARED
はマッピングをマッピングする他のすべてのプロセスと共有されるマッピングを作成します。ファイルの同じ領域。 デフォルト値はMAP_SHARED
です。prot は、指定されている場合、必要なメモリ保護を提供します。 最も有用な2つの値は、
PROT_READ
とPROT_WRITE
で、ページの読み取りまたは書き込みを指定します。 prot のデフォルトはPROT_READ | PROT_WRITE
です。オプションのキーワードパラメータとして、 flags および prot の代わりに access を指定できます。 フラグ、 prot 、アクセスの両方を指定するとエラーになります。 このパラメーターの使用方法については、上記の access の説明を参照してください。
offset は、非負の整数オフセットとして指定できます。 mmap参照は、ファイルの先頭からのオフセットを基準にしています。 offset のデフォルトは0です。 offset は、
ALLOCATIONGRANULARITY
の倍数である必要があります。これは、UnixシステムのPAGESIZE
と同じです。作成されたメモリマッピングの有効性を確保するために、記述子 fileno で指定されたファイルは、macOSおよびOpenVMSの物理バッキングストアと内部的に自動的に同期されます。
この例は、 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 は、 with ステートメントのコンテキストマネージャーとしても使用できます。
import mmap with mmap.mmap(-1, 13) as mm: mm.write(b"Hello world!")
バージョン3.2の新機能:コンテキストマネージャーのサポート。
次の例は、匿名マップを作成し、親プロセスと子プロセスの間でデータを交換する方法を示しています。
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()
メモリマップトファイルオブジェクトは、次のメソッドをサポートしています。
- close()
mmapを閉じます。 その後、オブジェクトの他のメソッドを呼び出すと、ValueError例外が発生します。 これは開いているファイルを閉じません。
- closed
True
ファイルが閉じている場合。バージョン3.2の新機能。
- find(sub[, start[, end]])
sub が[ start 、 end の範囲に含まれるように、サブシーケンス sub が見つかったオブジェクトの最小インデックスを返します]。 オプションの引数 start および end は、スライス表記のように解釈されます。 失敗すると
-1
を返します。バージョン3.5で変更:書き込み可能なバイトのようなオブジェクトが受け入れられるようになりました。
- flush([offset[, size]])
ファイルのメモリ内コピーに加えられた変更をディスクにフラッシュします。 この呼び出しを使用しないと、オブジェクトが破棄される前に変更が書き戻される保証はありません。 offset および size が指定されている場合、指定されたバイト範囲への変更のみがディスクにフラッシュされます。 それ以外の場合は、マッピングの全範囲がフラッシュされます。 offset は、
PAGESIZE
またはALLOCATIONGRANULARITY
の倍数である必要があります。None
は、成功を示すために返されます。 呼び出しが失敗すると、例外が発生します。バージョン3.8で変更:以前は、成功するとゼロ以外の値が返されていました。 Windowsでエラーが発生すると、ゼロが返されました。 成功するとゼロ値が返されました。 Unixでのエラー時に例外が発生しました。
- madvise(option[, start[, length]])
start で始まり、 length バイトを拡張するメモリ領域について、カーネルにアドバイス option を送信します。 option は、システムで使用可能な MADV_ *定数の1つである必要があります。 start および length を省略すると、マッピング全体がスパンされます。 一部のシステム(Linuxを含む)では、 start は
PAGESIZE
の倍数である必要があります。可用性:
madvise()
システムコールを備えたシステム。バージョン3.8の新機能。
- move(dest, src, count)
オフセット src で始まる count バイトを宛先インデックス dest にコピーします。 mmapが
ACCESS_READ
で作成された場合、moveを呼び出すと、 TypeError 例外が発生します。
- read([n])
現在のファイル位置から最大 n バイトを含むバイトを返します。 引数が省略されている場合、
None
または負の場合、現在のファイル位置からマッピングの最後までのすべてのバイトを返します。 ファイルの位置は、返されたバイトの後を指すように更新されます。バージョン3.3で変更:引数は省略可能、または
None
。
- read_byte()
現在のファイル位置のバイトを整数として返し、ファイル位置を1つ進めます。
- readline()
現在のファイル位置から次の改行までの1行を返します。 ファイルの位置は、返されたバイトの後を指すように更新されます。
- resize(newsize)
マップと基になるファイル(存在する場合)のサイズを変更します。 mmapが
ACCESS_READ
またはACCESS_COPY
で作成された場合、マップのサイズを変更すると、 TypeError 例外が発生します。
- rfind(sub[, start[, end]])
sub が[ start 、 end の範囲に含まれるように、サブシーケンス sub が見つかったオブジェクトの最高のインデックスを返します]。 オプションの引数 start および end は、スライス表記のように解釈されます。 失敗すると
-1
を返します。バージョン3.5で変更:書き込み可能なバイトのようなオブジェクトが受け入れられるようになりました。
- seek(pos[, whence])
ファイルの現在位置を設定します。 whence 引数はオプションであり、デフォルトは
os.SEEK_SET
または0
(絶対ファイル配置)です。 他の値は、os.SEEK_CUR
または1
(現在の位置を基準にしてシーク)およびos.SEEK_END
または2
(ファイルの終わりを基準にしてシーク)です。
- size()
ファイルの長さを返します。これは、メモリマップ領域のサイズよりも大きくなる可能性があります。
- tell()
ファイルポインタの現在の位置を返します。
- write(bytes)
bytes のバイトをメモリのファイルポインタの現在の位置に書き込み、書き込まれたバイト数を返します(
len(bytes)
以上、書き込みが失敗した場合は ValueError が発生します)。 ファイルの位置は、書き込まれたバイトの後を指すように更新されます。 mmapがACCESS_READ
で作成された場合、mmapに書き込むと、 TypeError 例外が発生します。バージョン3.5で変更:書き込み可能なバイトのようなオブジェクトが受け入れられるようになりました。
バージョン3.6で変更:書き込まれたバイト数が返されるようになりました。
- write_byte(byte)
整数バイトをメモリのファイルポインタの現在の位置に書き込みます。 ファイルの位置は
1
だけ進みます。 mmapがACCESS_READ
で作成された場合、mmapに書き込むと、 TypeError 例外が発生します。
MADV_ *定数
- 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.madvise()に渡すことができます。 すべてのオプションがすべてのシステムに存在するわけではありません。
可用性:madvise()システムコールを備えたシステム。
バージョン3.8の新機能。