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