This API non-allocating, non-fallible, and thread-safe. The tradeoff is that users of this API must provide the storage for each Progress.Node
.
Initialize the struct directly, overriding these fields as desired:
refresh_rate_ms
initial_delay_ms
Fields
null
if the current node (and its children) should not print on update()
is_windows_terminal: bool = false,
Is this a windows API terminal (note: this is not the same as being run on windows because other terminals exist like MSYS/git-bash)
supports_ansi_escape_codes: bool = false,
Whether the terminal supports ANSI escape codes.
dont_print_on_dumb: bool = false,
If the terminal is “dumb”, don’t print output. This can be useful if you don’t want to print all the stages of code generation if there are a lot. You should not use it if the user should see output for example showing the user what tests run.
root: Node = undefined,
Keeps track of how much time has passed since the beginning. Used to compare with initial_delay_ms
and refresh_rate_ms
.
prev_refresh_timestamp: u64 = undefined,
When the previous refresh was written to the terminal. Used to compare with refresh_rate_ms
.
output_buffer: [100]u8 = undefined,
This buffer represents the maximum number of bytes written to the terminal with each refresh.
How many nanoseconds between writing updates to the terminal.
done: bool = true,
Protects the refresh
function, as well as node.recently_updated_child
. Without this, callsites would call Node.end
and then free Node
memory while it was still being accessed by the refresh
function.
columns_written: usize = undefined,
Keeps track of how many columns in the terminal have been output, so that we can move the cursor back later.
Functions
fn lock_stderr(p: *Progress) void
Allows the caller to freely write to stderr until unlock_stderr() is called. Du…
Allows the caller to freely write to stderr until unlock_stderr() is called. During the lock, the progress information is cleared from the terminal.
fn maybeRefresh(self: *Progress) void
Updates the terminal if enough time has passed since last update. Thread-safe.
fn refresh(self: *Progress) void
Updates the terminal and resets
self.next_refresh_timestamp
. Thread-safe.fn start(self: *Progress, name: []const u8, estimated_total_items: usize) *Node
Create a new progress node. Call
Node.end
when done. TODO solve https://gith…Create a new progress node. Call
Node.end
when done. TODO solve https://github.com/ziglang/zig/issues/2765 and then change this API to return Progress rather than accept it as a parameter.estimated_total_items
value of 0 means unknown.