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 uint64_t sprixelemissions; // sprixel draw count
39 uint64_t sprixelelisions; // sprixel elision count
40 // current state -- these can decrease
42 uint64_t fbbytes; // bytes devoted to framebuffers
43 unsigned planes; // planes currently in existence
44 } ncstats;
45 ncstats* notcurses_stats_alloc(struct notcurses* nc);
47 void notcurses_stats(struct notcurses* nc, ncstats* stats);
49 void notcurses_stats_reset(struct notcurses* nc, ncstats* stats);
51
53 notcurses_stats_alloc allocates an ncstats object. This should be used
54 rather than allocating the object in client code, to future-proof
55 against the struct being enlarged by later Notcurses versions.
56 notcurses_stats acquires an atomic snapshot of statistics, primarily
58 related to notcurses_render(3). notcurses_stats_reset does the same,
59 but also resets all cumulative stats (immediate stats such as fbbytes
60 are not reset).
61 renders is the number of successful calls to notcurses_render(3) or
63 notcurses_render_to_buffer(3). failed_renders is the number of unsuc‐
64 cessful calls to these functions. failed_renders should be 0; renders
65 are not expected to fail except under exceptional circumstances.
66 should notcurses_render(3) fail while writing out a frame to the termi‐
67 nal, it counts as a failed render.
68 render_max_bytes and render_min_bytes track the maximum and minimum
70 number of bytes used rasterizing a frame. A given state of Notcurses
71 does not correspond to a unique number of bytes; the size is also de‐
72 pendent on the existing terminal state. As a first approximation, the
73 time a terminal takes to ingest and reflect a frame is dependent on the
74 size of the rasterized frame.
75 render_ns, render_max_ns, and render_min_ns track the total amount of
77 time spent rendering frames in nanoseconds. Rendering takes place in
78 ncpile_render (called by notcurses_render(3) and notcurses_ren‐
79 der_to_buffer). This step is independent of the terminal.
80 raster_ns, raster_max_ns, and raster_min_ns track the total amount of
82 time spent rasterizing frames in nanoseconds. Rasterizing takes place
83 in ncpile_raster (called by notcurses_raster(3) and notcurses_ren‐
84 der_to_buffer). This step depends on the terminal definitions. The
85 same frame might not rasterize to the same bytes for different termi‐
86 nals.
87 writeout_ns, writeout_max_ns, and writeout_min_ns track the total
89 amount of time spent writing frames to the terminal. This takes place
90 in ncpile_rasterize (called by notcurses_render(3)).
91 cellemissions reflects the number of EGCs written to the terminal.
93 cellelisions reflects the number of cells which were not written, due
94 to damage detection.
95 refreshes is the number of times notcurses_refresh has been successful‐
97 ly executed.
98 fbbytes is the total number of bytes devoted to framebuffers throughout
100 the struct notcurses context. planes is the number of planes in the
101 context. Neither of these stats can reach 0, due to the mandatory
102 standard plane.
103 sprixelemissions is the number of sprixel draws. sprixelelisions is
105 the number of times a sprixel was elided--essentially, the number of
106 times a sprixel appeared in a rendered frame without freshly drawing
107 it.
108
110 Unsuccessful render operations do not contribute to the render timing
111 stats.
112
114 Neither notcurses_stats nor notcurses_stats_reset can fail. Neither
115 returns any value. notcurses_stats_alloc returns a valid ncstats ob‐
116 ject on success, or NULL on failure.
117
119 notcurses(3), notcurses_render(3)
120
122 nick black <nickblack@linux.com>.
123 v2.3.1 notcurses_stats(3)