mmap --- Hỗ trợ tập tin ánh xạ bộ nhớ

---

sẵn có: not WASI.

Mô-đun này không hoạt động hoặc không có trên WebAssembly. Xem Nền tảng WebAssugging để biết thêm thông tin.

Các đối tượng tệp được ánh xạ bộ nhớ hoạt động giống như cả bytearray và file objects. Bạn có thể sử dụng các đối tượng mmap ở hầu hết các nơi mong đợi bytearray; ví dụ: bạn có thể sử dụng mô-đun re để tìm kiếm thông qua tệp được ánh xạ bộ nhớ. Bạn cũng có thể thay đổi một byte đơn bằng cách thực hiện obj[index] = 97 hoặc thay đổi chuỗi con bằng cách gán cho một lát: obj[i1:i2] = b'...'. Bạn cũng có thể đọc và ghi dữ liệu bắt đầu từ vị trí tệp hiện tại và seek() thông qua tệp đến các vị trí khác nhau.

Tệp ánh xạ bộ nhớ được tạo bởi hàm tạo mmap, khác với trên Unix và trên Windows. Trong cả hai trường hợp, bạn phải cung cấp bộ mô tả tệp cho tệp được mở để cập nhật. Nếu bạn muốn ánh xạ một đối tượng tệp Python hiện có, hãy sử dụng phương thức fileno() của nó để lấy giá trị chính xác cho tham số fileno. Nếu không, bạn có thể mở tệp bằng hàm os.open(), hàm này trả về trực tiếp bộ mô tả tệp (tệp vẫn cần được đóng khi hoàn tất).

Ghi chú

Nếu bạn muốn tạo ánh xạ bộ nhớ cho một tệp đệm có thể ghi, trước tiên bạn nên flush() tệp đó. Điều này là cần thiết để đảm bảo rằng các sửa đổi cục bộ đối với bộ đệm thực sự có sẵn cho ánh xạ.

Đối với cả phiên bản Unix và Windows của hàm tạo, access có thể được chỉ định làm tham số từ khóa tùy chọn. access chấp nhận một trong bốn giá trị: ACCESS_READ, ACCESS_WRITE hoặc ACCESS_COPY để chỉ định bộ nhớ chỉ đọc, ghi qua hoặc sao chép khi ghi tương ứng hoặc ACCESS_DEFAULT để trì hoãn thành prot. access có thể được sử dụng trên cả Unix và Windows. Nếu access không được chỉ định, Windows mmap sẽ trả về ánh xạ ghi qua. Các giá trị bộ nhớ ban đầu cho cả ba loại truy cập được lấy từ tệp được chỉ định. Việc gán cho bản đồ bộ nhớ ACCESS_READ sẽ tạo ra ngoại lệ TypeError. Việc gán cho bản đồ bộ nhớ ACCESS_WRITE ảnh hưởng đến cả bộ nhớ và tệp cơ bản. Việc gán cho bản đồ bộ nhớ ACCESS_COPY ảnh hưởng đến bộ nhớ nhưng không cập nhật tệp cơ bản.

Thay đổi trong phiên bản 3.7: Đã thêm hằng số ACCESS_DEFAULT.

Để ánh xạ bộ nhớ ẩn danh, -1 phải được chuyển dưới dạng fileno cùng với độ dài.

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

(Windows version) Bản đồ các byte length từ tệp được chỉ định bởi tệp xử lý fileno và tạo đối tượng mmap. Nếu length lớn hơn kích thước hiện tại của tệp, tệp sẽ được mở rộng để chứa byte length. Nếu length là 0, độ dài tối đa của bản đồ là kích thước hiện tại của tệp, ngoại trừ nếu tệp trống thì Windows sẽ đưa ra một ngoại lệ (bạn không thể tạo ánh xạ trống trên Windows).

tagname, nếu được chỉ định chứ không phải None, là một chuỗi cung cấp tên thẻ cho ánh xạ. Windows cho phép bạn có nhiều ánh xạ khác nhau trên cùng một tệp. Nếu bạn chỉ định tên của thẻ hiện có, thẻ đó sẽ được mở, nếu không, thẻ mới có tên này sẽ được tạo. Nếu tham số này bị bỏ qua hoặc None, ánh xạ sẽ được tạo mà không có tên. Việc tránh sử dụng tham số tagname sẽ giúp giữ cho mã của bạn có thể di chuyển giữa Unix và Windows.

