\section{\module{mmap} ---
メモリマップファイル}

\declaremodule{builtin}{mmap}
\modulesynopsis{\UNIX\ とWindowsのメモリマップファイルへのインターフェース}

メモリにマップされたファイルオブジェクトは、
文字列とファイルオブジェクトの両方のように振舞います。
しかし通常の文字列オブジェクトとは異なり、これらは可変です。
文字列が期待されるほとんどの場所でmmapオブジェクトを利用できます。
例えば、メモリマップファイルを探索するために
\module{re}モジュールを使うことができます。
それらは可変なので、\ \code{obj[\var{index}] = 'a'}\ のように文字を
変換できますし、スライスを使うことで
\ \code{obj[\var{i1}:\var{i2}] = '...'}\ のように
部分文字列を変換することができます。
現在のファイル位置をデータの始めとする読込みや書込み、
ファイルの異なる位置へ\method{seek()}することもできます。

メモリマップファイルは\UNIX{}上とWindows上とでは異なる
\function{mmap()}関数によって作られます。
いずれの場合も、開いたファイルのディスクリプタを、
更新のために提供しなければなりません。
すでに存在するPythonファイルオブジェクトをマップしたい場合は、
\var{fileno}パラメータのための現在値を手に入れるために、
\method{fileno()}メソッドを使用して下さい。
そうでなければ、ファイル・ディスクリプタを直接返す\function{os.open()}関数
(呼び出すときにはまだファイルが閉じている必要があります)を使って、
ファイルを開くことができます。

関数の\UNIX{}バージョンとWindowsバージョンのために、
オプションのキーワード・パラメータとして\var{access}を指定する
ことになるかもしれません。
\var{access}は3つの値の内の1つを受け入れます。
\constant{ACCESS_READ}は読み込み専用、
\constant{ACCESS_WRITE}は書き込み可能、
\constant{ACCESS_COPY}はコピーした上での書き込みです。
\var{access}は\UNIX{}とWindowsの両方で使用することができます。
\var{access}が指定されない場合、Windowsのmmapは書き込み可能マップを返します。
3つのアクセス型すべてに対する初期メモリ値は、
指定されたファイルから得られます。
\constant{ACCESS_READ}を割り当てたメモリマップは
\exception{TypeError}例外を送出します。
\constant{ACCESS_WRITE}を割り当てたメモリマップは
メモリと元のファイルの両方に影響を与えます。
\constant{ACCESS_COPY}を割り当てたメモリマップは
メモリに影響を与えますが、元のファイルを更新することはありません。
\versionchanged[無名メモリ(anonymous memory)をマップするためにはfilenoとして
-1 を渡して長さを与えてください]{2.5}



\begin{funcdesc}{mmap}{fileno, length\optional{, tagname\optional{, access}}}
\strong{(Windows)}バージョンはファイルハンドル\var{fileno}によって
指定されたファイルから\var{length}バイトをマップして、
mmapオブジェクトを返します。
\var{length}が現在のファイルサイズより大きな場合、ファイルサイズは
\var{length}を含む大きさにまで拡張されます。
\var{length}が\code{0}の場合、マップの最大の長さは
Windowsが空ファイルで例外を起こす(Windowsでは空のマップを作成すること
ができません。)ことを除いては、
\function{mmap()}が呼ばれたときのファイルサイズになります。

\var{tagname}は、\code{None}以外で指定された場合、
マップのタグ名を与える文字列となります。
Windowsは同じファイルに対する様々なマップを持つことを可能にします。
既存のタグの名前を指定すればそのタグがオープンされ、
そうでなければこの名前の新しいタグが作成されます。
もしこのパラメータを省略したり\code{None}を与えたりしたならば、
マップは名前なしで作成されます。
タグ・パラメータの使用の回避は、あなたのコードを\UNIX{}とWindowsの間で
移植可能にしておくのを助けてくれるでしょう。
\end{funcdesc}

\begin{funcdescni}{mmap}{fileno, length\optional{, flags\optional{,
                         prot\optional{, access}}}}
\strong{(\UNIX{})}バージョンは、ファイル・ディスクリプタ \var{fileno}に
よって指定されたファイルから\var{length}バイトをマップし、
mmapオブジェクトを返します。\var{length}が\code{0}の場合、
そのマップの最大長が現在のファイルサイズになります。

\var{flags}はマップの種類を指定します。
\constant{MAP_PRIVATE}はプライベートなcopy-on-write(書込み時コピー)
のマップを作成します。
従って、mmapオブジェクトの内容への変更はこのプロセス内にのみ有効です。
\constant{MAP_SHARED}はファイルの同じ領域をマップする他のすべてのプロセス
と共有されたマップを作成します。
デフォルトは\constant{MAP_SHARED}です。

