Hiệu năng: trình phân tích phân mảnh bộ nhớ

Tổng quan nhanh

Mô-đun Performance có phạm vi hẹp. Nó cung cấp một công cụ chỉ quan sát là MemoryFragmentationAnalyzer, dùng để đo bộ nhớ đỉnh và bộ nhớ giữ lại trong các cửa sổ được đánh dấu khi engine hoạt động. Bề mặt công khai của mô-đun cũng bao gồm các ảnh chụp bất biến do công cụ tạo ra. Nó không áp đặt ngân sách, không điều tiết khối lượng công việc và không thay đổi hành vi của engine.

Phạm vi và độ ổn định. Bề mặt thực sự của mô-đun này là hai lớp (MemoryFragmentationAnalyzer, MemoryFragmentationSnapshot). Nó không phải là một bộ khung áp đặt ngân sách theo từng thao tác. Giá trị performance_budget trong frontmatter của mọi mô-đun là một quy ước tài liệu, không phải là giá trị mà mô-đun này áp đặt. Bề mặt này là experimental: nó là một công cụ chẩn đoán được giới thiệu ở @since 3.2.0. Cấu trúc ảnh chụp của nó có thể thay đổi theo thời gian.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Mức sử dụng tài nguyên là một mối quan tâm chất lượng hàng đầu đối với một engine Portable Document Format (PDF). Mức quan sát tối thiểu cần có là phân biệt giữa bộ nhớ đỉnh (mức cao nhất trong một cửa sổ) và bộ nhớ giữ lại (phần vẫn còn được giữ sau cửa sổ). Mô-đun này chỉ đo điều đó.

MemoryFragmentationAnalyzer chỉ quan sát; nó không thay đổi trạng thái của writer hay của tài liệu. reset() chạy một chu kỳ thu gom rác (GC) và đặt lại bộ đếm đỉnh của PHP để các phép đo tiếp theo thuộc về cửa sổ bắt đầu từ lần đặt lại đó. mark(string $label) ghi lại một MemoryFragmentationSnapshot tại một điểm có nhãn. snapshots() trả về dãy ảnh chụp đã ghi. peakDelta() và retainedDelta() báo cáo mức thay đổi bộ nhớ đỉnh và bộ nhớ giữ lại trong toàn bộ lần chạy.

MemoryFragmentationSnapshot là một đối tượng giá trị final readonly: đại diện cho một điểm có nhãn, kèm transientBytes() (đỉnh trừ đi giữ lại, tức là bộ nhớ đã được dùng rồi giải phóng), retentionRatio() (giữ lại trên đỉnh), và toArray() để xuất dữ liệu. Giá trị transient-bytes cao đi kèm tỷ lệ giữ lại thấp cho thấy sự xáo trộn mà một chiến lược tái sử dụng buffer có thể loại bỏ. Cả hai lớp đều là @since 3.2.0.

Bề mặt API

Lớp	Thành viên chính	Vai trò
MemoryFragmentationAnalyzer	reset(), mark(string $label), snapshots(), peakDelta(), retainedDelta()	Trình phân tích bộ nhớ chỉ để quan sát (@since 3.2.0)
MemoryFragmentationSnapshot	transientBytes(), retentionRatio(), toArray()	Phép đo bất biến có nhãn (@since 3.2.0)

Chạy composer docs:generate-api-php -- --module=Performance để tạo bảng PHPDoc đầy đủ.

Mẫu mã — bắt đầu nhanh

Gắn đo đạc vào một đường dẫn nóng, rồi đọc các giá trị delta.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Performance\MemoryFragmentationAnalyzer;

$analyzer = new MemoryFragmentationAnalyzer();
$analyzer->reset();

$analyzer->mark('before-write');
// ... engine work under observation ...
$analyzer->mark('after-write');

printf("Peak delta: %d B, retained delta: %d B\n", $analyzer->peakDelta(), $analyzer->retainedDelta());

Mẫu mã — sản xuất