offset có thể được chỉ định làm phần bù số nguyên không âm. tham chiếu mmap sẽ liên quan đến phần bù từ đầu tệp. offset mặc định là 0. offset phải là bội số của ALLOCATIONGRANULARITY.

Tăng một auditing event mmap.__new__ với các đối số fileno, length, access, offset.

class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE | PROT_READ, access=ACCESS_DEFAULT, offset=0, *, trackfd=True)

(Unix version) Ánh xạ các byte length từ tệp được chỉ định bởi bộ mô tả tệp fileno và trả về một đối tượng mmap. Nếu length là 0, độ dài tối đa của bản đồ sẽ là kích thước hiện tại của tệp khi mmap được gọi.

flags chỉ định bản chất của ánh xạ. MAP_PRIVATE tạo một ánh xạ sao chép khi ghi riêng tư, do đó các thay đổi đối với nội dung của đối tượng mmap sẽ ở chế độ riêng tư đối với quy trình này và MAP_SHARED tạo một ánh xạ được chia sẻ với tất cả các quy trình khác ánh xạ các khu vực giống nhau của tệp. Giá trị mặc định là MAP_SHARED. Một số hệ thống có thêm các cờ có thể có với danh sách đầy đủ được chỉ định trong MAP_* constants.

prot, nếu được chỉ định, sẽ cung cấp khả năng bảo vệ bộ nhớ mong muốn; hai giá trị hữu ích nhất là PROT_READ và PROT_WRITE, để chỉ định rằng các trang có thể được đọc hoặc ghi. prot mặc định là PROT_READ | PROT_WRITE.

access có thể được chỉ định thay cho flags và prot làm tham số từ khóa tùy chọn. Sẽ có lỗi khi chỉ định cả flags, prot và access. Xem mô tả của access ở trên để biết thông tin về cách sử dụng tham số này.

offset có thể được chỉ định làm phần bù số nguyên không âm. tham chiếu mmap sẽ liên quan đến phần bù từ đầu tệp. offset mặc định là 0. offset phải là bội số của ALLOCATIONGRANULARITY, bằng PAGESIZE trên hệ thống Unix.

Nếu trackfd là False, bộ mô tả tệp được chỉ định bởi fileno sẽ không bị trùng lặp và đối tượng mmap thu được sẽ không được liên kết với tệp cơ bản của bản đồ. Điều này có nghĩa là phương thức size() và resize() sẽ thất bại. Chế độ này hữu ích để giới hạn số lượng bộ mô tả tệp đang mở.

Để đảm bảo tính hợp lệ của ánh xạ bộ nhớ đã tạo, tệp được chỉ định bởi bộ mô tả fileno sẽ được tự động đồng bộ hóa nội bộ với kho lưu trữ sao lưu vật lý trên macOS.

Thay đổi trong phiên bản 3.13: Tham số trackfd đã được thêm vào.

Ví dụ này cho thấy cách sử dụng mmap đơn giản:

nhập mmap

# write một tệp ví dụ đơn giản
với open("hello.txt", "wb") là f:
    f.write(b"Xin chào Python!\n")

với open("hello.txt", "r+b") là f:
    # memory-map tệp, kích thước 0 có nghĩa là toàn bộ tệp
    mm = mmap.mmap(f.fileno(), 0)
    nội dung # read thông qua các phương thức tệp tiêu chuẩn
    print(mm.readline()) # prints b"Xin chào Python!\n"
    nội dung # read thông qua ký hiệu lát cắt
    print(mm[:5]) # prints b"Xin chào"
    nội dung # update sử dụng ký hiệu lát cắt;
    # note rằng nội dung mới phải có cùng kích thước
    mm[6:] = b" thế giới!\n"
    # ... và đọc lại bằng các phương thức tệp tiêu chuẩn
    mm.seek(0)
    print(mm.readline()) # prints b"Xin chào thế giới!\n"
    # close bản đồ
    mm.close()

mmap cũng có thể được sử dụng làm trình quản lý bối cảnh trong câu lệnh with

nhập mmap

với mmap.mmap(-1, 13) là mm:
    mm.write(b"Xin chào thế giới!")

Added in version 3.2: Hỗ trợ quản lý bối cảnh.

Ví dụ tiếp theo trình bày cách tạo bản đồ ẩn danh và trao đổi dữ liệu giữa tiến trình cha và con:

nhập mmap
hệ điều hành nhập khẩu

mm = mmap.mmap(-1, 13)
mm.write(b"Xin chào thế giới!")

pid = os.fork()

if pid == 0: # In một tiến trình con
    mm.seek(0)
    in(mm.readline())

    mm.close()