\var{prot}が指定された場合、希望のメモリ保護を与えます。
2つの最も有用な値は、\constant{PROT_READ}と\constant{PROT_WRITE}です。
これは、読込み可能または書込み可能を指定するものです。
\var{prot}のデフォルトは\constant{PROT_READ | PROT_WRITE}です。

\var{access}はオプションのキーワード・パラメータとして、
\var{flags}と\var{prot}の代わりに指定してもかまいません。
\var{flags},\var{prot}と\var{access}の両方を指定することは間違っています。
このパラメーターを使用法についての情報は、
\var{access}の記述を参照してください。
\end{funcdescni}


メモリマップフィイルオブジェクトは以下のメソッドをサポートしています:


\begin{methoddesc}[mmap]{close}{}
ファイルを閉じます。
この呼出しの後にオブジェクトの他のメソッドの呼出すことは、
例外の送出を引き起こすでしょう。
\end{methoddesc}

\begin{methoddesc}[mmap]{find}{string\optional{, start}}
オブジェクト内で部分文字列\var{string}が見つかった場所の最も小さい
インデックスを返します。
失敗したとき\code{-1}を返します。
\var{start}は探索を始めたい場所のインデックスで、デフォルトは0です。
\end{methoddesc}

\begin{methoddesc}[mmap]{flush}{\optional{offset, size}}
ファイルのメモリコピー内での変更をディスクへフラッシュします。
この呼出しを使わなかった場合、オブジェクトが破壊される前に
変更が書き込まれる保証はありません。
もし\var{offset}と\var{size}が指定された場合、与えられたバイトの範囲の
変更だけがディスクにフラッシュされます。
指定されない場合、マップ全体がフラッシュされます。
\end{methoddesc}

\begin{methoddesc}[mmap]{move}{\var{dest}, \var{src}, \var{count}}
オフセット\var{src}からインデックス\var{dest}へ\var{count}バイトだけ
コピーします。
もしmmapが\constant{ACCESS_READ}で作成されていた場合、
\exception{TypeError}例外を送出します。
\end{methoddesc}

\begin{methoddesc}[mmap]{read}{\var{num}}
現在のファイル位置から\var{num}バイトの文字列を返します。
ファイル位置は返したバイトの分だけ後ろの位置へ更新されます。
\end{methoddesc}

\begin{methoddesc}[mmap]{read_byte}{}
現在のファイル位置から長さ1の文字列を返します。
ファイル位置は1だけ進みます。
\end{methoddesc}

\begin{methoddesc}[mmap]{readline}{}
現在のファイル位置から次の新しい行までの、1行を返します。
\end{methoddesc}

\begin{methoddesc}[mmap]{resize}{\var{newsize}}
マップと元ファイルのサイズを変更します。
もしmmapが\constant{ACCESS_READ}または\constant{ACCESS_COPY}で
作成されたならば、マップのリサイズは\exception{TypeError}例外を送出します。
\end{methoddesc}

\begin{methoddesc}[mmap]{seek}{pos\optional{, whence}}
ファイルの現在位置をセットします。
\var{whence}引数はオプションであり、デフォルトは\code{0}(絶対位置)です。
その他の値として、\code{1}(現在位置からの相対位置)と
\code{2}(ファイルの終わりからの相対位置)があります。
\end{methoddesc}

\begin{methoddesc}[mmap]{size}{}
ファイルの長さを返します。
メモリマップ領域のサイズより大きいかもしれません。
\end{methoddesc}

\begin{methoddesc}[mmap]{tell}{}
ファイル・ポインタの現在位置を返します。
\end{methoddesc}

\begin{methoddesc}[mmap]{write}{\var{string}}
メモリ内のファイル・ポインタの現在位置から\var{string}のバイト列を
書き込みます。
ファイル位置はバイト列が書き込まれた後の位置へ更新されます。
もしmmapが\constant{ACCESS_READ}で作成されていた場合、
書き込み時に\exception{TypeError}例外が送出されるでしょう。
\end{methoddesc}

\begin{methoddesc}[mmap]{write_byte}{\var{byte}}
メモリ内のファイル・ポインタの現在位置から
単一文字の文字列\var{byte}を書き込みます。
ファイル位置は\code{1}だけ進みます。
もしmmapが\constant{ACCESS_READ}で作成されていた場合、
書き込み時に\exception{TypeError}例外が送出されるでしょう。
\end{methoddesc}
