"mmap" --- メモリマップファイル
*******************************

======================================================================

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

メモリマップドファイルは Unix と Windows で異なる "mmap" コンストラク
タで生成されます。どちらの場合も、更新用に開かれたファイルディスクリプ
タを渡さなければなりません。既存の Python ファイルオブジェクトをマップ
したければ、 "fileno()" メソッドを使って *fileno* パラメータの正しい値
を取得してください。そうでなければ、 "os.open()" 関数を使ってファイル
を開けます。この関数はファイルディスクリプタを直接返します(処理が終わ
ったら、やはりファイルを閉じる必要があります)。

注釈:

  書き込み可能でバッファされたファイルへのメモリマップファイルを作りた
  いのであれば、まず最初にファイルの "flush()" を呼び出すべきです。こ
  れはバッファへのローカルな修正がマッピングで実際に利用可能になること
  を保障するために必要です。

For both the Unix and Windows versions of the constructor, *access*
may be specified as an optional keyword parameter. *access* accepts
one of four values: "ACCESS_READ", "ACCESS_WRITE", or "ACCESS_COPY" to
specify read-only, write-through or copy-on-write memory respectively,
or "ACCESS_DEFAULT" to defer to *prot*.  *access* can be used on both
Unix and Windows.  If *access* is not specified, Windows mmap returns
a write-through mapping.  The initial memory values for all three
access types are taken from the specified file.  Assignment to an
"ACCESS_READ" memory map raises a "TypeError" exception.  Assignment
to an "ACCESS_WRITE" memory map affects both memory and the underlying
file. Assignment to an "ACCESS_COPY" memory map affects memory but
does not update the underlying file.

バージョン 3.7 で変更: 定数 "ACCESS_DEFAULT" が追加されました。

無名メモリ(anonymous memory)にマップするためには fileno として -1 を渡
し、length を与えてください。

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

   **(Windows バージョン)** ファイルハンドル *fileno* によって指定され
   たファイルから *length* バイトをマップして、 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" はプライベートな
   copy-on-write(書込み時コピー)のマップを作成します。従って、mmap オ
   ブジェクトの内容への変更はこのプロセス内にのみ有効です。
   "MAP_SHARED" はファイルの同じ領域をマップする他のすべてのプロセスと
   共有されたマップを作成します。デフォルトは "MAP_SHARED" です。

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

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

   *offset* may be specified as a non-negative integer offset. mmap
   references will be relative to the offset from the beginning of the
   file. *offset* defaults to 0. *offset* must be a multiple of
   "ALLOCATIONGRANULARITY" which is equal to "PAGESIZE" on Unix
   systems.

   Mac OS X と OpenVMS において、作成された memory mapping の正当性を
   確実にするために *fileno* で指定されたファイルディスクリプタは内部
   で自動的に物理的なストレージ (physical backing store) と同期されま
   す。

   この例は "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()

      メモリマップファイルを閉じます。この呼出しの後にオブジェクトの他
      のメソッドの呼出すことは、 "ValueError" 例外の送出を引き起こしま
      す。このメソッドは開いたファイルのクローズはしません。

   closed

      ファイルが閉じている場合 "True" となります。

      バージョン 3.2 で追加.

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

      オブジェクト内の [*start*, *end*] の範囲に含まれている部分シーケ
      ンス *sub* が見つかった場所の最も小さいインデックスを返します。
      オプションの引数 *start* と *end* はスライスに使われるときのよう
      に解釈されます。失敗したときには "-1" を返します。

      バージョン 3.5 で変更: 書き込み可能な *bytes-like object* を使用
      できるようになりました。

   flush([offset[, size]])

      Flushes changes made to the in-memory copy of a file back to
      disk. Without use of this call there is no guarantee that
      changes are written back before the object is destroyed.  If
      *offset* and *size* are specified, only changes to the given
      range of bytes will be flushed to disk; otherwise, the whole
      extent of the mapping is flushed.  *offset* must be a multiple
      of the "PAGESIZE" or "ALLOCATIONGRANULARITY".

      **(Windows バージョン)** ゼロ以外の値が返されたら成功を、ゼロは
      失敗を意味します。

      **(Unix バージョン)** ゼロの値が返されたら成功を意味します。呼び
      出しが失敗すると例外が送出されます。

   move(dest, src, count)

      オフセット *src* から始まる *count* バイトをインデックス *dest*
      の位置へコピーします。もし mmap が "ACCESS_READ" で作成されてい
      た場合、 "TypeError" 例外を発生させます。

   read([n])

      現在のファイル位置からの最大 *n* バイトを含む "bytes" を返します
      。引数が省略されるか、 "None" もしくは負の値が指定された場合、現
      在のファイル位置からマップ終端までの全てのバイト列を返します。フ
      ァイル位置は返されたバイト列の直後を指すように更新されます。

      バージョン 3.3 で変更: 引数が省略可能になり、 "None" も受け付け
      るようになりました。

   read_byte()

      現在のファイル位置のバイトを整数値として返し、ファイル位置を 1
      進めます。

   readline()

      現在のファイル位置から次の改行までの、1行を返します。

   resize(newsize)

      マップと元ファイル(がもしあれば)のサイズを変更します。もし mmap
      が "ACCESS_READ" または "ACCESS_COPY" で作成されたならば、マップ
      サイズの変更は "TypeError" 例外を発生させます。

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

      オブジェクト内の [*start*, *end*] の範囲に含まれている部分シーケ
      ンス *sub* が見つかった場所の最も大きいインデックスを返します。
      オプションの引数 *start* と *end* はスライスに使われるときのよう
      に解釈されます。失敗したときには "-1" を返します。

      バージョン 3.5 で変更: 書き込み可能な *bytes-like object* を使用
      できるようになりました。

   seek(pos[, whence])

      ファイルの現在位置をセットします。 *whence* 引数はオプションであ
      り、デフォルトは "os.SEEK_SET" つまり "0" (絶対位置)です。その他
      の値として、 "os.SEEK_CUR" つまり "1" (現在位置からの相対位置)と
      "os.SEEK_END" つまり "2" (ファイルの終わりからの相対位置)があり
      ます。

   size()

      ファイルの長さを返します。メモリマップ領域のサイズより大きいかも
      しれません。

   tell()

      ファイルポインタの現在位置を返します。

   write(bytes)

      メモリ内のファイルポイントの現在位置に *bytes* のバイト列を書き
      込み、書き込まれたバイト数を返します(もし書き込みが失敗したら
      "ValueError" が送出されるため、"len(bytes)" より少なくなりません
      )。ファイル位置はバイト列が書き込まれた位置に更新されます。もし
      mmapが:const:*ACCESS_READ* とともに作成されていた場合は、書き込
      みは "TypeError" 例外を送出するでしょう。

      バージョン 3.5 で変更: 書き込み可能な *bytes-like object* を使用
      できるようになりました。

      バージョン 3.6 で変更: 書きこまれたバイト数を返すようになりまし
      た。

   write_byte(byte)

      メモリ内のファイル・ポインタの現在位置に整数 *byte* を書き込みま
      す。ファイル位置は "1" だけ進みます。もし mmap が "ACCESS_READ"
      で作成されていた場合、書き込み時に "TypeError" 例外を発生させる
      でしょう。
