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

terminal: ?std.fs.File = undefined,

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,
timer: ?std.time.Timer = null,

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.

refresh_rate_ns: u64 = 50 * std.time.ns_per_ms,

How many nanoseconds between writing updates to the terminal.

initial_delay_ns: u64 = 500 * std.time.ns_per_ms,

How many nanoseconds to keep the output hidden

done: bool = true,
update_mutex: std.Thread.Mutex = .{ },

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.

Types

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 log(self: *Progress, comptime format: []const u8, args: anytype) void

No documentation provided.

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.

fn unlock_stderr(p: *Progress) void

No documentation provided.