j2k-cuda 0.8.1

CUDA adapter for resident HTJ2K decode/encode and shared JPEG 2000 stages
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

// SPDX-License-Identifier: MIT OR Apache-2.0

use std::sync::Arc;

use j2k::{BatchDecodeOptions, BatchLayout, EncodedImage};
use j2k_cuda::{CudaBatchDecoder, CudaSession};
use j2k_cuda_runtime::CudaContext;

use super::support::submit_external_for_test;

#[test]
#[expect(
    clippy::too_many_lines,
    reason = "one soak scenario audits pool, transfer, event, synchronization, and output invariants together"
)]
fn resident_and_external_decode_pools_stabilize_for_one_thousand_batches_when_runtime_required() {
    if !j2k_test_support::cuda_runtime_gate(module_path!()) {
        return;
    }
    let fixture = j2k_test_support::openjph_batch_fixtures()
        .iter()
        .find(|fixture| fixture.name == "openjph-rgb-s12-53-single-raw")
        .expect("independent signed RGB12 single-tile fixture");
    let encoded = Arc::<[u8]>::from(fixture.encoded);
    let inputs = (0..8)
        .map(|_| EncodedImage::full(Arc::clone(&encoded)))
        .collect::<Vec<_>>();
    let context = CudaContext::system_default().expect("CUDA context");
    let session = CudaSession::with_context(context.clone());
    let options = BatchDecodeOptions {
        layout: BatchLayout::Nhwc,
        ..BatchDecodeOptions::default()
    };
    let mut decoder = CudaBatchDecoder::with_session_and_options(session, options);
    let prepared = decoder
        .prepare(inputs)
        .expect("prepare reusable RGB12 batch");
    let [group] = prepared.groups() else {
        panic!("expected one homogeneous signed RGB12 group")
    };
    let external_bytes = fixture
        .oracle
        .len()
        .checked_mul(8)
        .expect("external batch byte length");
    let mut external = context
        .allocate(external_bytes)
        .expect("persistent external destination");

    for _ in 0..16 {
        drop(
            decoder
                .decode_prepared(&prepared)
                .expect("warm persistent CUDA batch pools"),
        );
        // SAFETY: the allocation remains live and inaccessible until wait.
        unsafe { submit_external_for_test(&mut decoder, group, &context, &mut external) }
            .wait()
            .expect("warm persistent external CUDA batch pools");
    }
    let warm = decoder
        .diagnostics()
        .expect("warm CUDA session diagnostics");
    let warm_runtime = warm.runtime.expect("CUDA runtime must be initialized");
    let warm_batch = warm
        .pools
        .batch_decode
        .expect("dense batch decode pool must be initialized");
    assert_eq!(warm_batch.deferred_bytes, 0);
    assert_eq!(warm_batch.reuse_holds, 0);
    assert!(warm.pools.retained_bytes() > 0);

    for _ in 0..1_000 {
        drop(
            decoder
                .decode_prepared(&prepared)
                .expect("reuse prepared CUDA batch"),
        );
    }
    for _ in 0..1_000 {
        // SAFETY: the allocation remains live and inaccessible until wait.
        unsafe { submit_external_for_test(&mut decoder, group, &context, &mut external) }
            .wait()
            .expect("reuse external CUDA destination");
    }

    let after = decoder
        .diagnostics()
        .expect("post-soak CUDA session diagnostics");
    let after_runtime = after.runtime.expect("CUDA runtime remains initialized");
    let after_batch = after
        .pools
        .batch_decode
        .expect("batch pool remains initialized");
    assert_eq!(after_batch.deferred_bytes, 0);
    assert_eq!(after_batch.reuse_holds, 0);
    assert_eq!(after.pools.retained_bytes(), warm.pools.retained_bytes());
    assert_eq!(
        after.pools.peak_retained_bytes_upper_bound(),
        warm.pools.peak_retained_bytes_upper_bound()
    );
    assert_eq!(
        after_runtime.status_device_to_host_operations
            - warm_runtime.status_device_to_host_operations,
        2_000,
        "each resident/external group must use one status readback"
    );
    assert_eq!(
        after_runtime.device_to_host_operations - warm_runtime.device_to_host_operations,
        2_000,
        "the soak must not download decoded pixels"
    );
    assert_eq!(
        after_runtime.device_to_host_bytes - warm_runtime.device_to_host_bytes,
        after_runtime.status_device_to_host_bytes - warm_runtime.status_device_to_host_bytes,
        "all pre-verification D2H bytes must be the one small status transfer"
    );
    assert_eq!(
        after_runtime.event_driver_allocations, warm_runtime.event_driver_allocations,
        "completion events must stabilize after warmup"
    );
    assert!(after_runtime.event_reuses > warm_runtime.event_reuses);
    assert_eq!(
        after_runtime.event_host_synchronizations, warm_runtime.event_host_synchronizations,
        "the group status readback must replace a second final-store event wait"
    );
    assert_eq!(
        after_runtime.context_host_synchronizations, warm_runtime.context_host_synchronizations,
        "normal batch completion must not synchronize the whole context"
    );

    let mut actual = vec![0_u8; external_bytes];
    external
        .copy_to_host(&mut actual)
        .expect("download final external soak output");
    for image in actual.chunks_exact(fixture.oracle.len()) {
        assert_eq!(image, fixture.oracle);
    }
}