Tăng một auditing event mmap.__new__ với các đối số fileno, length, access, offset.

Các đối tượng tệp được ánh xạ bộ nhớ hỗ trợ các phương thức sau:

close()

Đóng mmap. Các cuộc gọi tiếp theo đến các phương thức khác của đối tượng sẽ dẫn đến ngoại lệ ValueError được đưa ra. Điều này sẽ không đóng tập tin đang mở.

closed

True nếu tập tin bị đóng.

Added in version 3.2.

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

Trả về chỉ mục thấp nhất trong đối tượng nơi tìm thấy dãy con sub, sao cho sub được chứa trong phạm vi [start, end]. Các đối số tùy chọn start và end được hiểu là trong ký hiệu lát cắt. Trả về -1 khi thất bại.

Thay đổi trong phiên bản 3.5: bytes-like object có thể ghi hiện đã được chấp nhận.

flush()

flush(offset, size, /)

Xóa các thay đổi được thực hiện đối với bản sao trong bộ nhớ của tệp trở lại đĩa. Nếu không sử dụng lệnh gọi này thì không có gì đảm bảo rằng các thay đổi sẽ được ghi lại trước khi đối tượng bị hủy. Nếu offset và size được chỉ định, chỉ những thay đổi đối với phạm vi byte nhất định mới được xóa vào đĩa; mặt khác, toàn bộ phạm vi ánh xạ sẽ bị xóa. offset phải là bội số của PAGESIZE hoặc ALLOCATIONGRANULARITY.

None được trả về để biểu thị thành công. Một ngoại lệ được đưa ra khi cuộc gọi không thành công.

Thay đổi trong phiên bản 3.8: Trước đây, giá trị khác 0 được trả về nếu thành công; số 0 được trả về do lỗi trong Windows. Giá trị 0 được trả về khi thành công; một ngoại lệ đã được đưa ra do lỗi trong Unix.

madvise(option[, start[, length]])

Gửi lời khuyên option tới kernel về vùng bộ nhớ bắt đầu từ start và mở rộng byte length. option phải là một trong những MADV_* constants có sẵn trên hệ thống. Nếu start và length bị bỏ qua, toàn bộ ánh xạ sẽ được kéo dài. Trên một số hệ thống (bao gồm cả Linux), start phải là bội số của PAGESIZE.

Tính khả dụng: Các hệ thống có lệnh gọi hệ thống madvise().

Added in version 3.8.

move(dest, src, count)

Sao chép các byte count bắt đầu từ offset src tới chỉ mục đích dest. Nếu mmap được tạo bằng ACCESS_READ thì lệnh gọi di chuyển sẽ đưa ra ngoại lệ TypeError.

read([n])

Trả về bytes chứa tối đa n byte bắt đầu từ vị trí tệp hiện tại. Nếu đối số bị bỏ qua, None hoặc âm, hãy trả về tất cả byte từ vị trí tệp hiện tại đến cuối ánh xạ. Vị trí tệp được cập nhật để trỏ sau byte được trả về.

Thay đổi trong phiên bản 3.3: Đối số có thể được bỏ qua hoặc None.

read_byte()

Trả về một byte ở vị trí tệp hiện tại dưới dạng số nguyên và tăng vị trí tệp lên 1.

readline()

Trả về một dòng duy nhất, bắt đầu từ vị trí tệp hiện tại cho đến dòng mới tiếp theo. Vị trí tệp được cập nhật để trỏ sau byte được trả về.

resize(newsize)

Thay đổi kích thước bản đồ và tệp cơ bản, nếu có.

Thay đổi kích thước bản đồ được tạo bằng access của ACCESS_READ hoặc ACCESS_COPY, sẽ tạo ra ngoại lệ TypeError. Việc thay đổi kích thước bản đồ được tạo bằng trackfd được đặt thành False sẽ tạo ra ngoại lệ ValueError.

On Windows: Thay đổi kích thước bản đồ sẽ tăng OSError nếu có các bản đồ khác đối với cùng một tệp có tên. Thay đổi kích thước bản đồ ẩn danh (tức là so với tệp trang) sẽ âm thầm tạo một bản đồ mới với dữ liệu gốc được sao chép theo chiều dài của kích thước mới.

Thay đổi trong phiên bản 3.11: Không thành công nếu cố gắng thay đổi kích thước khi bản đồ khác được giữ Cho phép thay đổi kích thước đối với bản đồ ẩn danh trên Windows

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

