Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-canvas

Source of release 0.5.1

0.5.1 / src / tiles / prefetch.lucb

#==============================================================================================
#
#   tiles/prefetch - Tiles brought back in the background while frames go on
#
#   DESCRIPTION:
#       Gathering (tiles/gathering) brings a batch of tiles back at once, but the frame that
#       asked waits for it. A frame that must not wait hands the tiles it lacks to
#       `prefetch_tiles` instead and draws something coarser meanwhile: their compressed
#       bytes are read here (a document file's records, a compressed scratch slot, or a
#       copy of a compressed tile in RAM, each a small read) and decoded on worker threads,
#       and a later frame's `prefetch_collect` gives each tile its decoded copy. One batch
#       is in flight at a time. Tiles live on the main thread, so the workers see only the
#       bytes and the decoder: each tile is held while its batch is out, and a tile drawn
#       into meanwhile (a new stamp) or already back keeps what it has.
#
#==============================================================================================

## One tile decoding on a worker.
struct Pending:
    var tile: Tile*
    var stamp: u64
    var packed: u8[]
    var copy: u8[]
    var decode: TileDecode
    var context: void*?
    var rows: u32
    var backed: bool
    var failed: bool

## A batch of tiles decoding in the background.
struct Prefetch:
    var storage: Pending[]
    var items: Pending[]
    ## The pool batch decoding the items.
    var job: pool.Job
    ## Items decoded so far: the last one wakes the app.
    var decoded: @usize

var in_flight: Prefetch*? = none
## Whether the last batch collected had a tile that could not be decoded.
var prefetch_failed: bool = false

## Whether a batch is out.
pub func prefetch_pending() -> bool:
    return in_flight != none

## Whether the last batch collected had a tile that did not decode: the
## caller brings what it lacks back itself, so the failure is reported.
pub func prefetch_had_failure() -> bool:
    return prefetch_failed

## Start bringing `list`'s tiles that only have compressed copies (in RAM, in
## the scratch file or in a document file) back in the background; tiles
## whose scratch slot holds them whole are left to be read when asked for.
## False when a batch is already out (ask again once it is collected).
pub func prefetch_tiles(list: Tile*[]) -> bool!:
    if in_flight != none:
        return false
    var count: usize = 0
    for tile in list:
        if prefetchable(tile):
            count += 1
    if count == 0:
        return true
    let storage = try new Pending[count] --- in memory.heap
    let batch = try new Prefetch(storage = storage, items = storage, job = pool.Job()) in memory.heap
    batch.decoded.store(0, .relaxed)
    var at: usize = 0
    for tile in list:
        if at == count or not prefetchable(tile):
            continue
        # One that cannot be read now is left to be brought back when asked for,
        # which reports why.
        batch.items[at] = pending_for(tile) catch failure:
            _ = failure
            continue
        at += 1
    try start_batch(batch, at)
    return true

## Whether `tile` is only somewhere a worker can decode it from.
func prefetchable(tile: const Tile*) -> bool:
    if tile.on_gpu or tile.ram.length > 0 or tile.loading:
        return false
    if tile.packed.length > 0:
        return codec_decode != none
    if tile.disk >= 0:
        return tile.disk_length > 0 and codec_decode != none
    return backed(tile)

## `tile`'s compressed bytes, read (or copied) now, and how to decode them.
func pending_for(tile: Tile*) -> Pending!:
    var no_bytes: u8[]
    var item = Pending(tile = tile, stamp = tile.stamp, packed = no_bytes, copy = no_bytes, decode = codec_decode else unpackable,
                       context = codec_context, rows = tile_size, backed = false, failed = false)
    if tile.packed.length > 0:
        item.packed = try new u8[tile.packed.length] --- in memory.heap
        memory.copy(item.packed, tile.packed, tile.packed.length)
    elif tile.disk >= 0:
        item.packed = try new u8[(usize)tile.disk_length] --- in memory.heap
        let file = try scratch_file()
        _ = try file.seek(tile.disk)
        var read: usize = 0
        while read < item.packed.length:
            let count = try file.read(item.packed[read..])
            if count == 0:
                error(invalid, "the scratch file ended inside a tile")
            read += count
    else:
        let source = tile.source else trap("a backed tile has its source")
        item.packed = try new u8[(usize)tile.source_length] --- in memory.heap
        try read_record(source, tile.source_offset, item.packed)
        item.decode = source.decode
        item.context = source.context
        item.rows = tile.source_rows
        item.backed = true
    errdefer free(item.packed) in memory.heap
    item.copy = try new u8[tile_bytes] --- in memory.heap
    memory.set(item.copy, 0)
    # Marked so another batch does not take it too.
    tile.loading = true
    _ = retain(tile)
    return item

func unpackable(context: void*?, packed: const u8[], rows: u32, into: u8[]) -> !:
    _ = context
    _ = packed
    _ = rows
    _ = into
    error(invalid, "a compressed tile came back without a codec")

## The batch's first `count` items to up to eight of the pool's workers.
func start_batch(batch: Prefetch*, count: usize) -> !:
    let items = batch.items
    batch.items = items[..<count]
    in_flight = batch
    if count == 0:
        wake_frames()
        return
    pool.start(&batch.job, count, prefetch_item, (void*)batch, limit = min_usize(8, max_usize(1, (usize)os.cpus() - 1)))

func prefetch_item(context: void*?, index: usize):
    let batch = (Prefetch*)(context else return)
    let item = &batch.items[index]
    item.decode(item.context, item.packed, item.rows, item.copy) catch failure:
        _ = failure
        item.failed = true
    # The last item done: the app's loop may be asleep until input, so ask it
    # for the frame that collects the batch.
    if batch.decoded.add(1, .acq_rel) + 1 == batch.items.length:
        wake_frames()

## If the batch out has finished, give its tiles their decoded copies; whether
## any tile came back.
pub func prefetch_collect() -> bool!:
    let batch = in_flight else return false
    if not pool.finished(&batch.job):
        return false
    return try finish_batch(batch)

## Wait for the batch out, if any, and collect it: tests, and letting go of
## everything (a document closing).
pub func prefetch_wait() -> !:
    let batch = in_flight else return
    _ = try finish_batch(batch)

func finish_batch(batch: Prefetch*) -> bool!:
    in_flight = none
    pool.wait(&batch.job)
    var any = false
    prefetch_failed = false
    for index in 0..<batch.items.length:
        let item = &batch.items[index]
        let tile = item.tile
        tile.loading = false
        if item.failed:
            prefetch_failed = true
        elif not tile.on_gpu and tile.ram.length == 0 and tile.stamp == item.stamp and tile.references > 1:
            tile.ram = item.copy
            var taken: u8[]
            item.copy = taken
            ram_tile_bytes += tile_bytes
            if item.backed:
                residency_fetches += 1
            else:
                residency_loads += 1
            any = true
        if item.packed.length > 0:
            free(item.packed) in memory.heap
        if item.copy.length > 0:
            free(item.copy) in memory.heap
        release(tile)
    let storage = batch.storage
    free(storage) in memory.heap
    free(batch) in memory.heap
    return any