@reekon-tools/react-native-pdf-canvas 0.1.0 → 0.2.0

package/ios/Sources/PdfCanvasSlots/include/PdfCanvasSlots.h

@@ -1,140 +0,0 @@
-#import <Foundation/Foundation.h>
-
-#import <PdfCanvasPixelSink.h>
-
-NS_ASSUME_NONNULL_BEGIN
-
-/**
- * The raster transport: CoreGraphics writes a tile, and JS gets an `ArrayBuffer`
- * over those exact bytes with no base64 and no copy anywhere.
- *
- * ------------------------------------------------------------------------
- * WHY THIS FILE EXISTS
- * ------------------------------------------------------------------------
- *
- * Neither the legacy bridge nor new-architecture codegen has a binary type, and
- * that is not an Android quirk — MEASURED on iOS by reading RN 0.86.2's own
- * source: `TurboModuleConvertUtils::convertObjCObjectToJSIValue` handles
- * `NSString`, `NSNumber`, `NSDictionary`, `NSArray` and `kCFNull`, and returns
- * `jsi::Value::undefined()` for anything else. An `NSData` in a resolved promise
- * arrives in JS as `undefined`.
- *
- * So the fallback is base64, exactly as on Android, and the cost is the same
- * cliff: the Android measurement for one 1024x1024 tile was 19.88 ms to encode,
- * ~72.6 ms of string marshalling and 1005.46 ms of `decodeBase64` in Hermes —
- * 90.6% of the tile, spent undoing an encode that finished a moment earlier. iOS
- * runs the same Hermes.
- *
- * ------------------------------------------------------------------------
- * HOW MANY COPIES: ZERO, AND THAT IS BETTER THAN ANDROID CAN DO
- * ------------------------------------------------------------------------
- *
- * Android's fast path costs ONE full-raster `memcpy` and cannot do better: a
- * `Bitmap` owns its own pixel memory, `PdfRenderer.render` writes into that, and
- * `nativeStoreFromBitmap`'s job is to copy it out. There is no way to tell
- * `PdfRenderer` where to put the pixels.
- *
- * `CGBitmapContextCreate` takes the destination pointer as an argument. So
- * `PdfCanvasSlotSink` reserves a buffer HERE, `PdfCanvasRasterizer` hands that
- * pointer to CoreGraphics, and the tile is written once, in place. Then
- * `__pdfCanvasTakePixels` hands the buffer to
- * `jsi::ArrayBuffer(runtime, shared_ptr<MutableBuffer>)`: Hermes retains the
- * `shared_ptr` and points the ArrayBuffer's storage AT it. Still no copy.
- *
- * ------------------------------------------------------------------------
- * RESERVE, FILL, PUBLISH — in that order, and the order is the safety property
- * ------------------------------------------------------------------------
- *
- * A buffer reachable from the process-wide slot map BEFORE it is filled can be
- * freed by `PdfCanvasSlotsReleaseAll` — which runs on another thread, on every
- * Fast Refresh — while a render worker is still writing into it. The Android JSI
- * file describes that outcome exactly: "silent heap corruption, weeks from the
- * change that caused it". So a reserved buffer is owned by its sink object alone,
- * on the rendering thread's stack, and becomes reachable only at publish.
- *
- * ------------------------------------------------------------------------
- * WHO FREES IT
- * ------------------------------------------------------------------------
- *
- * The slot map drops its reference the instant a take succeeds, so from that
- * moment the only owner is the JS `ArrayBuffer` and the buffer dies when Hermes
- * collects it. A slot that is stored and never taken — a JS teardown between the
- * promise resolving and its continuation running — is freed by
- * `PdfCanvasSlotsReleaseAll`, which `PdfCanvasModule.invalidate` calls.
- */
-
-/**
- * A `PdfCanvasPixelSink` that reserves C++-owned memory and publishes it under a
- * fresh slot id.
- *
- * The id comes from a PROCESS-WIDE counter, not from the caller, which closes a
- * hazard Android has to guard against by hand: its slot ids are allocated by the
- * module and the C++ side has to REFUSE a collision, because RN builds a fresh set
- * of native modules on every reload while the outgoing one may still have rasters
- * parked. Allocating the id at reserve time, next to the map it goes into, makes a
- * collision unrepresentable — so `pdfCanvasPublish` cannot fail, and the whole
- * "publish refused after the raster was already drawn" path does not exist here.
- */
-@interface PdfCanvasSlotSink : NSObject <PdfCanvasPixelSink>
-@end
-
-/**
- * The self-test payload, mirroring `TRANSPORT_PROBE_BYTES` in
- * `src/rasterizer/native-bridge.ts` and `PdfCanvasPixelBridge.PROBE_BYTES` on
- * Android.
- *
- * The three lists are restated rather than derived, which is the point: they are
- * the only places the transport's byte fidelity is asserted, and if one is edited
- * without the others the probe fails and that platform degrades to base64 rather
- * than shipping a shear.
- */
-FOUNDATION_EXPORT NSData *PdfCanvasSlotsProbeBytes(void);
-
-/**
- * Parks the probe bytes in a fresh slot and returns its id.
- *
- * What the probe covers: that the runtime accepted the host function, that Hermes
- * will build an `ArrayBuffer` over a `MutableBuffer`, and that byte values survive
- * the view unmangled. What it does NOT cover is the FILL every subsequent raster
- * uses — that is CoreGraphics writing into a reserved buffer, and it is covered by
- * `SinkTests.swift` on the host instead. Worth knowing when reading a bug report:
- * a passing probe says nothing about the fill.
- */
-FOUNDATION_EXPORT int64_t PdfCanvasSlotsStoreProbe(void);
-
-/**
- * Installs `globalThis.__pdfCanvasTakePixels` into a JSI runtime.
- *
- * MUST be called on the JS thread with a live runtime pointer. Returns NO — never
- * throws — when the pointer is null or the runtime refuses the host function. The
- * JS side then falls back to base64: rendering correctly is worth more than
- * rendering fast.
- *
- * @param runtimePointer a `facebook::jsi::Runtime *`, as an opaque pointer so this
- *     header stays importable from plain Objective-C. NULLABLE, and checked: the
- *     bridge genuinely can hand over nothing, and this file is enclosed in
- *     `NS_ASSUME_NONNULL_BEGIN`, so leaving it implicitly non-null would make Swift
- *     unable to express the case the implementation handles.
- */
-FOUNDATION_EXPORT BOOL PdfCanvasSlotsInstall(void *_Nullable runtimePointer);
-
-/** Drops one slot if it is still there. Idempotent. */
-FOUNDATION_EXPORT void PdfCanvasSlotsRelease(int64_t slot);
-
-/** Drops every slot. Called from `PdfCanvasModule.invalidate`. */
-FOUNDATION_EXPORT void PdfCanvasSlotsReleaseAll(void);
-
-/** Slots currently waiting to be taken. For assertions and diagnostics, not logic. */
-FOUNDATION_EXPORT NSInteger PdfCanvasSlotsCount(void);
-
-/**
- * Takes a slot back out as an `NSData`, through the identical storage the
- * `ArrayBuffer` would have wrapped.
- *
- * The only way to check the transport without a JS runtime, which is why it ships
- * rather than living in a test target: the storage under test is the production
- * one. Nil when the slot is empty.
- */
-FOUNDATION_EXPORT NSData *_Nullable PdfCanvasSlotsTakeForTest(int64_t slot);
-
-NS_ASSUME_NONNULL_END