Trả về chỉ số cao nhất trong đối tượng nơi tìm thấy dãy con sub, sao cho sub được chứa trong phạm vi [start, end]. Các đối số tùy chọn start và end được hiểu là trong ký hiệu lát cắt. Trả về -1 khi thất bại.

Thay đổi trong phiên bản 3.5: bytes-like object có thể ghi hiện đã được chấp nhận.

seek(pos[, whence])

Đặt vị trí hiện tại của tập tin. đối số whence là tùy chọn và mặc định là os.SEEK_SET hoặc 0 (định vị tệp tuyệt đối); các giá trị khác là os.SEEK_CUR hoặc 1 (tìm kiếm liên quan đến vị trí hiện tại) và os.SEEK_END hoặc 2 (tìm kiếm liên quan đến phần cuối của tệp).

Thay đổi trong phiên bản 3.13: Trả về vị trí tuyệt đối mới thay vì None.

seekable()

Trả về xem tệp có hỗ trợ tìm kiếm hay không và giá trị trả về luôn là True.

Added in version 3.13.

size()

Trả về độ dài của tệp, có thể lớn hơn kích thước của vùng ánh xạ bộ nhớ.

tell()

Trả về vị trí hiện tại của con trỏ tập tin.

write(bytes)

Ghi các byte trong bytes vào bộ nhớ tại vị trí hiện tại của con trỏ tệp và trả về số byte đã ghi (không bao giờ nhỏ hơn len(bytes), vì nếu ghi thất bại, ValueError sẽ được nâng lên). Vị trí tệp được cập nhật để trỏ sau byte được ghi. Nếu mmap được tạo bằng ACCESS_READ thì việc ghi vào nó sẽ tạo ra ngoại lệ TypeError.

Thay đổi trong phiên bản 3.5: bytes-like object có thể ghi hiện đã được chấp nhận.

Thay đổi trong phiên bản 3.6: Số byte được ghi bây giờ được trả về.

write_byte(byte)

Ghi số nguyên byte vào bộ nhớ tại vị trí hiện tại của con trỏ tệp; vị trí tập tin được nâng cao bởi 1. Nếu mmap được tạo bằng ACCESS_READ thì việc ghi vào nó sẽ tạo ra ngoại lệ TypeError.

MADV_* Hằng số

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.MADV_FREE_REUSABLE

mmap.MADV_FREE_REUSE

Các tùy chọn này có thể được chuyển tới mmap.madvise(). Không phải mọi tùy chọn sẽ có mặt trên mọi hệ thống.

Tính khả dụng: Các hệ thống có lệnh gọi hệ thống madvise().

Added in version 3.8.

MAP_* Hằng số

mmap.MAP_SHARED

mmap.MAP_PRIVATE

mmap.MAP_32BIT

mmap.MAP_ALIGNED_SUPER

mmap.MAP_ANON

mmap.MAP_ANONYMOUS

mmap.MAP_CONCEAL

mmap.MAP_DENYWRITE

mmap.MAP_EXECUTABLE

mmap.MAP_HASSEMAPHORE

mmap.MAP_JIT

mmap.MAP_NOCACHE

mmap.MAP_NOEXTEND

mmap.MAP_NORESERVE

mmap.MAP_POPULATE

mmap.MAP_RESILIENT_CODESIGN

mmap.MAP_RESILIENT_MEDIA

mmap.MAP_STACK

mmap.MAP_TPRO

mmap.MAP_TRANSLATED_ALLOW_EXECUTE

mmap.MAP_UNIX03

Đây là những cờ khác nhau có thể được chuyển tới mmap.mmap(). MAP_ALIGNED_SUPER chỉ có tại FreeBSD và MAP_CONCEAL chỉ có tại OpenBSD. Lưu ý rằng một số tùy chọn có thể không có trên một số hệ thống.

Thay đổi trong phiên bản 3.10: Đã thêm hằng số MAP_POPULATE.

Added in version 3.11: Đã thêm hằng số MAP_STACK.

Added in version 3.12: Đã thêm hằng số MAP_ALIGNED_SUPER và MAP_CONCEAL.

Added in version 3.13: Đã thêm các hằng số MAP_32BIT, MAP_HASSEMAPHORE, MAP_JIT, MAP_NOCACHE, MAP_NOEXTEND, MAP_NORESERVE, MAP_RESILIENT_CODESIGN, MAP_RESILIENT_MEDIA, MAP_TPRO, MAP_TRANSLATED_ALLOW_EXECUTE và MAP_UNIX03.