1notcurses_stats(3) notcurses_stats(3)
2
6 notcurses_stats - notcurses runtime statistics
7
9 #include <notcurses/notcurses.h>
10 typedef struct ncstats {
12 // purely increasing stats
13 uint64_t renders; // successful ncpile_render() runs
14 uint64_t writeouts; // successful ncpile_rasterize() runs
15 uint64_t failed_renders; // aborted renders, should be 0
16 uint64_t failed_writeouts; // aborted writes
17 uint64_t render_bytes; // bytes emitted to ttyfp
18 int64_t render_max_bytes; // max bytes emitted for a frame
19 int64_t render_min_bytes; // min bytes emitted for a frame
20 uint64_t render_ns; // nanoseconds spent rendering
21 int64_t render_max_ns; // max ns spent for a frame
22 int64_t render_min_ns; // min ns spent for a frame
23 uint64_t raster_ns; // nanoseconds spent rasterizing
24 int64_t raster_max_ns; // max ns spent in raster for a frame
25 int64_t raster_min_ns; // min ns spent in raster for a frame
26 uint64_t writeout_ns; // ns spent writing frames to terminal
27 int64_t writeout_max_ns; // max ns spent writing out a frame
28 int64_t writeout_min_ns; // min ns spent writing out a frame
29 uint64_t cellelisions; // cells elided entirely
30 uint64_t cellemissions; // cells emitted
31 uint64_t fgelisions; // RGB fg elision count
32 uint64_t fgemissions; // RGB fg emissions
33 uint64_t bgelisions; // RGB bg elision count
34 uint64_t bgemissions; // RGB bg emissions
35 uint64_t defaultelisions; // default color was emitted
36 uint64_t defaultemissions; // default color was elided
37 uint64_t refreshes; // refreshes (unoptimized redraws)
38 // current state -- these can decrease
40 uint64_t fbbytes; // bytes devoted to framebuffers
41 unsigned planes; // planes currently in existence
42 } ncstats;
43 ncstats* notcurses_stats_alloc(struct notcurses* nc);
45 void notcurses_stats(struct notcurses* nc, ncstats* stats);
47 void notcurses_stats_reset(struct notcurses* nc, ncstats* stats);
49
51 notcurses_stats_alloc allocates an ncstats object. This should be used
52 rather than allocating the object in client code, to future-proof
53 against the struct being enlarged by later Notcurses versions.
54 notcurses_stats acquires an atomic snapshot of statistics, primarily
56 related to notcurses_render(3). notcurses_stats_reset does the same,
57 but also resets all cumulative stats (immediate stats such as fbbytes
58 are not reset).
59 renders is the number of successful calls to notcurses_render(3) or
61 notcurses_render_to_buffer(3). failed_renders is the number of unsuc‐
62 cessful calls to these functions. failed_renders should be 0; renders
63 are not expected to fail except under exceptional circumstances.
64 should notcurses_render(3) fail while writing out a frame to the termi‐
65 nal, it counts as a failed render.
66 render_max_bytes and render_min_bytes track the maximum and minimum
68 number of bytes used rasterizing a frame. A given state of Notcurses
69 does not correspond to a unique number of bytes; the size is also de‐
70 pendent on the existing terminal state. As a first approximation, the
71 time a terminal takes to ingest and reflect a frame is dependent on the
72 size of the rasterized frame.
73 render_ns, render_max_ns, and render_min_ns track the total amount of
75 time spent rendering frames in nanoseconds. Rendering takes place in
76 ncpile_render (called by notcurses_render(3) and notcurses_ren‐
77 der_to_buffer). This step is independent of the terminal.
78 raster_ns, raster_max_ns, and raster_min_ns track the total amount of
80 time spent rasterizing frames in nanoseconds. Rasterizing takes place
81 in ncpile_raster (called by notcurses_raster(3) and notcurses_ren‐
82 der_to_buffer). This step depends on the terminal definitions. The
83 same frame might not rasterize to the same bytes for different termi‐
84 nals.
85 writeout_ns, writeout_max_ns, and writeout_min_ns track the total
87 amount of time spent writing frames to the terminal. This takes place
88 in ncpile_rasterize (called by notcurses_render(3)).
89 cellemissions reflects the number of EGCs written to the terminal.
91 cellelisions reflects the number of cells which were not written, due
92 to damage detection.
93 refreshes is the number of times notcurses_refresh has been successful‐
95 ly executed.
96 fbbytes is the total number of bytes devoted to framebuffers throughout
98 the struct notcurses context. planes is the number of planes in the
99 context. Neither of these stats can reach 0, due to the mandatory
100 standard plane.
101
103 Unsuccessful render operations do not contribute to the render timing
104 stats.
105
107 Neither notcurses_stats nor notcurses_stats_reset can fail. Neither
108 returns any value. notcurses_stats_alloc returns a valid ncstats ob‐
109 ject on success, or NULL on failure.
110
112 notcurses(3), notcurses_render(3)
113
115 nick black <nickblack@linux.com>.
116 v2.2.3 notcurses_stats(3)