Files
RetroArch/tasks/task_content_prefetch.h
LibretroAdmin 0315b872a4 gfx_widgets: show read progress in the "Load Content" notification
Second half of the load progress work.  The prefetch task reports a
read percentage; this puts it on screen, after the content name, in
the launch notification that already exists.

The notification used to fire AFTER retroarch_main_init() returned
true - a card celebrating a load that had already happened, which
cannot show progress for it.  On the deferred path, where the
content streams in ahead of the load while the frontend keeps
running, it now starts when the read is pushed instead, carries the
percentage as the bytes arrive, and is left alone by the post-init
site rather than being restarted there.  The percentage is cleared
once the read is over, so the card finishes as the plain launch
notification it has always been.  Display widgets persist across
driver reinits by default, so the card started before the load
survives into the loaded core.

Gating is unchanged and is the setting's existing meaning: with
"Load Content" startup notification off, nothing is shown and no
progress is even reported - the prefetch task takes a NULL progress
callback and never calls it.  Loads that do not defer - a bare
archive, a content:// URI, anything with argv - are untouched and
still get the post-init card with no percentage.

The percentage is the READ only.  Core init, SRAM and shader setup
follow it, so it reaches 100 before the load is finished rather than
tracking the whole operation.  That is honest for what it measures
and matches where the time actually goes on a large ROM, but it does
mean the last stretch sits at 100 - phase weighting, if wanted, is a
follow-up rather than something to fake here.

The oracle gains two lanes for the callback path, which is separate
from the task's progress field: a caller that never sees a callback
shows nothing however correct the field is.  One asserts several
updates arrive, in order, with an intermediate value, ending at 100;
the other that a NULL callback is accepted and never called, which
is what every existing caller passes.

Verified: strict C89 gates on all three touched translation units;
full Linux build links with HAVE_QT=1; all eight oracle lanes pass
plain, under ASan+UBSan+LSan and under TSan, repeated in each
flavor; the gfx_widgets sanitize and msg-queue-race samples still
pass.

Not verified here, and worth a look on real hardware: how the card
reads across the driver reinit in the middle of a load, and whether
the percentage wants phase weighting.  Neither can be judged from a
build.
2026-08-15 19:59:27 +02:00

74 lines
3.5 KiB
C

/* Copyright (C) 2010-2026 The RetroArch team
*
* ---------------------------------------------------------------------
* The following license statement only applies to this file (task_content_prefetch.h).
* ---------------------------------------------------------------------
*
* Permission is hereby granted, free of charge,
* to any person obtaining a copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
* and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#ifndef TASK_CONTENT_PREFETCH_H
#define TASK_CONTENT_PREFETCH_H
#include <stdint.h>
#include <stddef.h>
#include <boolean.h>
#include <retro_common_api.h>
RETRO_BEGIN_DECLS
/* Reads the bytes of a set of content paths ahead of the load, a
* byte-budgeted slice per task tick, so a large ROM - plain or a ZIP
* entry decompressing as it is read - streams in while the frontend
* keeps running, instead of freezing it for one long gulp.
*
* Paths may be plain files or "archive#entry". The reads happen on
* whatever thread the task queue runs handlers on - the worker
* thread, under the threaded queue. Delivery happens later, in one
* batch, from the task's completion callback: every deposit
* (ownership of the exact-size free()able buffer transfers), then
* done, exactly once, both invoked from task_queue_check() on the
* thread that pumps the queue. Neither callback may reenter the
* task system or run anything that reinitializes it (content_load()
* does, via retroarch_init_task_queue()) - park such work and
* perform it from the runloop. A path that cannot be prefetched (a
* 7z solid block, a vanished file) is simply skipped - the load's
* ordinary read path remains the authority, and a missing deposit
* costs a blocking read, not correctness. Same for cancellation:
* buffers already completed still deposit, the rest never arrive. */
typedef void (*content_prefetch_deposit_t)(void *ud, const char *path,
uint8_t *data, size_t size);
typedef void (*content_prefetch_done_t)(void *ud, bool all_ok);
/* Called on the thread pumping the queue whenever the whole-number
* read percentage changes, so a caller can show it. Optional: NULL
* means nobody is watching and nothing is reported. */
typedef void (*content_prefetch_progress_t)(void *ud, int8_t progress);
bool task_push_content_prefetch(const char **paths, size_t count,
content_prefetch_deposit_t deposit, content_prefetch_done_t done,
void *ud);
/* As above, with progress reporting. */
bool task_push_content_prefetch_progress(const char **paths,
size_t count, content_prefetch_deposit_t deposit,
content_prefetch_done_t done,
content_prefetch_progress_t progress, void *ud);
RETRO_END_DECLS
#endif