Skip to content

mmap.rst

Latest commit

 

History

History
491 lines (357 loc) · 18.1 KB

mmap.rst

File metadata and controls

491 lines (357 loc) · 18.1 KB

:mod:`!mmap` --- Memory-mapped file support

.. module:: mmap
   :synopsis: Interface to memory-mapped files for Unix and Windows.

Memory-mapped file objects behave like both :class:`bytearray` and like :term:`file objects <file object>`. You can use mmap objects in most places where :class:`bytearray` are expected; for example, you can use the :mod:`re` module to search through a memory-mapped file. You can also change a single byte by doing obj[index] = 97, or change a subsequence by assigning to a slice: obj[i1:i2] = b'...'. You can also read and write data starting at the current file position, and :meth:`seek` through the file to different positions.

A memory-mapped file is created by the :class:`~mmap.mmap` constructor, which is different on Unix and on Windows. In either case you must provide a file descriptor for a file opened for update. If you wish to map an existing Python file object, use its :meth:`~io.IOBase.fileno` method to obtain the correct value for the fileno parameter. Otherwise, you can open the file using the :func:`os.open` function, which returns a file descriptor directly (the file still needs to be closed when done).

Note

If you want to create a memory-mapping for a writable, buffered file, you should :func:`~io.IOBase.flush` the file first. This is necessary to ensure that local modifications to the buffers are actually available to the mapping.

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: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to specify read-only, write-through or copy-on-write memory respectively, or :const:`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 :const:`ACCESS_READ` memory map raises a :exc:`TypeError` exception. Assignment to an :const:`ACCESS_WRITE` memory map affects both memory and the underlying file. Assignment to an :const:`ACCESS_COPY` memory map affects memory but does not update the underlying file.

.. versionchanged:: 3.7
   Added :const:`ACCESS_DEFAULT` constant.

To map anonymous memory, -1 should be passed as the fileno along with the length.

MADV_* Constants

.. data:: MADV_NORMAL
          MADV_RANDOM
          MADV_SEQUENTIAL
          MADV_WILLNEED
          MADV_DONTNEED
          MADV_REMOVE
          MADV_DONTFORK
          MADV_DOFORK
          MADV_HWPOISON
          MADV_MERGEABLE
          MADV_UNMERGEABLE
          MADV_SOFT_OFFLINE
          MADV_HUGEPAGE
          MADV_NOHUGEPAGE
          MADV_DONTDUMP
          MADV_DODUMP
          MADV_FREE
          MADV_NOSYNC
          MADV_AUTOSYNC
          MADV_NOCORE
          MADV_CORE
          MADV_PROTECT
          MADV_FREE_REUSABLE
          MADV_FREE_REUSE

   These options can be passed to :meth:`mmap.madvise`.  Not every option will
   be present on every system.

   Availability: Systems with the madvise() system call.

   .. versionadded:: 3.8

MAP_* Constants

.. data:: MAP_SHARED
          MAP_PRIVATE
          MAP_32BIT
          MAP_ALIGNED_SUPER
          MAP_ANON
          MAP_ANONYMOUS
          MAP_CONCEAL
          MAP_DENYWRITE
          MAP_EXECUTABLE
          MAP_HASSEMAPHORE
          MAP_JIT
          MAP_NOCACHE
          MAP_NOEXTEND
          MAP_NORESERVE
          MAP_POPULATE
          MAP_RESILIENT_CODESIGN
          MAP_RESILIENT_MEDIA
          MAP_STACK
          MAP_TPRO
          MAP_TRANSLATED_ALLOW_EXECUTE
          MAP_UNIX03

    These are the various flags that can be passed to :meth:`mmap.mmap`.  :data:`MAP_ALIGNED_SUPER`
    is only available at FreeBSD and :data:`MAP_CONCEAL` is only available at OpenBSD.  Note
    that some options might not be present on some systems.

    .. versionchanged:: 3.10
       Added :data:`MAP_POPULATE` constant.

    .. versionadded:: 3.11
       Added :data:`MAP_STACK` constant.

    .. versionadded:: 3.12
       Added :data:`MAP_ALIGNED_SUPER` and :data:`MAP_CONCEAL` constants.

    .. versionadded:: 3.13
       Added :data:`MAP_32BIT`, :data:`MAP_HASSEMAPHORE`, :data:`MAP_JIT`,
       :data:`MAP_NOCACHE`, :data:`MAP_NOEXTEND`, :data:`MAP_NORESERVE`,
       :data:`MAP_RESILIENT_CODESIGN`, :data:`MAP_RESILIENT_MEDIA`,
       :data:`MAP_TPRO`, :data:`MAP_TRANSLATED_ALLOW_EXECUTE`, and
       :data:`MAP_UNIX03` constants.

MS_* Constants

.. data:: MS_SYNC
          MS_ASYNC
          MS_INVALIDATE

    These flags control the synchronization behavior for :meth:`mmap.flush`:

    * :data:`MS_SYNC` - Synchronous flush: writes are scheduled and the call
      blocks until they are physically written to storage.
    * :data:`MS_ASYNC` - Asynchronous flush: writes are scheduled but the call
      returns immediately without waiting for completion.
    * :data:`MS_INVALIDATE` - Invalidate cached data: invalidates other mappings
      of the same file so they can see the changes.

    .. versionadded:: 3.15