package/ios/Tests/PdfCanvasCoreTests/ConcurrencyTests.swift

@@ -1,358 +0,0 @@
-import Foundation
-import XCTest
-
-@testable import PdfCanvasCore
-
-/**
- Cancellation, the pool, and what happens when a document is closed under a render.
-
- None of these produce a wrong pixel. They produce a leaked lane that starves every
- later render, a freed document a worker is still drawing from, or a superseded
- raster that gets ingested into Skia anyway — so each one is worth a test even
- though none of them is visible in an image.
- */
-final class ConcurrencyTests: XCTestCase {
-
-  private func grid(_ name: String, poolSize: Int = 1) throws -> PdfCanvasRasterizer {
-    try openFixture(
-      TestPdfs.grid(width: 600, height: 800), name: name, poolSize: poolSize)
-  }
-
-  // ---------------------------------------------------------------- //
-  // Cancellation
-  // ---------------------------------------------------------------- //
-
-  /**
-   A cancel before the render starts stops it, and says so by stage.
-
-   The stage is in the message on purpose: a cancellation reported "before start"
-   saved the whole render, and one reported "after render" saved only the ingest.
-   Those are very different amounts of work and a bug report should not have to
-   guess which happened.
-   */
-  func testACancelBeforeStartStopsTheRender() throws {
-    let r = try grid("cancel-before.pdf")
-    let signal = PdfCanvasCancellation()
-    signal.cancel()
-    XCTAssertTrue(signal.isCancelled)
-    XCTAssertThrowsError(
-      try r.render(
-        request(width: 600, height: 800, scale: 2), cancellation: signal, sink: nil)
-    ) { error in
-      XCTAssertEqual(PdfCanvasErrorCodeOf(error as NSError), .cancelled)
-      XCTAssertTrue(
-        (error as NSError).localizedDescription.contains("before start"),
-        (error as NSError).localizedDescription)
-    }
-    r.close()
-  }
-
-  /// A signal that is never cancelled does not interfere.
-  func testAnUncancelledSignalIsTransparent() throws {
-    let r = try grid("cancel-none.pdf")
-    let signal = PdfCanvasCancellation()
-    let raster = try r.render(
-      request(width: 100, height: 100, scale: 1), cancellation: signal, sink: nil)
-    XCTAssertEqual(raster.width, 100)
-    XCTAssertFalse(signal.isCancelled)
-    r.close()
-  }
-
-  /**
-   A cancel that lands while a render is IN FLIGHT is observed only after it
-   finishes.
-
-   `CGContextDrawPDFPage` is synchronous and uninterruptible once entered, and this
-   test asserts that shape rather than pretending otherwise — it is the same honest
-   claim `RasterCancellation.java` makes and the reason
-   `capabilities.interruptibleRender` is false. What the cancel DOES buy is that the
-   finished raster is not handed back, which saves the Skia ingest on the JS side.
-
-   The render is made large enough to still be running when the cancel fires, and
-   the assertion tolerates either outcome for exactly one reason: on a fast machine
-   the render can complete before the 5 ms timer, and a test that demanded the
-   cancel win would be a flake. What it does NOT tolerate is a raster coming back
-   from a signal that was already cancelled when the draw ended.
-   */
-  func testACancelDuringAnInFlightRenderIsObservedOnlyAfterItFinishes() throws {
-    let r = try openFixture(
-      TestPdfs.grid(width: 1728, height: 2592, pitch: 4), name: "cancel-inflight.pdf")
-    let signal = PdfCanvasCancellation()
-    let started = Date()
-    DispatchQueue.global().asyncAfter(deadline: .now() + 0.005) { signal.cancel() }
-
-    do {
-      let raster = try r.render(
-        request(width: 1728, height: 2592, scale: 2), cancellation: signal, sink: nil)
-      // It finished before the timer. That is a legitimate outcome — and the proof
-      // that the render was not interrupted is that it produced a complete raster.
-      XCTAssertEqual(raster.width, 3456)
-      XCTAssertLessThan(
-        Date().timeIntervalSince(started), 60, "sanity: it did finish")
-    } catch {
-      XCTAssertEqual(PdfCanvasErrorCodeOf(error as NSError), .cancelled)
-      XCTAssertTrue(
-        (error as NSError).localizedDescription.contains("after render")
-          || (error as NSError).localizedDescription.contains("before render")
-          || (error as NSError).localizedDescription.contains("after pool wait"),
-        "a mid-flight cancel can only be seen at a checkpoint: "
-          + (error as NSError).localizedDescription)
-    }
-    r.close()
-  }
-
-  /**
-   A cancel is per-signal: cancelling one render does not affect another.
-
-   Trivial to get wrong if the flag ever moves onto the rasterizer, which is where
-   it would be tempting to put it.
-   */
-  func testCancellationIsPerSignal() throws {
-    let r = try grid("cancel-per-signal.pdf", poolSize: 2)
-    let cancelled = PdfCanvasCancellation()
-    cancelled.cancel()
-    let live = PdfCanvasCancellation()
-
-    XCTAssertThrowsError(
-      try r.render(
-        request(width: 100, height: 100, scale: 1), cancellation: cancelled,
-        sink: nil))
-    XCTAssertNoThrow(
-      try r.render(
-        request(width: 100, height: 100, scale: 1), cancellation: live, sink: nil))
-    r.close()
-  }
-
-  // ---------------------------------------------------------------- //
-  // The pool
-  // ---------------------------------------------------------------- //
-
-  /**
-   N lanes really do render concurrently, and every result is correct.
-
-   The correctness half matters more than the concurrency half: two lanes drawing
-   from two `CGPDFDocumentRef`s over the same file is the arrangement that would go
-   wrong if the pool handed the same document to both. Every tile is compared
-   against the same tile rendered serially, so a lane that produced a torn or
-   half-drawn raster would fail rather than merely be slow.
-   */
-  func testEveryLaneProducesTheSamePixelsAsASerialRender() throws {
-    let data = TestPdfs.grid(width: 600, height: 800)
-    let serial = try openFixture(data, name: "lanes-serial.pdf", poolSize: 1)
-    let tiles: [(Double, Double)] = [
-      (0, 0), (100, 0), (200, 0), (0, 100), (100, 100), (200, 100),
-      (300, 200), (400, 300),
-    ]
-    var expected: [String: [UInt8]] = [:]
-    for (x, y) in tiles {
-      let raster = try serial.render(
-        request(x: x, y: y, width: 100, height: 100, scale: 2),
-        cancellation: nil, sink: nil)
-      expected["\(x),\(y)"] = Array(raster.bytes!)
-    }
-    serial.close()
-
-    let parallel = try openFixture(data, name: "lanes-parallel.pdf", poolSize: 4)
-    XCTAssertEqual(parallel.poolSize, 4)
-    let lock = NSLock()
-    var failures: [String] = []
-    DispatchQueue.concurrentPerform(iterations: tiles.count * 3) { index in
-      let (x, y) = tiles[index % tiles.count]
-      do {
-        let raster = try parallel.render(
-          request(x: x, y: y, width: 100, height: 100, scale: 2),
-          cancellation: nil, sink: nil)
-        let bytes = Array(raster.bytes!)
-        lock.lock()
-        if bytes != expected["\(x),\(y)"] {
-          failures.append("tile \(x),\(y) differs from the serial render")
-        }
-        lock.unlock()
-      } catch {
-        lock.lock()
-        failures.append("tile \(x),\(y) failed: \(error)")
-        lock.unlock()
-      }
-    }
-    XCTAssertEqual(failures, [], "concurrent renders must match the serial ones")
-    parallel.close()
-  }
-
-  /**
-   A one-lane pool SERIALISES rather than failing, and every render still lands.
-
-   The lease blocks; it does not refuse. That is what lets the controller schedule
-   more items than there are lanes without knowing how many there are.
-   */
-  func testAOneLanePoolSerialisesRatherThanFailing() throws {
-    let r = try grid("one-lane.pdf", poolSize: 1)
-    XCTAssertEqual(r.poolSize, 1)
-    let lock = NSLock()
-    var completed = 0
-    DispatchQueue.concurrentPerform(iterations: 12) { _ in
-      if let raster = try? r.render(
-        request(width: 80, height: 80, scale: 1), cancellation: nil, sink: nil),
-        raster.width == 80
-      {
-        lock.lock()
-        completed += 1
-        lock.unlock()
-      }
-    }
-    XCTAssertEqual(completed, 12, "every render must land, one at a time")
-    r.close()
-  }
-
-  /**
-   PDFKit renders concurrently too, and each lane opens its OWN `PDFDocument`.
-
-   The lazy PDFKit document is per-lane, so this is where a shared one would show
-   up. `PDFDocument` is not documented thread-safe and the failure mode would be
-   intermittent — which is exactly the kind of thing to pin while it is cheap.
-   */
-  func testPdfKitRendersConcurrentlyPerLane() throws {
-    let r = try openFixture(
-      TestPdfs.annotatedPage(), name: "pdfkit-lanes.pdf", poolSize: 4)
-    let lock = NSLock()
-    var greens = 0
-    DispatchQueue.concurrentPerform(iterations: 16) { _ in
-      if let raster = try? r.render(
-        request(width: 200, height: 200, scale: 1, annotations: true),
-        cancellation: nil, sink: nil)
-      {
-        let p = raster.pixel(100, 100)
-        lock.lock()
-        if p.isNear(.green) { greens += 1 }
-        lock.unlock()
-      }
-    }
-    XCTAssertEqual(greens, 16, "every lane must composite the annotation")
-    r.close()
-  }
-
-  // ---------------------------------------------------------------- //
-  // Close
-  // ---------------------------------------------------------------- //
-
-  /**
-   CLOSING WHILE A RENDER IS IN FLIGHT IS SAFE, and this is the test Android cannot
-   write.
-
-   `PdfRendererPool.close()` closes every renderer including leased ones, and its
-   own comment calls that "the only honest option" — blocking `close()` until an
-   in-flight ARCH-D render finishes is worse. It leaves a window.
-
-   There is no window here: a lease OWNS a CoreFoundation reference to its document,
-   so `close` dropping the pool's references cannot free a document a worker is
-   still drawing from. The worker's render either completes normally or fails with
-   `backend-failure`; what it must never do is crash. Run enough times to make a
-   use-after-free likely if one existed.
-   */
-  func testClosingWhileRendersAreInFlightIsSafe() throws {
-    for attempt in 0..<8 {
-      let r = try openFixture(
-        TestPdfs.grid(width: 1728, height: 2592, pitch: 4),
-        name: "close-race-\(attempt).pdf", poolSize: 4)
-      let group = DispatchGroup()
-      for lane in 0..<8 {
-        DispatchQueue.global().async(group: group) {
-          // Either outcome is fine. A crash is not.
-          _ = try? r.render(
-            request(
-              x: Double(lane) * 100, y: 0, width: 400, height: 400, scale: 3),
-            cancellation: nil, sink: nil)
-        }
-      }
-      // Close while they are very likely still drawing.
-      Thread.sleep(forTimeInterval: 0.002)
-      r.close()
-      XCTAssertEqual(
-        group.wait(timeout: .now() + 30), .success,
-        "renders should finish or fail, never hang")
-      XCTAssertTrue(r.isClosed)
-    }
-  }
-
-  /**
-   `close` does not block on an in-flight render.
-
-   The whole reason the leased document is left alive rather than freed: `close`
-   comes from JS when a document unmounts, and a JS thread waiting on an ARCH-D
-   raster is a frozen app.
-   */
-  func testCloseDoesNotBlockOnAnInFlightRender() throws {
-    let r = try openFixture(
-      TestPdfs.grid(width: 1728, height: 2592, pitch: 4), name: "close-nonblock.pdf",
-      poolSize: 1)
-    let group = DispatchGroup()
-    DispatchQueue.global().async(group: group) {
-      _ = try? r.render(
-        request(width: 1728, height: 2592, scale: 3), cancellation: nil, sink: nil)
-    }
-    Thread.sleep(forTimeInterval: 0.005)
-    let started = Date()
-    r.close()
-    let elapsed = Date().timeIntervalSince(started)
-    XCTAssertLessThan(
-      elapsed, 0.5,
-      "close took \(elapsed * 1000)ms, which means it waited for the render")
-    _ = group.wait(timeout: .now() + 60)
-  }
-
-  /**
-   A render that starts AFTER close fails rather than blocking forever.
-
-   The semaphore accounting is the thing being pinned: `close` empties the free
-   list without signalling, so a naive implementation leaves a later `lease` waiting
-   on a count that will never come.
-   */
-  func testRendersAfterCloseFailPromptly() throws {
-    let r = try grid("after-close.pdf", poolSize: 2)
-    r.close()
-    let done = expectation(description: "renders return")
-    done.expectedFulfillmentCount = 4
-    for _ in 0..<4 {
-      DispatchQueue.global().async {
-        // `try?` rather than XCTAssertThrowsError: the assertion helper is not
-        // usable from a non-throwing block, and what matters here is that the call
-        // RETURNS at all — a hang is the failure mode being tested for.
-        let raster = try? r.render(
-          request(width: 50, height: 50, scale: 1), cancellation: nil, sink: nil)
-        XCTAssertNil(raster, "a render after close must fail")
-        done.fulfill()
-      }
-    }
-    wait(for: [done], timeout: 5)
-  }
-
-  /**
-   A lane blocked waiting for the pool when `close` lands returns rather than
-   hanging.
-
-   The one ordering the semaphore has to get right, and the reason `leaseWithError`
-   signals the count back before failing: with one lane held and one waiter, a
-   `close` plus the held lane's return has to wake the waiter and let it error out.
-   */
-  func testALaneWaitingWhenCloseLandsReturns() throws {
-    let r = try openFixture(
-      TestPdfs.grid(width: 1728, height: 2592, pitch: 4), name: "waiter.pdf",
-      poolSize: 1)
-    let holding = expectation(description: "the first render finishes")
-    let waiting = expectation(description: "the queued render returns")
-    DispatchQueue.global().async {
-      _ = try? r.render(
-        request(width: 1728, height: 2592, scale: 3), cancellation: nil, sink: nil)
-      holding.fulfill()
-    }
-    Thread.sleep(forTimeInterval: 0.003)
-    DispatchQueue.global().async {
-      // Blocks on the semaphore behind the render above.
-      _ = try? r.render(
-        request(width: 100, height: 100, scale: 1), cancellation: nil, sink: nil)
-      waiting.fulfill()
-    }
-    Thread.sleep(forTimeInterval: 0.002)
-    r.close()
-    wait(for: [holding, waiting], timeout: 60)
-  }
-}