Bao quanh một lần kết xuất và phát ảnh chụp phân mảnh tới một metrics sink. Xem tỷ lệ giữ lại thấp đi kèm số byte tạm thời cao là dấu hiệu xáo trộn.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Performance\MemoryFragmentationAnalyzer;
use Psr\Log\LoggerInterface;

final readonly class RenderMemoryProbe
{
    public function __construct(private LoggerInterface $logger) {}

    /** @param callable():void $render The render closure to observe. */
    public function observe(callable $render): void
    {
        $analyzer = new MemoryFragmentationAnalyzer();
        $analyzer->reset();

        $analyzer->mark('start');
        $render();
        $analyzer->mark('end');

        foreach ($analyzer->snapshots() as $snapshot) {
            $this->logger->info('mem-frag', $snapshot->toArray());
        }
    }
}

Trường hợp đặc biệt và lưu ý

• reset() gọi gc_collect_cycles() và memory_reset_peak_usage(). Nó ảnh hưởng đến bộ đếm đỉnh của PHP ở phạm vi toàn tiến trình. Đừng dùng xen kẽ nó với một thành phần khác cũng đọc cùng bộ đếm đó trong cùng một yêu cầu.
• Các phép đo thuộc về cửa sổ tính từ lần reset() gần nhất. Một mark() không có reset() đứng trước sẽ đo từ lúc tiến trình bắt đầu, thường không phải điều bạn muốn.
• Đây là công cụ chẩn đoán, không phải công cụ kiểm soát. Nó không bao giờ điều tiết hay hủy bỏ công việc. Đừng xây dựng cơ chế back pressure dựa trên nó.
• Hồ sơ khả năng tái lập là structural: các con số byte phụ thuộc vào runtime, allocator và trạng thái GC. Hai lần chạy có thể cho số liệu khác nhau ngay cả với cùng một khối lượng công việc về mặt logic.

Hiệu năng

Chi phí bổ sung của riêng trình phân tích là một chu kỳ thu gom rác tại reset() và một lần đọc hrtime() / memory_get_* cho mỗi mark(), là không đáng kể so với khối lượng công việc mà nó quan sát. Nó cấp phát một ảnh chụp nhỏ cho mỗi mark(). Giá trị performance_budget trong frontmatter này là con số tham chiếu chung cho toàn bộ tài liệu; mô-đun này không áp đặt nó.

Lưu ý về bảo mật

Các số liệu bộ nhớ là dữ liệu chẩn đoán. Chúng không chứa nội dung tài liệu, nhưng một hồ sơ bộ nhớ chi tiết có thể tiết lộ kích thước và dạng của đầu vào. Xem dữ liệu ảnh chụp được xuất ra là telemetry nội bộ, và áp dụng nghĩa vụ làm sạch nhật ký của dự án trước khi bạn chia sẻ ra bên ngoài. Mô-đun không thực hiện input/output (I/O) nào và không nhúng dữ liệu bên ngoài. Xem mô hình mối đe dọa của engine tại /modules/core/security/.

Tuân thủ

Mô-đun này không đưa ra tuyên bố quy chuẩn nào về đặc tả PDF. Nó là một công cụ chẩn đoán bộ nhớ và không triển khai giao thức tiêu chuẩn hóa nào có các điều khoản để trích dẫn. Lý do kiến trúc của nó tham chiếu đến góc nhìn chất lượng về sử dụng tài nguyên từ khung mô tả kiến trúc ISO/IEC/IEEE 42010. Tham chiếu đó là một sự liên kết với thực hành kiến trúc, không phải là một trích dẫn PDF. Mức độ tuân thủ của engine được xác thực bằng các bộ oracle và golden được mô tả trong /modules/core/conformance/.

Xem thêm

• Mô-đun Observability — bề mặt trạng thái lúc chạy rộng hơn.
• Mô-đun Telemetry — phát các metric tới một backend bên ngoài.
• Mô-đun Writer — một đối tượng phổ biến của việc quan sát bộ nhớ.
• Mô hình bảo mật của engine